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.

Jonathan Corbet committed 5 years ago

Commit 212209c1 parent 8d295fb1 file · +7 −1Browse files

Unified · Split

scripts/kernel-doc+7−1

 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*$';