Skip to contentSkip to conversation

docs: make kernel-doc handle varargs properly

PATCH In review Jonathan Corbet 4 participants 6 messages Aug 26, 2016 – Sep 7, 2016

lore
Share & tools
lore
#0 lore raw

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
index c681e8f0ecc2..e6c52ab938fd 100755
@@ -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
#1 lore raw
url: 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

#2 lore raw
In reply to Jonathan Corbet
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.

---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index c681e8f0ecc2..e6c52ab938fd 100755

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 -0
 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
Jani Nikula, Intel Open Source Technology Center
#3 lore raw
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.

---
 scripts/kernel-doc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index c681e8f0ecc2..e6c52ab938fd 100755

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?

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

#4 lore raw

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.

---
scripts/kernel-doc | 3 ++-

1 file changed, 2 insertions(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index c681e8f0ecc2..e6c52ab938fd 100755
@@ -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 .

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

#5 lore raw
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.

---
scripts/kernel-doc | 3 ++-

1 file changed, 2 insertions(+), 1 deletion(-)
scripts/kernel-doc +0 -0
index c681e8f0ecc2..e6c52ab938fd 100755
@@ -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 .

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