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 <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <lkp@intel.com>
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Brendan Higgins <brendanhiggins@google.com>
Tested-by: Brendan Higgins <brendanhiggins@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <corbet@lwn.net>
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 <corbet@lwn.net>
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 <corbet@lwn.net>
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 <sakari.ailus@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <rppt@linux.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <rdunlap@infradead.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Commit 701b3a3c0a ("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 <ben@decadent.org.uk>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <valdis.kletnieks@vt.edu>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
So once upon a time I set out to fix the problem reported by Tobin wherein
a literal block within a kerneldoc comment would be corrupted in
processing. On the way, though, I got annoyed at the way I have to learn
how kernel-doc works from the beginning every time I tear into it.
As a result, seven of the following eight patches just get rid of some dead
code and reorganize the rest - mostly turning the 500-line process_file()
function into something a bit more rational. Sphinx output is unchanged
after these are applied. Then, at the end, there's a tweak to stop messing
with literal blocks.
If anybody was unaware that I've not done any serious Perl since the
1990's, they will certainly understand that fact now.
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 <corbet@lwn.net>
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 <jani.nikula@intel.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <rppt@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move the top-level prototype-processing code out of process_file().
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Also group the pseudo-global $leading_space variable with its peers.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move this code out of process_file() in the name of readability and
maintainability.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
XML escaping is a worry that came with DocBook, which we no longer have any
dealings with. So get rid of the useless xml_escape()/xml_unescape()
functions. No change to the generated output.
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
