13 Aug, 2019
1 commit
-
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
Signed-off-by: Jonathan Corbet
07 Aug, 2019
1 commit
-
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
Signed-off-by: Randy Dunlap
Cc: Brendan Higgins
Tested-by: Brendan Higgins
Signed-off-by: Jonathan Corbet
27 Jun, 2019
1 commit
-
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
28 May, 2019
1 commit
-
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
17 Jan, 2019
1 commit
-
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
26 Nov, 2018
1 commit
-
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
Signed-off-by: Jonathan Corbet
08 Nov, 2018
2 commits
-
Currently, function parameter description can match '@type.member'
expressions but fails to match '@type->member'.
Extend the $type_param regex to allow matching bothSigned-off-by: Mike Rapoport
Signed-off-by: Jonathan Corbet -
Signed-off-by: Mike Rapoport
Signed-off-by: Jonathan Corbet
19 Oct, 2018
1 commit
-
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
Acked-by: Jani Nikula
Tested-by: Kees Cook
Signed-off-by: Jonathan Corbet
07 Aug, 2018
1 commit
-
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
Signed-off-by: Jonathan Corbet
23 Jul, 2018
1 commit
-
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
Reviewed-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
30 Mar, 2018
1 commit
-
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
Signed-off-by: Jonathan Corbet
21 Mar, 2018
1 commit
-
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
Signed-off-by: Jonathan Corbet
21 Feb, 2018
2 commits
-
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
19 Feb, 2018
2 commits
-
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
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
16 Feb, 2018
8 commits
-
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
Move the top-level prototype-processing code out of process_file().
Reviewed-by: Jani Nikula
Signed-off-by: Jonathan Corbet -
Also group the pseudo-global $leading_space variable with its peers.
Reviewed-by: Jani Nikula
Signed-off-by: Jonathan Corbet -
Move this code out of process_file() in the name of readability and
maintainability.Reviewed-by: Jani Nikula
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet -
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
Signed-off-by: Jonathan Corbet
02 Jan, 2018
1 commit
-
The logic with inhibits warnings for definitions that is not
output is incomplete: it doesn't cover the cases where
OUTPUT_INTERNAL and OUTPUT_EXPORTED are used.As the most common case is OUTPUT_ALL, place it first,
in order to optimize a litte bit the check logic.Fixes: 2defb2729217 ("scripts: kernel-doc: apply filtering rules to warnings")
Reported-by: Randy Dunlap
Acked-and-Tested-by: Randy Dunlap
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
22 Dec, 2017
11 commits
-
When kernel-doc is called with output selection filters,
it will be called lots of time for a single file. If
there is a warning present there, it means that it may
print hundreds of identical warnings.Worse than that, the -function NAME actually filters only
functions. So, it makes no sense at all to print warnings
for structs or enums.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
It is possible to use nested structs like:
struct {
struct {
void *arg1;
} st1, st2, *st3, st4;
};Handling it requires to split each parameter. Change the logic
to allow such definitions.In order to test the new nested logic, the following file
was used to test
struct foo { int a; }; /* Just to avoid errors if compiled *//**
* struct my_struct - a struct with nested unions and structs
* @arg1: first argument of anonymous union/anonymous struct
* @arg2: second argument of anonymous union/anonymous struct
* @arg1b: first argument of anonymous union/anonymous struct
* @arg2b: second argument of anonymous union/anonymous struct
* @arg3: third argument of anonymous union/anonymous struct
* @arg4: fourth argument of anonymous union/anonymous struct
* @bar.st1.arg1: first argument of struct st1 on union bar
* @bar.st1.arg2: second argument of struct st1 on union bar
* @bar.st1.bar1: bar1 at st1
* @bar.st1.bar2: bar2 at st1
* @bar.st2.arg1: first argument of struct st2 on union bar
* @bar.st2.arg2: second argument of struct st2 on union bar
* @bar.st3.arg2: second argument of struct st3 on union bar
* @f1: nested function on anonimous union/struct
* @bar.st2.f2: nested function on named union/struct
*/
struct my_struct {
/* Anonymous union/struct*/
union {
struct {
char arg1 : 1;
char arg2 : 3;
};
struct {
int arg1b;
int arg2b;
};
struct {
void *arg3;
int arg4;
int (*f1)(char foo, int bar);
};
};
union {
struct {
int arg1;
int arg2;
struct foo bar1, *bar2;
} st1; /* bar.st1 is undocumented, cause a warning */
struct {
void *arg1; /* bar.st3.arg1 is undocumented, cause a warning */
int arg2;
int (*f2)(char foo, int bar); /* bar.st3.fn2 is undocumented, cause a warning */
} st2, st3, *st4;
int (*f3)(char foo, int bar); /* f3 is undocumented, cause a warning */
} bar; /* bar is undocumented, cause a warning *//* private: */
int undoc_privat; /* is undocumented but private, no warning *//* public: */
int undoc_public; /* is undocumented, cause a warning */
};It produces the following warnings, as expected:
test2.h:57: warning: Function parameter or member 'bar' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st3.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg1' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.arg2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.st4.f2' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'bar.f3' not described in 'my_struct'
test2.h:57: warning: Function parameter or member 'undoc_public' not described in 'my_struct'Suggested-by: Markus Heiser
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Function arguments are different than usual ones. So, an
special logic is needed in order to handle such arguments
on nested structs.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
The logic at create_parameterlist()'s ancillary push_parameter()
function has already a way to output the declaration name, with
would help to discover what declaration is missing.However, currently, the logic is utterly broken, as it uses
the var $type with a wrong meaning. With the current code,
it will never print anything. I suspect that originally
it was using the second argument of output_declaration().I opted to not rely on a globally defined $declaration_name,
but, instead, to pass it explicitly as a parameter.While here, I removed a unaligned check for !$anon_struct_union.
This is not needed, as, if $anon_struct_union is not zero,
$parameterdescs{$param} will be defined.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
The check_sections() function has a $nested parameter, meant
to identify when a nested struct is present. As we now have
a logic that handles it, get rid of such parameter.Suggested-by: Markus Heiser
Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
There are several places within the Kernel tree with nested
structs/unions, like this one:struct ingenic_cgu_clk_info {
const char *name;
enum {
CGU_CLK_NONE = 0,
CGU_CLK_EXT = BIT(0),
CGU_CLK_PLL = BIT(1),
CGU_CLK_GATE = BIT(2),
CGU_CLK_MUX = BIT(3),
CGU_CLK_MUX_GLITCHFREE = BIT(4),
CGU_CLK_DIV = BIT(5),
CGU_CLK_FIXDIV = BIT(6),
CGU_CLK_CUSTOM = BIT(7),
} type;
int parents[4];
union {
struct ingenic_cgu_pll_info pll;
struct {
struct ingenic_cgu_gate_info gate;
struct ingenic_cgu_mux_info mux;
struct ingenic_cgu_div_info div;
struct ingenic_cgu_fixdiv_info fixdiv;
};
struct ingenic_cgu_custom_info custom;
};
};Currently, such struct is documented as:
**Definition**
::
struct ingenic_cgu_clk_info {
const char * name;
};**Members**
``name``
name of the clockWith is obvioulsy wrong. It also generates an error:
drivers/clk/ingenic/cgu.h:169: warning: No description found for parameter 'enum'However, there's nothing wrong with this kernel-doc markup: everything
is documented there.It makes sense to document all fields there. So, add a
way for the core to parse those structs.With this patch, all documented fields will properly generate
documentation.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Sphinx has a hard time dealing with tabs, causing it to
misinterpret paragraph continuation.As we're now mainly focused on supporting ReST output,
replace tabs by spaces, in order to avoid troubles when
the output is parsed by Sphinx.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Right now, if kernel-doc is called without arguments, it
defaults to man pages. IMO, it makes more sense to
default to ReST, as this is the output that it is most
used nowadays, and it easier to check if everything got
parsed fine on an enriched text mode format.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Right now, if one uses "--rst" instead of "-rst", it just
ignore the argument and produces a man page. Change the
logic to accept both "-cmd" and "--cmd". Also, if
"cmd" doesn't exist, print the usage information and exit.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet -
Since there isn't any docbook code anymore upstream,
we can get rid of several output formats:- docbook/xml, html, html5 and list formats were used by
the old build system;
- As ReST is text, there's not much sense on outputting
on a different text format.After this patch, only man and rst output formats are
supported.Signed-off-by: Mauro Carvalho Chehab
Acked-by: Jani Nikula
Signed-off-by: Jonathan Corbet -
Everything there is already described at
Documentation/doc-guide/kernel-doc.rst. So, there's no reason why
to keep it anymore.Signed-off-by: Mauro Carvalho Chehab
Signed-off-by: Jonathan Corbet
12 Dec, 2017
1 commit
-
On media, we now have an struct declared with:
struct lirc_fh {
struct list_head list;
struct rc_dev *rc;
int carrier_low;
bool send_timeout_reports;
DECLARE_KFIFO_PTR(rawir, unsigned int);
DECLARE_KFIFO_PTR(scancodes, struct lirc_scancode);
wait_queue_head_t wait_poll;
u8 send_mode;
u8 rec_mode;
};gpiolib.c has a similar declaration with DECLARE_KFIFO().
Currently, those produce the following error:
./include/media/rc-core.h:96: warning: No description found for parameter 'int'
./include/media/rc-core.h:96: warning: No description found for parameter 'lirc_scancode'
./include/media/rc-core.h:96: warning: Excess struct member 'rawir' description in 'lirc_fh'
./include/media/rc-core.h:96: warning: Excess struct member 'scancodes' description in 'lirc_fh'
../drivers/gpio/gpiolib.c:601: warning: No description found for parameter '16'
../drivers/gpio/gpiolib.c:601: warning: Excess struct member 'events' description in 'lineevent_state'So, teach kernel-doc how to parse DECLARE_KFIFO() and DECLARE_KFIFO_PTR().
While here, relax at the past DECLARE_foo() macros, accepting a random
number of spaces after comma.The addition of DECLARE_KFIFO() was
Suggested-by: Randy DunlapSigned-off-by: Mauro Carvalho Chehab
Tested-by: Randy Dunlap
Signed-off-by: Jonathan Corbet
02 Dec, 2017
1 commit
-
My bisect scripts starting running into build failures when trying to
compile 4.15-rc1 with the builds failing with things like:drivers/net/wireless/broadcom/brcm80211/brcmfmac/sdio.c:2078: error: Cannot parse struct or union!
The line in question is actually just a #define, but after some digging
it turns out that my scripts pass W=1 and since commit 3a025e1d1c2ea
("Add optional check for bad kernel-doc comments") that results in
kernel-doc running on each source file. The file in question has a
badly formatted comment immediately before the #define:/**
* struct brcmf_skbuff_cb reserves first two bytes in sk_buff::cb for
* bus layer usage.
*/which causes the regex in dump_struct to fail (lack of braces following
struct declaration) and kernel-doc returns 1, which causes the build
to fail.Fix the issue by always returning 0 from kernel-doc when invoked with
-none. It successfully generates no documentation, and prints out any
issues.Cc: Matthew Wilcox
Cc: Jonathan Corbet
Signed-off-by: Will Deacon
Signed-off-by: Jonathan Corbet
24 Nov, 2017
1 commit
-
Pull documentation updates from Jonathan Corbet:
"A few late-arriving docs updates that have no real reason to wait.There's a new "Co-Developed-by" tag described by Greg, and a build
enhancement from Willy to generate docs warnings during a kernel build
(but only when additional warnings have been requested in general)"* tag 'docs-4.15-2' of git://git.lwn.net/linux:
Add optional check for bad kernel-doc comments
Documentation: fix profile= options in kernel-parameters.txt
documentation/svga.txt: update outdated file
kokr/memory-barriers.txt: Fix typo in paring example
kokr/memory-barriers/txt: Replace uses of "transitive"
Documentation/process: add Co-Developed-by: tag for patches with multiple authors
