summaryrefslogtreecommitdiffstats
path: root/scripts
diff options
context:
space:
mode:
authorJani Nikula <jani.nikula@intel.com>2016-05-29 10:35:28 +0200
committerJani Nikula <jani.nikula@intel.com>2016-05-30 12:39:03 +0200
commitf624adef3d0b9975076c1ba7549b81ed19e34437 (patch)
treeae4daa883a857b6ec178d1b9371ca9fe9f68889c /scripts
parentkernel-doc/rst: remove fixme comment (diff)
downloadlinux-f624adef3d0b9975076c1ba7549b81ed19e34437.tar.xz
linux-f624adef3d0b9975076c1ba7549b81ed19e34437.zip
kernel-doc: limit the "section header:" detection to a select few
kernel-doc currently identifies anything matching "section header:" (specifically a string of word characters and spaces followed by a colon) as a new section in the documentation comment, and renders the section header accordingly. Unfortunately, this turns all uses of colon into sections, mostly unintentionally. Considering the output, erroneously creating sections when not intended is always worse than erroneously not creating sections when intended. For example, a line with "http://example.com" turns into a "http" heading followed by "//example.com" in normal text style, which is quite ugly. OTOH, "WARNING: Beware of the Leopard" is just fine even if "WARNING" does not turn into a heading. It is virtually impossible to change all the kernel-doc comments, either way. The compromise is to pick the most commonly used and depended on section headers (with variants) and accept them as section headers. The accepted section headers are, case insensitive: * description: * context: * return: * returns: Additionally, case sensitive: * @return: All of the above are commonly used in the kernel-doc comments, and will result in worse output if not identified as section headers. Also, kernel-doc already has some special handling for all of them, so there's nothing particularly controversial in adding more special treatment for them. While at it, improve the whitespace handling surrounding section names. Do not consider the whitespace as part of the name. Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/kernel-doc19
1 files changed, 17 insertions, 2 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 425a94be04f6..20136564f264 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -401,7 +401,8 @@ my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
-my $doc_sect = $doc_com . '(\@?[\w\s]+):(.*)';
+# @params and a strictly limited set of supported section names
+my $doc_sect = $doc_com . '\s*(\@\w+|description|context|returns?)\s*:(.*)';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -417,6 +418,8 @@ my $sectcheck;
my $struct_actual;
my $contents = "";
+
+# the canonical section names. see also $doc_sect above.
my $section_default = "Description"; # default section
my $section_intro = "Introduction";
my $section = $section_default;
@@ -2798,10 +2801,22 @@ sub process_file($) {
$state = STATE_NORMAL;
}
} elsif ($state == STATE_FIELD) { # look for head: lines, and include content
- if (/$doc_sect/o) {
+ if (/$doc_sect/i) { # case insensitive for supported section names
$newsection = $1;
$newcontents = $2;
+ # map the supported section names to the canonical names
+ if ($newsection =~ m/^description$/i) {
+ $newsection = $section_default;
+ } elsif ($newsection =~ m/^context$/i) {
+ $newsection = $section_context;
+ } elsif ($newsection =~ m/^returns?$/i) {
+ $newsection = $section_return;
+ } elsif ($newsection =~ m/^\@return$/) {
+ # special: @return is a section, not a param description
+ $newsection = $section_return;
+ }
+
if (($contents ne "") && ($contents ne "\n")) {
if (!$in_doc_sect && $verbose) {
print STDERR "${file}:$.: warning: contents before sections\n";