* [PATCH] docs: make kernel-doc handle varargs properly
@ 2016-08-26 13:25 Jonathan Corbet
2016-08-26 16:07 ` kbuild test robot
2016-08-27 8:43 ` Jani Nikula
0 siblings, 2 replies; 6+ messages in thread
From: Jonathan Corbet @ 2016-08-26 13:25 UTC (permalink / raw)
To: linux-doc; +Cc: LKML, Mauro Carvalho Chehab, Markus Heiser, Jani Nikula
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>
---
scripts/kernel-doc | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c681e8f0ecc2..e6c52ab938fd 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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";
}
--
2.7.4
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH] docs: make kernel-doc handle varargs properly
2016-08-26 13:25 [PATCH] docs: make kernel-doc handle varargs properly Jonathan Corbet
@ 2016-08-26 16:07 ` kbuild test robot
2016-08-27 8:43 ` Jani Nikula
1 sibling, 0 replies; 6+ messages in thread
From: kbuild test robot @ 2016-08-26 16:07 UTC (permalink / raw)
To: Jonathan Corbet
Cc: kbuild-all, linux-doc, LKML, Mauro Carvalho Chehab,
Markus Heiser, Jani Nikula
[-- Attachment #1: Type: text/plain, Size: 4526 bytes --]
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 <tiwai@suse.de>
:::::: CC: Takashi Iwai <tiwai@suse.de>
---
0-DAY kernel test infrastructure Open Source Technology Center
https://lists.01.org/pipermail/kbuild-all Intel Corporation
[-- Attachment #2: .config.gz --]
[-- Type: application/octet-stream, Size: 6422 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: make kernel-doc handle varargs properly
2016-08-26 13:25 [PATCH] docs: make kernel-doc handle varargs properly Jonathan Corbet
2016-08-26 16:07 ` kbuild test robot
@ 2016-08-27 8:43 ` Jani Nikula
2016-09-06 13:36 ` Jonathan Corbet
1 sibling, 1 reply; 6+ messages in thread
From: Jani Nikula @ 2016-08-27 8:43 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc; +Cc: LKML, Mauro Carvalho Chehab, Markus Heiser
On Fri, 26 Aug 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> 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>
> ---
> scripts/kernel-doc | 3 ++-
> 1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index c681e8f0ecc2..e6c52ab938fd 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -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.
> 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";
> }
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH] docs: make kernel-doc handle varargs properly
2016-08-27 8:43 ` Jani Nikula
@ 2016-09-06 13:36 ` Jonathan Corbet
2016-09-07 7:28 ` Markus Heiser
0 siblings, 1 reply; 6+ messages in thread
From: Jonathan Corbet @ 2016-09-06 13:36 UTC (permalink / raw)
To: Jani Nikula; +Cc: linux-doc, LKML, Mauro Carvalho Chehab, Markus Heiser
On Sat, 27 Aug 2016 11:43:18 +0300
Jani Nikula <jani.nikula@intel.com> wrote:
> On Fri, 26 Aug 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> > 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>
> > ---
> > scripts/kernel-doc | 3 ++-
> > 1 file changed, 2 insertions(+), 1 deletion(-)
> >
> > diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> > index c681e8f0ecc2..e6c52ab938fd 100755
> > --- a/scripts/kernel-doc
> > +++ b/scripts/kernel-doc
> > @@ -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*:(.*)';
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: make kernel-doc handle varargs properly
2016-09-06 13:36 ` Jonathan Corbet
@ 2016-09-07 7:28 ` Markus Heiser
2016-09-07 13:08 ` Jani Nikula
0 siblings, 1 reply; 6+ messages in thread
From: Markus Heiser @ 2016-09-07 7:28 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Jani Nikula, linux-doc, LKML, Mauro Carvalho Chehab
Am 06.09.2016 um 15:36 schrieb Jonathan Corbet <corbet@lwn.net>:
> On Sat, 27 Aug 2016 11:43:18 +0300
> Jani Nikula <jani.nikula@intel.com> wrote:
>
>> On Fri, 26 Aug 2016, Jonathan Corbet <corbet@lwn.net> wrote:
>>> 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>
>>> ---
>>> scripts/kernel-doc | 3 ++-
>>> 1 file changed, 2 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>>> index c681e8f0ecc2..e6c52ab938fd 100755
>>> --- a/scripts/kernel-doc
>>> +++ b/scripts/kernel-doc
>>> @@ -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*:(.*)';
>
> 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 --
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs: make kernel-doc handle varargs properly
2016-09-07 7:28 ` Markus Heiser
@ 2016-09-07 13:08 ` Jani Nikula
0 siblings, 0 replies; 6+ messages in thread
From: Jani Nikula @ 2016-09-07 13:08 UTC (permalink / raw)
To: Markus Heiser, Jonathan Corbet; +Cc: linux-doc, LKML, Mauro Carvalho Chehab
On Wed, 07 Sep 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 06.09.2016 um 15:36 schrieb Jonathan Corbet <corbet@lwn.net>:
>
>> On Sat, 27 Aug 2016 11:43:18 +0300
>> Jani Nikula <jani.nikula@intel.com> wrote:
>>
>>> On Fri, 26 Aug 2016, Jonathan Corbet <corbet@lwn.net> wrote:
>>>> 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>
>>>> ---
>>>> scripts/kernel-doc | 3 ++-
>>>> 1 file changed, 2 insertions(+), 1 deletion(-)
>>>>
>>>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>>>> index c681e8f0ecc2..e6c52ab938fd 100755
>>>> --- a/scripts/kernel-doc
>>>> +++ b/scripts/kernel-doc
>>>> @@ -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*:(.*)';
>>
>> 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?
Sparse contains a C preprocessor.
> 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.
--
Jani Nikula, Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-09-07 13:09 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-08-26 13:25 [PATCH] docs: make kernel-doc handle varargs properly Jonathan Corbet
2016-08-26 16:07 ` kbuild test robot
2016-08-27 8:43 ` Jani Nikula
2016-09-06 13:36 ` Jonathan Corbet
2016-09-07 7:28 ` Markus Heiser
2016-09-07 13:08 ` Jani Nikula
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.