docs: make kernel-doc handle varargs properly
PATCH 1/1 docs: make kernel-doc handle varargs properly
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.
--- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
scripts/kernel-doc +2 -1
@@ -414,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|description|context|returns?|notes?|examples?)\s*:(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -2340,6 +2340,7 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { + $param = "..."; if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; }
Signature · 1 line
2.7.4
kbuild test robot
build boturl: https://github.com/0day-ci/linux/commits/Jonathan-Corbet/docs-make-kernel-doc-handle-varargs-properly/20160826-213158 reproduce: make htmldocs
Hi Jonathan,
[auto build test WARNING on linus/master]
[also build test WARNING on v4.8-rc3 next-20160825]
[if your patch is applied to the wrong git tree, please drop us a note to help improve the system]
[Suggest to use git(>=2.9.0) format-patch --base=<commit> (or --base=auto for convenience) to record what (public, well-known) commit your patch series was built on] [Check https://git-scm.com/docs/git-format-patch for more information]
url: https://github.com/0day-ci/linux/commits/Jonathan-Corbet/docs-make-kernel-doc-handle-varargs-properly/20160826-213158
reproduce: make htmldocs
All warnings (new ones prefixed by >>):
include/sound/compress_driver.h:162: warning: No description found for parameter 'id[64]' include/sound/compress_driver.h:162: warning: No description found for parameter 'proc_root' include/sound/compress_driver.h:162: warning: No description found for parameter 'proc_info_entry'
>> include/sound/core.h:323: warning: No description found for parameter '...'
include/sound/core.h:334: warning: No description found for parameter '...' include/sound/core.h:387: warning: No description found for parameter '...'
--
include/linux/init.h:1: warning: no structured comments found kernel/sched/core.c:2082: warning: No description found for parameter 'cookie'
>> include/linux/workqueue.h:391: warning: No description found for parameter '...' >> include/linux/workqueue.h:391: warning: Excess function parameter 'args' description in 'alloc_workqueue' include/linux/workqueue.h:412: warning: No description found for parameter '...' >> include/linux/workqueue.h:412: warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue' kernel/sys.c:1: warning: no structured comments found include/linux/fence.h:85: warning: Excess struct/union/enum/typedef member 'child_list' description in 'fence' include/linux/fence.h:85: warning: Excess struct/union/enum/typedef member 'active_list' description in 'fence' drivers/dma-buf/seqno-fence.c:1: warning: no structured comments found drivers/dma-buf/fence-array.c:124: warning: No description found for parameter 'signal_on_any' >> include/sound/core.h:323: warning: No description found for parameter '...'
include/sound/core.h:334: warning: No description found for parameter '...' include/sound/core.h:387: warning: No description found for parameter '...'
vim +323 include/sound/core.h
b9075fa96 Joe Perches 2011-10-31 307 __printf(4, 5) 36ce99c1d Takashi Iwai 2009-08-27 308 void __snd_printk(unsigned int level, const char *file, int line, b9075fa96 Joe Perches 2011-10-31 309 const char *format, ...); 36ce99c1d Takashi Iwai 2009-08-27 310 #else 36ce99c1d Takashi Iwai 2009-08-27 311 #define __snd_printk(level, file, line, format, args...) \ cf0baf16c Takashi Iwai 2009-08-28 312 printk(format, ##args) 36ce99c1d Takashi Iwai 2009-08-27 313 #endif 36ce99c1d Takashi Iwai 2009-08-27 314 ^1da177e4 Linus Torvalds 2005-04-16 315 /** ^1da177e4 Linus Torvalds 2005-04-16 316 * snd_printk - printk wrapper ^1da177e4 Linus Torvalds 2005-04-16 317 * @fmt: format string ^1da177e4 Linus Torvalds 2005-04-16 318 * f66fcedc8 Takashi Iwai 2008-11-07 319 * Works like printk() but prints the file and the line of the caller ^1da177e4 Linus Torvalds 2005-04-16 320 * when configured with CONFIG_SND_VERBOSE_PRINTK. ^1da177e4 Linus Torvalds 2005-04-16 321 */ ^1da177e4 Linus Torvalds 2005-04-16 322 #define snd_printk(fmt, args...) \ 36ce99c1d Takashi Iwai 2009-08-27 @323 __snd_printk(0, __FILE__, __LINE__, fmt, ##args) ^1da177e4 Linus Torvalds 2005-04-16 324 ^1da177e4 Linus Torvalds 2005-04-16 325 #ifdef CONFIG_SND_DEBUG ^1da177e4 Linus Torvalds 2005-04-16 326 /** ^1da177e4 Linus Torvalds 2005-04-16 327 * snd_printd - debug printk 0863afb32 Martin Waitz 2006-01-09 328 * @fmt: format string ^1da177e4 Linus Torvalds 2005-04-16 329 * edab938e6 Pavel Machek 2008-04-01 330 * Works like snd_printk() for debugging purposes. ^1da177e4 Linus Torvalds 2005-04-16 331 * Ignored when CONFIG_SND_DEBUG is not set.
:::::: The code at line 323 was first introduced by commit
:::::: 36ce99c1dcab2978fc1900f19b431adedd8f99f6 ALSA: Add debug module option
:::::: TO: Takashi Iwai <[email protected]>
:::::: CC: Takashi Iwai <[email protected]>
---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation
Quoted 16 lines · Jonathan Corbet
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 <[email protected]>--- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)scripts/kernel-doc +0
-0
scripts/kernel-doc my $doc_com_body = '\s*\* ?'; · line 417
Quoted 5 lines
scripts/kernel-doc +1
-1@@ -414,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|description|context|returns?|notes?|examples?)\s*:(.*)';
So this will now accept "@foo.bar.baz:" too, right? Should it be something like this instead?
'\s*(\@\w+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
BR,
Jani.
Quoted 11 lines
scripts/kernel-doc +1
-0my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$';@@ -2340,6 +2340,7 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { + $param = "..."; if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; }
Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
Quoted 26 lines · On Sat, 27 Aug 2016 11:43:18 +0300 Jani Nikula <[email protected]> wrote:
Quoted 16 lines · Jonathan Corbet
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 <[email protected]>--- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)scripts/kernel-doc +0
-0scripts/kernel-doc my $doc_com_body = '\s*\* ?'; · line 417
Quoted 5 lines
scripts/kernel-doc +1
-1@@ -414,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|description|context|returns?|notes?|examples?)\s*:(.*)';So this will now accept "@foo.bar.baz:" too, right? Should it be something like this instead?
Quoted 1 line
'\s*(\@\w+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
That works too.
I had a sort of vision of catching the "args..." notation that a lot of kerneldoc comments use and doing the right thing, but ran out of patience before getting it to work. There are times when I find Markus's python kernel-doc replacement tempting... Maybe I'll beat my head against that wall one more time when I get a chance and, failing that, just use the above.
Thanks,
jon
Am 06.09.2016 um 15:36 schrieb Jonathan Corbet <[email protected]>:
Quoted 29 lines
Quoted 26 lines · On Sat, 27 Aug 2016 11:43:18 +0300 Jani Nikula <[email protected]> wrote:
Quoted 19 lines · Jonathan Corbet
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 <[email protected]>---
scripts/kernel-doc| 3 ++-1 file changed, 2 insertions(+), 1 deletion(-)scripts/kernel-doc +0
-0@@ -414,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section namesmy $doc_sect = $doc_com .
scripts/kernel-doc my $doc_com_body = '\s*\* ?'; · line 417
Quoted 2 lines
scripts/kernel-doc +1
-1- '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|description|context|returns?|notes?|examples?)\s*:(.*)';So this will now accept "@foo.bar.baz:" too, right? Should it be something like this instead?
Quoted 8 lines
Quoted 1 line
'\s*(\@\w+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
That works too.
I had a sort of vision of catching the "args..." notation that a lot of kerneldoc comments use and doing the right thing, but ran out of patience before getting it to work. There are times when I find Markus's python kernel-doc replacement tempting...
Feel free to contact me if you want to see a RFC.
OT but BTW: Does sparse parse macros, or did sparse precompile? I mean, are macros objects of sparse's AST or does the AST only contain C objects?
Sorry if my question is dump, I haven't had time to take a serious look on sparse.
-- Markus --
Quoted 7 lines
Maybe I'll beat my head against that
wall one more time when I get a chance and, failing that, just use the above.Thanks,
jon
Quoted 40 lines · Markus Heiser
Am 06.09.2016 um 15:36 schrieb Jonathan Corbet <[email protected]>:
Quoted 29 lines
Quoted 26 lines · On Sat, 27 Aug 2016 11:43:18 +0300 Jani Nikula <[email protected]> wrote:
Quoted 19 lines · Jonathan Corbet
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 <[email protected]>---
scripts/kernel-doc| 3 ++-1 file changed, 2 insertions(+), 1 deletion(-)scripts/kernel-doc +0
-0@@ -414,7 +414,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section namesmy $doc_sect = $doc_com .
scripts/kernel-doc my $doc_com_body = '\s*\* ?'; · line 417
Quoted 2 lines
scripts/kernel-doc +1
-1- '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|description|context|returns?|notes?|examples?)\s*:(.*)';So this will now accept "@foo.bar.baz:" too, right? Should it be something like this instead?
Quoted 8 lines
Quoted 1 line
'\s*(\@\w+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
That works too.
I had a sort of vision of catching the "args..." notation that a lot of kerneldoc comments use and doing the right thing, but ran out of patience before getting it to work. There are times when I find Markus's python kernel-doc replacement tempting...
Quoted 5 lines
Feel free to contact me if you want to see a RFC.
OT but BTW: Does sparse parse macros, or did sparse precompile? I mean, are macros objects of sparse's AST or does the AST only contain C objects?
Sparse contains a C preprocessor.
Quoted 2 lines
Sorry if my question is dump, I haven't had time to take a serious look on sparse.
See https://lwn.net/Articles/689907/.
BR,
Jani.
Signature · 1 line
Jani Nikula, Intel Open Source Technology Center