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>
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: 2defb27292 ("scripts: kernel-doc: apply filtering rules to warnings")
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Acked-and-Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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
<code>
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 */
};
</code>
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 <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 clock
With 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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 3a025e1d1c
("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 <mawilcox@microsoft.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Will Deacon <will.deacon@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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).
-----BEGIN PGP SIGNATURE-----
iQIcBAABAgAGBQJaFaXjAAoJEI3ONVYwIuV6AXAQAMDinEQQBxNJmO/PkQrIxT4t
sgbLfI+Sd9zD/lEb9aC5e99XYqw+SH0H9xtEcOrhwx+fjuzkKa6NKLPWjopGzVxH
CM+N7lCE3AFuzbBCmcQvQyEelQg+p7rsY+2MGLYxMZINnaHFgTa1lvamcE/wKu5d
CSXs1K2TwFQEpippYlzTmiWU1Rt3gWKGwtBFgLtikSBqiS3HVr4yn7dgm1WTEpVo
IZPQYoglHjb8vL/vnVDDsfu1PW6Q1uE1aBSgTFBgFIv3UXJBBSlfWQJ7MQsD12Ww
ZkkAxssFm6TRa87mtgd68Du0Ebg4wZQJG9fizCSy6yIh1ExYxvG0rUmqGrZ1rRYu
4F+hukXINn7OK5L2laKNQT8ZWCPP+RoN6YUQpz2dhXC3nULZbd5GI9y8pQTdZjmK
p39SIovicQltlw8ap9MkzTKxm4mvLo/wjFWhQT4qH2QENKO8uSqA9BpLt5a1gJU5
dSLKDElph5EhliQAQfN/wXdPnTzSaGovele23zTTOLu2vr2JUSnBWWwiaOwuTHRQ
OEdzxQceoINnc/iqC1qt8F/57E8BT76YedAlmsn77umTXq3mq28wkd1RCRFcjqz5
KeqrvC5WMSbWZXZDxow7Pr+CPONUy4WpqVbHbwcQ4V8zlFfGjtQdR6zKN88Mb364
4oJpUwUMz36HchZpi1Tx
=ydAe
-----END PGP SIGNATURE-----
Merge tag 'docs-4.15-2' of git://git.lwn.net/linux
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
Implement a '-none' output mode for kernel-doc which will only output
warning messages, and suppresses the warning message about there being
no kernel-doc in the file.
If the build has requested additional warnings, automatically check all
.c files. This patch does not check .h files. Enabling the warning
by default would add about 1300 warnings, so it's default off for now.
People who care can use this to check they didn't break the docs and
maybe we'll get all the warnings fixed and be able to enable this check
by default in the future.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The existing message
"Excess struct/union/enum/typedef member [...]"
made it sound like this would already be done, but the
code is never invoked for enums or typedefs (and really
can't be).
Add some code to the enum dumper to handle this there
instead.
While at it, also make the above message more accurate
by simply dumping the type that was passed in, and pass
the struct/union differentiation in.
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Reported by Johannes Berg [1]. Problem here: function
process_proto_type() concatenates the striped lines of declaration
without any whitespace. A one-liner of::
struct something {
struct foo
bar;
};
has to be::
struct something {struct foo bar;};
Without the patching process_proto_type(), the result missed the space
between 'foo' and 'bar'::
struct something {struct foobar;};
Bugfix of process_proto_type() brings next error when blank lines
between enum declaration::
warning: Enum value ' ' not described in enum 'foo'
Problem here: dump_enum() does not strip leading whitespaces from
the concatenated string (with the new additional space from
process_proto_type).
[1] https://www.mail-archive.com/linux-doc@vger.kernel.org/msg12410.html
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
- Use more portable shebang for Perl scripts
- Remove trailing spaces from GCC version in kernel log
- Make initramfs generation deterministic
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQIcBAABAgAGBQJZXrq2AAoJED2LAQed4NsGzlIP/jmVGusmFIP2jFC7zUEVaKsp
VK4tezn0aa/c/BsY+kGu3OVqUHgspQSjNa4wH27A+z4/skkxPQKUmF1IY+8/W5yc
aR0Yn76vzjjNYNl6AS3fA+QP+dBn+UdQDA2jMNKyu/3fACjiVY9BBx2ZdhJMwJcy
WrAax/fQNnRjmAQFQpptNBvYZn1B7A/7iFCPpQbPP6GFsqSJ2zMtRGjtoaeFgpV3
On6d4uAcgAcnEHw1zomWTx0N0LghW+L6Te9PoHyPZnyxfi+OVN/bmakoy7qs1uUh
zWucIhpBc8bshx6s4VnJ5OZhFNVEkeSjq5CivYKnU0u4waKb7suxuI1+D6e7uRrA
2OuXmhm7sRvGHwGIxEdJAOlF0PNecYSgJPv+ZDcOxVMy72REUZUEjgThti/vLdUn
9iVDXn/ExOxqJW7isth1MTn3FBsDUIZDKK5EypgY/oAuECR6pQnjD3HjojJBACau
OqbsZDPqmDiY3sxzU1GcAbrhAJiGyWXV7hAKsROoVlgwU2fu0Al2HHtDzEjqLrzK
wIvAD+lsWKiFP1zXlCnrsgjXgn/RFG1cHLiqEhtPy+HpqNzXoXDRs5kcTsr5Z0fj
3DlMNqa7Bv0raL3+XG2pp9OR5gWdLxmOuPIR/TNU3JubTRur4SElJtXyDoHVTJti
s4mye73xjjcifGEwpZQw
=C+WJ
-----END PGP SIGNATURE-----
Merge tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild
Pull misc Kbuild updates from Masahiro Yamada:
- Use more portable shebang for Perl scripts
- Remove trailing spaces from GCC version in kernel log
- Make initramfs generation deterministic
* tag 'kbuild-misc-v4.13' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild:
kbuild: create deterministic initramfs directory listings
scripts/mkcompile_h: Remove trailing spaces from compiler version
scripts: Switch to more portable Perl shebang
DECLARE_HASHTABLE needs similar handling to DECLARE_BITMAP
because otherwise kernel-doc assumes the member name is the
second, not first macro parameter.
Signed-off-by: Jakub Kicinski <jakub.kicinski@netronome.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The default NetBSD package manager is pkgsrc and it installs Perl
along other third party programs under custom and configurable prefix.
The default prefix for binary prebuilt packages is /usr/pkg, and the
Perl executable lands in /usr/pkg/bin/perl.
This change switches "/usr/bin/perl" to "/usr/bin/env perl" as it's
the most portable solution that should work for almost everybody.
Perl's executable is detected automatically.
This change switches -w option passed to the executable with more
modern "use warnings;" approach. There is no functional change to the
default behavior.
While there, drop "require 5" from scripts/namespace.pl (Perl from 1994?).
Signed-off-by: Kamil Rytarowski <n54@gmx.com>
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
lib/crc32c defines one parameter as:
const u32 (*tab)[256]
Better handle parenthesis, to avoid those warnings:
./lib/crc32.c:149: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:149: warning: Excess function parameter 'tab' description in 'crc32_le_generic'
./lib/crc32.c:294: warning: No description found for parameter 'tab)[256]'
./lib/crc32.c:294: warning: Excess function parameter 'tab' description in 'crc32_be_generic'
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
On ReST, adding a text like ``literal`` is valid. However,
the kernel-doc script won't handle it fine.
We really need this feature, in order to escape things like
%ph, with is found on some C files.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Clearly nobody ever tried to build the documentation for the radix tree
before:
include/linux/radix-tree.h:400: warning: cannot understand function
prototype: 'void ** radix_tree_iter_init(struct radix_tree_iter *iter,
unsigned long start) '
Indeed, the regexes only handled a single '*', not one-or-more. I have
tried to fix that, but now I have perl regexes all over my hands, and
I fear I shall never be clean again.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation for array parameters passed in a function, like the first
argument in the function below, weren't getting exported in the rst
format, although they work fine for html and pdf formats:
void drm_clflush_pages(struct page * pages[], unsigned long num_pages)
That's because the string key to store the description in the
parameterdescs dictionary doesn't have the [] suffix. This cleans up
the suffix from the key before accessing the dictionary.
Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>
Fixes: c0d1b6ee78 ("kernel-doc: produce RestructuredText output")
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
$type_struct_full and friends are only used by the restructuredText
backend, because it needs to separate enum/struct/typedef/union from
the name of the type. However, $type_struct is *also* used by the rST
backend. This is confusing.
This patch replaces $type_struct's use in the rST backend with a new
$type_fallback; it modifies $type_struct so that it can be used in the
rST backend; and creates regular expressions like $type_struct
for enum/typedef/union, for use in all backends.
Note that, compared to $type_*_full, in the new regexes $1 includes both
the "kind" and the name (before, $1 was pretty much a constant).
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Note that, in order to produce the correct Docbook markup, the "." or "->"
must be separated from the member name in the regex's captured fields. For
consistency, this change is applied to $type_member and $type_member_func
too, not just to $type_member_xml.
List mode only prints the struct name, to avoid any undesired change in
the operation of docproc.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The restructuredText output includes both the parameter type and
the name for functions and function-typed members. Do the same
for docbook.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
An inline function can have an attribute, as in include/linux/log2.h,
and kernel-doc handles this already for simple cases. However,
some attributes have arguments (e.g. the "target" attribute).
Handle those too.
Furthermore, attributes could be at the beginning of a function
declaration, before the return type. To correctly handle this case,
you need to strip spaces after the attributes; otherwise, dump_function
is left confused.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
A prototype like
/**
* foo - sample definition
* @bar: a parameter
*/
int foo(int (*bar)(int x,
int y));
is currently producing
.. c:function:: int foo (int (*bar) (int x, int y)
sample definition
**Parameters**
``int (*)(int x, int y) bar``
a parameter
Collapse the spaces so that the output is nicer.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
kernel-doc supports documenting struct members "inline" since
a4c6ebede2 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:
/**
* struct foo - struct documentation
*/
struct foo {
/**
* @bar: member documentation
*/
int bar;
};
Add support for one line inline comments:
/**
* struct foo - struct documentation
*/
struct foo {
/** @bar: member documentation */
int bar;
};
Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.
Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Without this patch we get warnings for named variable arguments.
warning: No description found for parameter '...'
warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue'
Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Jani Nikula <jani.nikula@intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Add yet another regex to kernel-doc to trap @param() references separately
and not produce corrupt RST markup.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
As far as I can tell, the handling of "..." arguments has never worked
right, so any documentation provided was ignored in favor of "variable
arguments." This makes kernel-doc handle "@...:" as documented. It does
*not* fix spots in kerneldoc comments that don't follow that convention,
but they are no more broken than before.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When using a typedef function like this one:
typedef bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);
The Sphinx C domain expects it to create a c:type: reference,
as that's the way it creates the type references when parsing
a c:function:: declaration.
So, a declaration like:
.. c:function:: bool v4l2_valid_dv_timings (const struct v4l2_dv_timings * t, const struct v4l2_dv_timings_cap * cap, v4l2_check_dv_timings_fnc fnc, void * fnc_handle)
Will create a cross reference for :c:type:`v4l2_check_dv_timings_fnc`.
So, when outputting such typedefs in RST format, we need to handle
this special case, as otherwise it will produce those warnings:
./include/media/v4l2-dv-timings.h:43: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:60: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
./include/media/v4l2-dv-timings.h:81: WARNING: c:type reference target not found: v4l2_check_dv_timings_fnc
So, change the kernel-doc script to produce a RST output for the
above typedef as:
.. c:type:: v4l2_check_dv_timings_fnc
**Typedef**: timings check callback
**Syntax**
``bool v4l2_check_dv_timings_fnc (const struct v4l2_dv_timings * t, void * handle);``
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Mauro Carvalho Chehab
Matthew Wilcox
Jonathan Corbet
Mike Rapoport
Will Deacon
Linus Torvalds
Matthew Wilcox
Levin, Alexander (Sasha Levin)
Johannes Berg
Markus Heiser
Jakub Kicinski
Kamil Rytarowski
Gabriel Krisman Bertazi
Paolo Bonzini
Jani Nikula
Silvio Fricke