Hi all,
After merging the jc_docs tree, today's linux-next build (htmldocs)
produced these warnings:
include/linux/pstore_zone.h:55: warning: Function parameter or member 'write' not described in 'pstore_zone_info'
include/linux/pstore_blk.h:43: warning: Function parameter or member 'write' not described in 'pstore_device_info'
include/media/v4l2-mediabus.h:127: warning: Function parameter or member 'type' not described in 'v4l2_mbus_config'
and many more similar. These appear to be false positives :-(
Introduced by commit
8d295fbad687 ("kernel-doc: better handle '::' sequences")
I have reverted that commit for today.
--
Cheers,
Stephen Rothwell
Stephen Rothwell <[email protected]> writes:
> Hi all,
>
> After merging the jc_docs tree, today's linux-next build (htmldocs)
> produced these warnings:
>
> include/linux/pstore_zone.h:55: warning: Function parameter or member 'write' not described in 'pstore_zone_info'
> include/linux/pstore_blk.h:43: warning: Function parameter or member 'write' not described in 'pstore_device_info'
> include/media/v4l2-mediabus.h:127: warning: Function parameter or member 'type' not described in 'v4l2_mbus_config'
>
> and many more similar. These appear to be false positives :-(
>
> Introduced by commit
>
> 8d295fbad687 ("kernel-doc: better handle '::' sequences")
>
> I have reverted that commit for today.
Argh, that was bad, sorry, I should have caught that.
Just added the following to fix it.
Thanks,
jon
From 212209cff89fe497bc47abcd017aa95e4e8a5196 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <[email protected]>
Date: Fri, 26 Mar 2021 13:16:35 -0600
Subject: [PATCH] docs: kernel-doc: properly recognize parameter lines with
colons
The previous attempt to properly handle literal blocks broke parsing of
parameter lines containing colons; fix it by tweaking the regex to
specifically exclude the "::" pattern while accepting lines containing
colons in general. Add a little documentation to the regex while in the
neighborhood.
Reported-by: Stephen Rothwell <[email protected]>
Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences")
Signed-off-by: Jonathan Corbet <[email protected]>
---
scripts/kernel-doc | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 0ecd71477a16..d6d2b6e0b4eb 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -391,8 +391,14 @@ my $doc_com = '\s*\*\s*';
my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
# @params and a strictly limited set of supported section names
+# Specifically:
+# Match @word:
+# @...:
+# @{section-name}:
+# while trying to not match literal block starts like "example::"
+#
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*$';
--
2.30.2