kernel-doc: add support for ____cacheline_aligned_in_smp attribute

Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it

kernel-doc: add support for ____cacheline_aligned_in_smp attribute

Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned_in_smp` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.

Signed-off-by: André Almeida <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: fix processing nested structs with attributes

The current regular expression for strip attributes of structs (and
for nested ones as well) also removes all whitespaces that may
surround

kernel-doc: fix processing nested structs with attributes

The current regular expression for strip attributes of structs (and
for nested ones as well) also removes all whitespaces that may
surround the attribute. After that, the code will split structs and
iterate for each symbol separated by comma at the end of struct
definition (e.g. "} alias1, alias2;"). However, if the nested struct
does not have any alias and has an attribute, it will result in a
empty string at the closing bracket (e.g "};"). This will make the
split return nothing and $newmember will keep uninitialized. Fix
that, by ensuring that the attribute substitution will leave at least
one whitespace.

Signed-off-by: André Almeida <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: Allow anonymous enum

In C is a valid construction to have an anonymous enumerator.

Though we have now:

drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum!

Support i

kernel-doc: Allow anonymous enum

In C is a valid construction to have an anonymous enumerator.

Though we have now:

drivers/pinctrl/intel/pinctrl-intel.c:240: error: Cannot parse enum!

Support it in the kernel-doc script.

Signed-off-by: Andy Shevchenko <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: ignore __printf attribute

Ignore __printf() function attributes just as other __attribute__
strings are ignored.

Fixes this kernel-doc warning message:
include/kunit/kunit-stream.h:58:

kernel-doc: ignore __printf attribute

Ignore __printf() function attributes just as other __attribute__
strings are ignored.

Fixes this kernel-doc warning message:
include/kunit/kunit-stream.h:58: warning: Function parameter or member '2' not described in '__printf'

Reported-by: kbuild test robot <[email protected]>
Signed-off-by: Randy Dunlap <[email protected]>
Cc: Brendan Higgins <[email protected]>
Tested-by: Brendan Higgins <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: Don't try to mark up function names

We now have better automarkup in sphinx itself and, besides, this markup
was incorrect and left :c:func: gunk in the processed docs. Sort of
discoura

kernel-doc: Don't try to mark up function names

We now have better automarkup in sphinx itself and, besides, this markup
was incorrect and left :c:func: gunk in the processed docs. Sort of
discouraging that nobody ever noticed...:)

As a first step toward the removal of impenetrable regex magic from
kernel-doc it's a tiny one, but you have to start somewhere.

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: always name missing kerneldoc sections

The "no structured comments found" warning is not particularly useful if
there are several invocations, one of which is looking for something
wrong

kernel-doc: always name missing kerneldoc sections

The "no structured comments found" warning is not particularly useful if
there are several invocations, one of which is looking for something
wrong. So if something specific has been requested, make it clear that
it's the one we weren't able to find.

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: suppress 'not described' warnings for embedded struct fields

The ability to add kerneldoc comments for fields in embedded structures is
useful, but it brought along a whole bunch of warn

kernel-doc: suppress 'not described' warnings for embedded struct fields

The ability to add kerneldoc comments for fields in embedded structures is
useful, but it brought along a whole bunch of warnings for fields that
could not be described before. In many cases, there's little value in
adding docs for these nested fields, and in cases like:

struct a {
struct b {
int c;
} d, e;
};

"c" would have to be described twice (as d.c and e.c) to make the warnings
go away.

We can no doubt do something smarter, but simply suppressing the warnings
for this case removes about 70 warnings from the docs build, freeing us to
focus on the ones that matter more. So make kerneldoc be silent about
missing descriptions for any field containing a ".".

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts/kernel-doc: Fix struct and struct field attribute processing

The kernel-doc attempts to clear the struct and struct member attributes
from the API documentation it produces. It falls short o

scripts/kernel-doc: Fix struct and struct field attribute processing

The kernel-doc attempts to clear the struct and struct member attributes
from the API documentation it produces. It falls short of the job in the
following respects:

- extra whitespaces are left where __attribute__((...)) was removed,

- only a single attribute is removed per struct,

- attributes (such as aligned) containing numbers were not removed,

- attributes are only cleared from struct fields, not structs themselves.

This patch addresses these issues by removing the attributes.

Signed-off-by: Sakari Ailus <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: extend $type_param to match members referenced by pointer

Currently, function parameter description can match '@type.member'
expressions but fails to match '@type->member'.
Extend the $t

kernel-doc: extend $type_param to match members referenced by pointer

Currently, function parameter description can match '@type.member'
expressions but fails to match '@type->member'.
Extend the $type_param regex to allow matching both

Signed-off-by: Mike Rapoport <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: kill trailing whitespace

Signed-off-by: Mike Rapoport <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

kernel-doc: fix declaration type determination

Make declaration type determination more robust.

When scripts/kernel-doc is deciding if some kernel-doc notation
contains an enum, a struct, a union,

kernel-doc: fix declaration type determination

Make declaration type determination more robust.

When scripts/kernel-doc is deciding if some kernel-doc notation
contains an enum, a struct, a union, a typedef, or a function,
it does a pattern match on the beginning of the string, looking
for a match with one of "struct", "union", "enum", or "typedef",
and otherwise defaults to a function declaration type.
However, if a function or a function-like macro has a name that
begins with "struct" (e.g., struct_size()), then kernel-doc
incorrectly decides that this is a struct declaration.

Fix this by looking for the declaration type keywords having an
ending word boundary (\b), so that "struct_size" will not match
a struct declaration.

I compared lots of html before/after output from core-api, driver-api,
and networking. There were no differences in any of the files that
I checked.

Signed-off-by: Randy Dunlap <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Tested-by: Kees Cook <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts/kernel-doc: Escape all literal braces in regexes

Commit 701b3a3c0ac4 ("PATCH scripts/kernel-doc") fixed the two
instances of literal braces that Perl 5.28 warns about, but there are
still mo

scripts/kernel-doc: Escape all literal braces in regexes

Commit 701b3a3c0ac4 ("PATCH scripts/kernel-doc") fixed the two
instances of literal braces that Perl 5.28 warns about, but there are
still more than it doesn't warn about.

Escape all left braces that are treated as literal characters. Also
escape literal right braces, for consistency and to avoid confusing
bracket-matching in text editors.

Signed-off-by: Ben Hutchings <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

PATCH scripts/kernel-doc

Fix a warning whinge from Perl introduced by "scripts: kernel-doc: parse next structs/unions"

Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.

PATCH scripts/kernel-doc

Fix a warning whinge from Perl introduced by "scripts: kernel-doc: parse next structs/unions"

Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE [^\{\}]*})/ at ./scripts/kernel-doc line 1155.
Unescaped left brace in regex is deprecated here (and will be fatal in Perl 5.32), passed through in regex; marked by <-- HERE in m/({ <-- HERE )/ at ./scripts/kernel-doc line 1179.

Signed-off-by: Valdis Kletnieks <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: kernel-doc: fix parsing of arrays

The logic with parses array has a bug that prevents it to
parse arrays like:
struct {
...
struct {
u64 msdu[IEEE80211_NUM_TIDS + 1];
...
...

Fix t

docs: kernel-doc: fix parsing of arrays

The logic with parses array has a bug that prevents it to
parse arrays like:
struct {
...
struct {
u64 msdu[IEEE80211_NUM_TIDS + 1];
...
...

Fix the parser to accept it.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kernel-doc: Remove __sched markings

I find the __sched annotations unaesthetic in the kernel-doc. Remove
them like we remove __inline, __weak, __init and so on.

Signed-off-by: Matthew Wilcox <mawi

kernel-doc: Remove __sched markings

I find the __sched annotations unaesthetic in the kernel-doc. Remove
them like we remove __inline, __weak, __init and so on.

Signed-off-by: Matthew Wilcox <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Add an SPDX header to kernel-doc

Add the SPDX header while I'm in the neighborhood. The source itself just
says "GNU General Public License", but it also refers people to the COPYING
file for

docs: Add an SPDX header to kernel-doc

Add the SPDX header while I'm in the neighborhood. The source itself just
says "GNU General Public License", but it also refers people to the COPYING
file for further information. Since COPYING says 2.0-only, that is what I
have put into the header.

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel-doc: support in-line comments on nested structs/unions

The parser at kernel-doc rejects names with dots in the middle.
Fix it, in order to support nested structs/unions.

Tested-by:

scripts: kernel-doc: support in-line comments on nested structs/unions

The parser at kernel-doc rejects names with dots in the middle.
Fix it, in order to support nested structs/unions.

Tested-by: Jani Nikula <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

scripts: kernel_doc: fixup reporting of function identifiers

When function description includes brackets after the function name as
suggested by Documentation/doc-guide/kernel-doc, the kernel-doc sc

scripts: kernel_doc: fixup reporting of function identifiers

When function description includes brackets after the function name as
suggested by Documentation/doc-guide/kernel-doc, the kernel-doc script
omits the function name from "Scanning doc for" report.
Extending match for identifier name with optional brackets fixes this
issue.

Signed-off-by: Mike Rapoport <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: kernel-doc: Don't mangle literal code blocks in comments

It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

docs: kernel-doc: Don't mangle literal code blocks in comments

It can be useful to put code snippets into kerneldoc comments; that can be
done with the "::" operator at the end of a line like this::

if (desperate)
run_in_circles();

The ".. code-block::" directive can also be used to this end. kernel-doc
currently fails to understand these literal blocks and applies its normal
markup to them, which is then treated as literal by sphinx. The result is
unsightly markup instead of a useful code snippet.

Apply a hack to the output code to recognize literal blocks and avoid
performing any special markup on them. It's ugly, but that means it fits
in well with the rest of the script.

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

show more ...

docs: kernel-doc: Finish moving STATE_* code out of process_file()

Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now
actually fits on a single screen. Delete an unused vari

docs: kernel-doc: Finish moving STATE_* code out of process_file()

Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now
actually fits on a single screen. Delete an unused variable and add a
couple of comments while I'm at it.

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

show more ...

docs: kernel-doc: Move STATE_PROTO processing into its own function

Move the top-level prototype-processing code out of process_file().

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

docs: kernel-doc: Move STATE_PROTO processing into its own function

Move the top-level prototype-processing code out of process_file().

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

show more ...

docs: kernel-doc: Move STATE_BODY processing to a separate function

Also group the pseudo-global $leading_space variable with its peers.

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

docs: kernel-doc: Move STATE_BODY processing to a separate function

Also group the pseudo-global $leading_space variable with its peers.

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

show more ...

docs: kernel-doc: Move STATE_NAME processing into its own function

Move this code out of process_file() in the name of readability and
maintainability.

Reviewed-by: Jani Nikula <[email protected]

docs: kernel-doc: Move STATE_NAME processing into its own function

Move this code out of process_file() in the name of readability and
maintainability.

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

show more ...

docs: kernel-doc: Move STATE_NORMAL processing into its own function

Begin the process of splitting up the nearly 500-line process_file()
function by moving STATE_NORMAL processing to a separate fun

docs: kernel-doc: Move STATE_NORMAL processing into its own function

Begin the process of splitting up the nearly 500-line process_file()
function by moving STATE_NORMAL processing to a separate function.

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

show more ...

docs: kernel-doc: Rename and split STATE_FIELD

STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.

The $in_purpose va

docs: kernel-doc: Rename and split STATE_FIELD

STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.

The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
it and make a proper state (STATE_BODY_MAYBE) instead. This will make the
subsequent process_file() splitup easier.

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

show more ...