scripts/kernel-doc: Add option to inject line numbers

Opt-in since this wreaks the rst output and must be removed
by consumers again. This is useful to adjust the linenumbers
for included kernel-doc

scripts/kernel-doc: Add option to inject line numbers

Opt-in since this wreaks the rst output and must be removed
by consumers again. This is useful to adjust the linenumbers
for included kernel-doc snippets in shinx. With that sphinx
error message will be accurate when there's issues with the
rst-ness of the kernel-doc comments.

Especially when transitioning a new docbook .tmpl to .rst this
is extremely useful, since you can just use your editors compilation
quickfix list to accurately jump from error to error.

v2:
- Also make sure that we filter the LINENO for purpose/at declaration
start so it only shows for selected blocks, not all of them (Jani).
While at it make it a notch more accurate.
- Avoid undefined $lineno issues. I tried filtering these out at the
callsite, but Jani spotted more when linting the entire kernel.
Unamed unions and similar things aren't stored consistently and end
up with an undefined line number (but also no kernel-doc text, just
the parameter type). Simplify things and filter undefined line
numbers in print_lineno() to catch them all.

v3: Fix LINENO 0 issue for kernel-doc comments without @param: lines
or any other special sections that directly jump to the description
after the "name - purpose" line. Only really possible for functions
without parameters. Noticed by Jani.

Cc: Jani Nikula <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Signed-off-by: Jani Nikula <[email protected]>

show more ...

scripts/kernel-doc: Also give functions symbolic names

state3 = prototype parsing, so name them accordingly.

Cc: Jani Nikula <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbe

scripts/kernel-doc: Also give functions symbolic names

state3 = prototype parsing, so name them accordingly.

Cc: Jani Nikula <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Signed-off-by: Jani Nikula <[email protected]>

show more ...

scripts/kernel-doc: Remove duplicated DOC: start handling

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 her

scripts/kernel-doc: Remove duplicated DOC: start handling

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, unless there are multiple DOC:
sections within a single kernel-doc comment.

Getting a list of all the files with more than one DOC: section using

$ git grep -c " * DOC:" | grep -v ":1$"

and then doing a full audit of them reveals there are no such comment
blocks in the kernel.

Supporting multiple DOC: sections in a single kernel-doc comment does
not seem like a recommended way of doing things anyway, so nuke the code
for simplicity.

Cc: Jani Nikula <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
[Jani: amended the commit message]
Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: reset contents and section harder

If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.

Signed-off-by: Jan

kernel-doc: reset contents and section harder

If the documentation comment does not have params or sections, the
section heading may leak from the previous documentation comment.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: concatenate contents of colliding sections

If there are multiple sections with the same section name, the current
implementation results in several sections by the same heading, with the

kernel-doc: concatenate contents of colliding sections

If there are multiple sections with the same section name, the current
implementation results in several sections by the same heading, with the
content duplicated from the last section to all. Even if there's the
error message, a more graceful approach is to combine all the
identically named sections into one, with concatenated contents.

With the supported sections already limited to select few, there are
massively fewer collisions than there used to be, but this is still
useful for e.g. when function parameters are documented in the middle of
a documentation comment, with description spread out above and
below. (This is not a recommended documentation style, but used in the
kernel nonetheless.)

We can now also demote the error to a warning.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: limit the "section header:" detection to a select few

kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by

kernel-doc: limit the "section header:" detection to a select few

kernel-doc currently identifies anything matching "section header:"
(specifically a string of word characters and spaces followed by a
colon) as a new section in the documentation comment, and renders the
section header accordingly.

Unfortunately, this turns all uses of colon into sections, mostly
unintentionally. Considering the output, erroneously creating sections
when not intended is always worse than erroneously not creating sections
when intended. For example, a line with "http://example.com" turns into
a "http" heading followed by "//example.com" in normal text style, which
is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even
if "WARNING" does not turn into a heading.

It is virtually impossible to change all the kernel-doc comments, either
way. The compromise is to pick the most commonly used and depended on
section headers (with variants) and accept them as section headers.

The accepted section headers are, case insensitive:

* description:
* context:
* return:
* returns:

Additionally, case sensitive:

* @return:

All of the above are commonly used in the kernel-doc comments, and will
result in worse output if not identified as section headers. Also,
kernel-doc already has some special handling for all of them, so there's
nothing particularly controversial in adding more special treatment for
them.

While at it, improve the whitespace handling surrounding section
names. Do not consider the whitespace as part of the name.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: remove fixme comment

Yes, for our purposes the type should contain typedef.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc/rst: use *undescribed* instead of _undescribed_

The latter isn't special to rst.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc: strip leading whitespace from continued param descs

If a param description spans multiple lines, check any leading
whitespace in the first continuation line, and remove same amount of
wh

kernel-doc: strip leading whitespace from continued param descs

If a param description spans multiple lines, check any leading
whitespace in the first continuation line, and remove same amount of
whitespace from following lines.

This allows indentation in the multi-line parameter descriptions for
aesthetical reasons while not causing accidentally significant
indentation in the rst output.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: improve handling of whitespace on the first line param description

Handle whitespace on the first line of param text as if it was the empty
string. There is no need to add the newline in

kernel-doc: improve handling of whitespace on the first line param description

Handle whitespace on the first line of param text as if it was the empty
string. There is no need to add the newline in this case. This improves
the rst output in particular, where blank lines may be problematic in
parameter lists.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: change the output layout

