On Thu, 02 Jun 2016, Daniel Vetter <[email protected]> wrote: > On Thu, Jun 2, 2016 at 11:39 AM, Daniel Vetter <[email protected]> wrote: >> On Thu, Jun 2, 2016 at 9:16 AM, Jani Nikula <[email protected]> >> wrote: >>> On Thu, 02 Jun 2016, Daniel Vetter <[email protected]> wrote: >>>> Further up in the state machinery we switch from STATE_NAME to >>>> STATE_DOCBLOCK when we match /$doc_block/. Which means this >>>> block of code here is entirely unreachable. >>>> >>>> Nuke it. >>> >>> kernel-doc currently supports multiple DOC: lines in a single kernel-doc >>> comment, and this breaks it. This: >>> >>> /** >>> * DOC: foo >>> * >>> * Foo >>> * >>> * DOC: bar >>> * >>> * Bar >>> */ >>> >>> currently turns into sections foo and bar, with this patch this becomes >>> one section "foo", with literal "DOC: bar" in the content as normal >>> text. >>> >>> I don't know if we actually have that kind of comments anywhere, but >>> since this change doesn't really help you all that much with the >>> follow-up, I'd just drop it. >> >> Fine with me, just wanted to drop the cargo-culting factor a bit. I'm >> too lazy to write a stateful script to check whether we have any place >> that uses the above ;-) If anyone can do this quickly, would be >> awesom. > > I've unlazied and done a full audit using > > git grep -c " * DOC:" | grep -v ":1$" > > and then auditing all the files with more than one DOC: section. They > _all_ use separate comment blocks, even if there's nothing in between > them. Your above example doesn't exist. Can you pls merge my patch?
I did a double check plus a full output comparison before/after with all the tmpl files converted. No differences. And I totally agree having multiple DOC: sections per a kernel-doc comment is not something we should recommend either. KISS. Pushed to my sphinx-for-docs-next branch. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
