| Message ID | 20180207172624.24555-6-corbet@lwn.net |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Clean up kernel-doc and fix literal-block handling | expand |
On Wed, 07 Feb 2018, Jonathan Corbet <corbet@lwn.net> wrote: > Also group the pseudo-global $leading_space variable with its peers. > > Signed-off-by: Jonathan Corbet <corbet@lwn.net> > --- > scripts/kernel-doc | 193 ++++++++++++++++++++++++++++------------------------- > 1 file changed, 101 insertions(+), 92 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index a27c7016f72d..a6a7bb46ea29 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -336,6 +336,7 @@ use constant { > }; > my $state; > my $in_doc_sect; > +my $leading_space; > > # Inline documentation state > use constant { > @@ -1865,12 +1866,110 @@ sub process_name($$) { > } > } > > + > +# > +# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. > +# > +sub process_body($$) { > + my $file = shift; > + > + 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"; > + ++$warnings; > + } > + dump_section($file, $section, $contents); > + $section = $section_default; > + } > + > + $in_doc_sect = 1; > + $state = STATE_BODY; > + $contents = $newcontents; > + $new_start_line = $.; > + while (substr($contents, 0, 1) eq " ") { > + $contents = substr($contents, 1); > + } > + if ($contents ne "") { > + $contents .= "\n"; > + } > + $section = $newsection; > + $leading_space = undef; > + } elsif (/$doc_end/) { > + if (($contents ne "") && ($contents ne "\n")) { > + dump_section($file, $section, $contents); > + $section = $section_default; > + $contents = ""; > + } > + # look for doc_com + <text> + doc_end: > + if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { > + print STDERR "${file}:$.: warning: suspicious ending line: $_"; > + ++$warnings; > + } > + > + $prototype = ""; > + $state = STATE_PROTO; > + $brcount = 0; > + } elsif (/$doc_content/) { > + # miguel-style comment kludge, look for blank lines after > + # @parameter line to signify start of description The "miguel-style" always intrigued me, but its origin predates git history. Does anyone know? Reviewed-by: Jani Nikula <jani.nikula@intel.com> > + if ($1 eq "") { > + if ($section =~ m/^@/ || $section eq $section_context) { > + dump_section($file, $section, $contents); > + $section = $section_default; > + $contents = ""; > + $new_start_line = $.; > + } else { > + $contents .= "\n"; > + } > + $state = STATE_BODY; > + } elsif ($state == STATE_BODY_MAYBE) { > + # Continued declaration purpose > + chomp($declaration_purpose); > + $declaration_purpose .= " " . $1; > + $declaration_purpose =~ s/\s+/ /g; > + } else { > + my $cont = $1; > + if ($section =~ m/^@/ || $section eq $section_context) { > + if (!defined $leading_space) { > + if ($cont =~ m/^(\s+)/) { > + $leading_space = $1; > + } else { > + $leading_space = ""; > + } > + } > + $cont =~ s/^$leading_space//; > + } > + $contents .= $cont . "\n"; > + } > + } else { > + # i dont know - bad line? ignore. > + print STDERR "${file}:$.: warning: bad line: $_"; > + ++$warnings; > + } > +} > + > + > sub process_file($) { > my $file; > my $func; > my $initial_section_counter = $section_counter; > my ($orig_file) = @_; > - my $leading_space; > > $file = map_filename($orig_file); > > @@ -1894,97 +1993,7 @@ sub process_file($) { > } elsif ($state == STATE_NAME) { > process_name($file, $_); > } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { > - 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"; > - ++$warnings; > - } > - dump_section($file, $section, $contents); > - $section = $section_default; > - } > - > - $in_doc_sect = 1; > - $state = STATE_BODY; > - $contents = $newcontents; > - $new_start_line = $.; > - while (substr($contents, 0, 1) eq " ") { > - $contents = substr($contents, 1); > - } > - if ($contents ne "") { > - $contents .= "\n"; > - } > - $section = $newsection; > - $leading_space = undef; > - } elsif (/$doc_end/) { > - if (($contents ne "") && ($contents ne "\n")) { > - dump_section($file, $section, $contents); > - $section = $section_default; > - $contents = ""; > - } > - # look for doc_com + <text> + doc_end: > - if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { > - print STDERR "${file}:$.: warning: suspicious ending line: $_"; > - ++$warnings; > - } > - > - $prototype = ""; > - $state = STATE_PROTO; > - $brcount = 0; > -# print STDERR "end of doc comment, looking for prototype\n"; > - } elsif (/$doc_content/) { > - # miguel-style comment kludge, look for blank lines after > - # @parameter line to signify start of description > - if ($1 eq "") { > - if ($section =~ m/^@/ || $section eq $section_context) { > - dump_section($file, $section, $contents); > - $section = $section_default; > - $contents = ""; > - $new_start_line = $.; > - } else { > - $contents .= "\n"; > - } > - $state = STATE_BODY; > - } elsif ($state == STATE_BODY_MAYBE) { > - # Continued declaration purpose > - chomp($declaration_purpose); > - $declaration_purpose .= " " . $1; > - $declaration_purpose =~ s/\s+/ /g; > - } else { > - my $cont = $1; > - if ($section =~ m/^@/ || $section eq $section_context) { > - if (!defined $leading_space) { > - if ($cont =~ m/^(\s+)/) { > - $leading_space = $1; > - } else { > - $leading_space = ""; > - } > - } > - > - $cont =~ s/^$leading_space//; > - } > - $contents .= $cont . "\n"; > - } > - } else { > - # i dont know - bad line? ignore. > - print STDERR "${file}:$.: warning: bad line: $_"; > - ++$warnings; > - } > + process_body($file, $_); > } elsif ($state == STATE_INLINE) { # scanning for inline parameters > # First line (state 1) needs to be a @parameter > if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { -- Jani Nikula, Intel Open Source Technology Center
On Fri, Feb 9, 2018 at 1:32 AM, Jani Nikula <jani.nikula@linux.intel.com> wrote: >> + # miguel-style comment kludge, look for blank lines after >> + # @parameter line to signify start of description > > The "miguel-style" always intrigued me, but its origin predates git > history. Does anyone know? It came with the original script in 2.3.52-pre1, somewhere around March 2000. (Historical footnote: there was no actual 2.3.52 ever released - it was supposed turn into 2.4, but there was a long line of 2.3.99-pre kernels before that then finally happened early 2001). But no, back then we didn't track things well enough to have an actual reason. And even with git, we probably wouldn't have had a reason since it came in the initial patch. You'd have to go search emails if you really care. That "around March 2000" would at least give you a starting point for searches. Linus
On Fri, 09 Feb 2018, Linus Torvalds <torvalds@linux-foundation.org> wrote: > On Fri, Feb 9, 2018 at 1:32 AM, Jani Nikula <jani.nikula@linux.intel.com> wrote: >>> + # miguel-style comment kludge, look for blank lines after >>> + # @parameter line to signify start of description >> >> The "miguel-style" always intrigued me, but its origin predates git >> history. Does anyone know? > > It came with the original script in 2.3.52-pre1, somewhere around March 2000. > > (Historical footnote: there was no actual 2.3.52 ever released - it > was supposed turn into 2.4, but there was a long line of 2.3.99-pre > kernels before that then finally happened early 2001). > > But no, back then we didn't track things well enough to have an actual > reason. And even with git, we probably wouldn't have had a reason > since it came in the initial patch. > > You'd have to go search emails if you really care. That "around March > 2000" would at least give you a starting point for searches. Thanks for the background digging! I had a cursory look at the list archives, nothing much jumped at me but I found that the script was originally called gdoc. A little googling revealed that other forks of the script predating inclusion to the kernel also included the comment. I'll bet whoever added that didn't think someone would wonder about it two decades later. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a27c7016f72d..a6a7bb46ea29 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -336,6 +336,7 @@ use constant { }; my $state; my $in_doc_sect; +my $leading_space; # Inline documentation state use constant { @@ -1865,12 +1866,110 @@ sub process_name($$) { } } + +# +# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. +# +sub process_body($$) { + my $file = shift; + + 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"; + ++$warnings; + } + dump_section($file, $section, $contents); + $section = $section_default; + } + + $in_doc_sect = 1; + $state = STATE_BODY; + $contents = $newcontents; + $new_start_line = $.; + while (substr($contents, 0, 1) eq " ") { + $contents = substr($contents, 1); + } + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + $leading_space = undef; + } elsif (/$doc_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + # look for doc_com + <text> + doc_end: + if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { + print STDERR "${file}:$.: warning: suspicious ending line: $_"; + ++$warnings; + } + + $prototype = ""; + $state = STATE_PROTO; + $brcount = 0; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "") { + if ($section =~ m/^@/ || $section eq $section_context) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + $new_start_line = $.; + } else { + $contents .= "\n"; + } + $state = STATE_BODY; + } elsif ($state == STATE_BODY_MAYBE) { + # Continued declaration purpose + chomp($declaration_purpose); + $declaration_purpose .= " " . $1; + $declaration_purpose =~ s/\s+/ /g; + } else { + my $cont = $1; + if ($section =~ m/^@/ || $section eq $section_context) { + if (!defined $leading_space) { + if ($cont =~ m/^(\s+)/) { + $leading_space = $1; + } else { + $leading_space = ""; + } + } + $cont =~ s/^$leading_space//; + } + $contents .= $cont . "\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "${file}:$.: warning: bad line: $_"; + ++$warnings; + } +} + + sub process_file($) { my $file; my $func; my $initial_section_counter = $section_counter; my ($orig_file) = @_; - my $leading_space; $file = map_filename($orig_file); @@ -1894,97 +1993,7 @@ sub process_file($) { } elsif ($state == STATE_NAME) { process_name($file, $_); } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { - 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"; - ++$warnings; - } - dump_section($file, $section, $contents); - $section = $section_default; - } - - $in_doc_sect = 1; - $state = STATE_BODY; - $contents = $newcontents; - $new_start_line = $.; - while (substr($contents, 0, 1) eq " ") { - $contents = substr($contents, 1); - } - if ($contents ne "") { - $contents .= "\n"; - } - $section = $newsection; - $leading_space = undef; - } elsif (/$doc_end/) { - if (($contents ne "") && ($contents ne "\n")) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - } - # look for doc_com + <text> + doc_end: - if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { - print STDERR "${file}:$.: warning: suspicious ending line: $_"; - ++$warnings; - } - - $prototype = ""; - $state = STATE_PROTO; - $brcount = 0; -# print STDERR "end of doc comment, looking for prototype\n"; - } elsif (/$doc_content/) { - # miguel-style comment kludge, look for blank lines after - # @parameter line to signify start of description - if ($1 eq "") { - if ($section =~ m/^@/ || $section eq $section_context) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - $new_start_line = $.; - } else { - $contents .= "\n"; - } - $state = STATE_BODY; - } elsif ($state == STATE_BODY_MAYBE) { - # Continued declaration purpose - chomp($declaration_purpose); - $declaration_purpose .= " " . $1; - $declaration_purpose =~ s/\s+/ /g; - } else { - my $cont = $1; - if ($section =~ m/^@/ || $section eq $section_context) { - if (!defined $leading_space) { - if ($cont =~ m/^(\s+)/) { - $leading_space = $1; - } else { - $leading_space = ""; - } - } - - $cont =~ s/^$leading_space//; - } - $contents .= $cont . "\n"; - } - } else { - # i dont know - bad line? ignore. - print STDERR "${file}:$.: warning: bad line: $_"; - ++$warnings; - } + process_body($file, $_); } elsif ($state == STATE_INLINE) { # scanning for inline parameters # First line (state 1) needs to be a @parameter if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
Also group the pseudo-global $leading_space variable with its peers. Signed-off-by: Jonathan Corbet <corbet@lwn.net> --- scripts/kernel-doc | 193 ++++++++++++++++++++++++++++------------------------- 1 file changed, 101 insertions(+), 92 deletions(-) -- 2.14.3