iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

kernel-doc: limit the "section header:" detection to a select few

Browse Source 
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>
This commit is contained in:
Jani Nikula 2016-05-29 11:35:28 +03:00
parent cddfe325af
commit f624adef3d
1 changed files with 17 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
scripts/kernel-doc
View File

@ -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";