Move away from field lists, and simply use **strong emphasis** for
section headings on lines of their own. Do not use rst section headings,
because their nes

kernel-doc/rst: change the output layout

Move away from field lists, and simply use **strong emphasis** for
section headings on lines of their own. Do not use rst section headings,
because their nesting depth depends on the surrounding context, which
kernel-doc has no knowledge of. Also, they do not need to end up in any
table of contexts or indexes.

There are two related immediate benefits. Field lists are typically
rendered in two columns, while the new style uses the horizontal width
better. With no extra indent on the left, there's no need to be as fussy
about it. Field lists are more susceptible to indentation problems than
the new style.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: strip leading blank lines from inline doc comments

The inline member markup allows whitespace lines before the actual
documentation starts. Strip the leading blank lines. This improves t

kernel-doc: strip leading blank lines from inline doc comments

The inline member markup allows whitespace lines before the actual
documentation starts. Strip the leading blank lines. This improves the
rst output.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: blank lines in output are not needed

Current approach leads to two blank lines, while one is enough.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc: fix wrong code indentation

No functional changes.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc: do not regard $, %, or & prefixes as special in section names

The use of these is confusing in the script, and per this grep, they're
not used anywhere anyway:

$ git grep " \* [%$&][a-z

kernel-doc: do not regard $, %, or & prefixes as special in section names

The use of these is confusing in the script, and per this grep, they're
not used anywhere anyway:

$ git grep " \* [%$&][a-zA-Z0-9_]*:" -- *.[ch] | grep -v "\$\(Id\|Revision\|Date\)"

While at it, throw out the constants array, nothing is ever put there
again.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: highlight function/struct/enum purpose lines too

Let the user use @foo, &bar, %baz, etc. in the first kernel-doc purpose
line too.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc/rst: drop redundant unescape in highlighting

This bit is already done by xml_unescape() above.

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc/rst: add support for struct/union/enum member references

Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the
struct/union/enum foo definition. The members themselves do n

kernel-doc/rst: add support for struct/union/enum member references

Link "&foo->bar", "&foo->bar()", "&foo.bar", and "&foo.bar()" to the
struct/union/enum foo definition. The members themselves do not
currently have anchors to link to, but this is better than nothing, and
promotes a universal notation.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: add support for &union foo and &typedef foo references

Let the user use "&union foo" and "&typedef foo" to reference foo. The
difference to using "union &foo", "typedef &foo", or jus

kernel-doc/rst: add support for &union foo and &typedef foo references

Let the user use "&union foo" and "&typedef foo" to reference foo. The
difference to using "union &foo", "typedef &foo", or just "&foo" (which
are valid too) is that "union" and "typedef" become part of the link
text.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: &foo references are more universal than structs

It's possible to use &foo to reference structs, enums, typedefs, etc. in
the Sphinx C domain. Thus do not prefix the links with "struc

kernel-doc/rst: &foo references are more universal than structs

It's possible to use &foo to reference structs, enums, typedefs, etc. in
the Sphinx C domain. Thus do not prefix the links with "struct".

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc/rst: reference functions according to C domain spec

The Sphinx C domain spec says function references should include the
parens ().

Signed-off-by: Jani Nikula <[email protected]>

kernel-doc/rst: do not output DOC: section titles for requested ones

If the user requests a specific DOC: section by name, do not output its
section title. In these cases, the surrounding context al

kernel-doc/rst: do not output DOC: section titles for requested ones

If the user requests a specific DOC: section by name, do not output its
section title. In these cases, the surrounding context already has a
heading, and the DOC: section title is only used as an identifier and a
heading for clarity in the source file.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: add names for output selection

Make the output selection a bit more readable by adding constants for
the various types of output selection. While at it, actually call the
variable for ch

kernel-doc: add names for output selection

Make the output selection a bit more readable by adding constants for
the various types of output selection. While at it, actually call the
variable for choosing what to output $output_selection.

No functional changes.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: add names for states and substates

Make the state machine a bit more readable by adding constants for
parser states and inline member documentation parser substates. While at
it, rename

kernel-doc: add names for states and substates

Make the state machine a bit more readable by adding constants for
parser states and inline member documentation parser substates. While at
it, rename the "split" documentation to "inline" documentation.

No functional changes.

Signed-off-by: Jani Nikula <[email protected]>

show more ...

kernel-doc: support printing exported and non-exported symbols

Currently we use docproc to figure out which symbols are exported, and
then docproc calls kernel-doc on specific functions, to get
docu

kernel-doc: support printing exported and non-exported symbols

Currently we use docproc to figure out which symbols are exported, and
then docproc calls kernel-doc on specific functions, to get
documentation on exported functions. According to git blame and docproc
comments, this is due to historical reasons, as functions and their
corresponding EXPORT_SYMBOL* may have been in different files. However
for more than ten years the recommendation in CodingStyle has been to
place the EXPORT_SYMBOL* immediately after the closing function brace
line.

Additionally, the kernel-doc comments for functions are generally placed
above the function definition in the .c files (i.e. where the
EXPORT_SYMBOL* is) rather than above the declaration in the .h
files. There are some exceptions to this, but AFAICT none of these are
included in DocBook documentation using the "!E" docproc directive.

Therefore, assuming the EXPORT_SYMBOL* and kernel-doc are with the
function definition, kernel-doc can extract the exported vs. not
information by making two passes on the input file. Add support for that
via the new -export and -internal parameters.

Signed-off-by: Jani Nikula <[email protected]>

show more ...