Re: linux-next: build warnings after merge of the jc_docs tree

[Jonathan Corbet <corbet@lwn.net>]

Stephen Rothwell <sfr@canb.auug.org.au> 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 <corbet@lwn.net>
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 <sfr@canb.auug.org.au>
Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 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