| Message ID | 20180207172624.24555-8-corbet@lwn.net |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Clean up kernel-doc and fix literal-block handling | expand |
On Wed, Feb 07, 2018 at 10:26:23AM -0700, Jonathan Corbet wrote: > Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now > actually fits on a single screen. Delete an unused variable and add a > couple of comments while I'm at it. > > Signed-off-by: Jonathan Corbet <corbet@lwn.net> > --- > scripts/kernel-doc | 145 ++++++++++++++++++++++++++++++----------------------- > 1 file changed, 83 insertions(+), 62 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index 2deddb876156..c6c9370a1e49 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -1990,10 +1990,86 @@ sub process_proto($$) { > } > } > > +# > +# STATE_DOCBLOCK: within a DOC: block. > +# > +sub process_docblock($$) { > + my $file = shift; > + > + if (/$doc_end/) > + { > + dump_doc_section($file, $section, $contents); > + $section = $section_default; > + $contents = ""; > + $function = ""; > + %parameterdescs = (); > + %parametertypes = (); > + @parameterlist = (); > + %sections = (); > + @sectionlist = (); > + $prototype = ""; > + $state = STATE_NORMAL; > + } > + elsif (/$doc_content/) > + { > + if ( $1 eq "" ) > + { > + $contents .= $blankline; > + } > + else > + { > + $contents .= $1 . "\n"; > + } > + } > +} It doesn't appear to be introduced by you but the brace positions are non-uniform in this patch. if { ... } else { ... } instead of if { ... } else { eee } Hope this helps, Tobin. (rest of patch left intentionally for reference) > + > +# > +# STATE_INLINE: docbook comments within a prototype. > +# > +sub process_inline($$) { > + my $file = shift; > + > + # First line (state 1) needs to be a @parameter > + if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { > + $section = $1; > + $contents = $2; > + $new_start_line = $.; > + if ($contents ne "") { > + while (substr($contents, 0, 1) eq " ") { > + $contents = substr($contents, 1); > + } > + $contents .= "\n"; > + } > + $inline_doc_state = STATE_INLINE_TEXT; > + # Documentation block end */ > + } elsif (/$doc_inline_end/) { > + if (($contents ne "") && ($contents ne "\n")) { > + dump_section($file, $section, $contents); > + $section = $section_default; > + $contents = ""; > + } > + $state = STATE_PROTO; > + $inline_doc_state = STATE_INLINE_NA; > + # Regular text > + } elsif (/$doc_content/) { > + if ($inline_doc_state == STATE_INLINE_TEXT) { > + $contents .= $1 . "\n"; > + # nuke leading blank lines > + if ($contents =~ /^\s*$/) { > + $contents = ""; > + } > + } elsif ($inline_doc_state == STATE_INLINE_NAME) { > + $inline_doc_state = STATE_INLINE_ERROR; > + print STDERR "${file}:$.: warning: "; > + print STDERR "Incorrect use of kernel-doc format: $_"; > + ++$warnings; > + } > + } > +} > + > > sub process_file($) { > my $file; > - my $func; > my $initial_section_counter = $section_counter; > my ($orig_file) = @_; > > @@ -2014,6 +2090,8 @@ sub process_file($) { > } > # Replace tabs by spaces > while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; > + > + # Hand this line to the appropriate state handler > if ($state == STATE_NORMAL) { > process_normal(); > } elsif ($state == STATE_NAME) { > @@ -2021,72 +2099,15 @@ sub process_file($) { > } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { > 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) { > - $section = $1; > - $contents = $2; > - $new_start_line = $.; > - if ($contents ne "") { > - while (substr($contents, 0, 1) eq " ") { > - $contents = substr($contents, 1); > - } > - $contents .= "\n"; > - } > - $inline_doc_state = STATE_INLINE_TEXT; > - # Documentation block end */ > - } elsif (/$doc_inline_end/) { > - if (($contents ne "") && ($contents ne "\n")) { > - dump_section($file, $section, $contents); > - $section = $section_default; > - $contents = ""; > - } > - $state = STATE_PROTO; > - $inline_doc_state = STATE_INLINE_NA; > - # Regular text > - } elsif (/$doc_content/) { > - if ($inline_doc_state == STATE_INLINE_TEXT) { > - $contents .= $1 . "\n"; > - # nuke leading blank lines > - if ($contents =~ /^\s*$/) { > - $contents = ""; > - } > - } elsif ($inline_doc_state == STATE_INLINE_NAME) { > - $inline_doc_state = STATE_INLINE_ERROR; > - print STDERR "${file}:$.: warning: "; > - print STDERR "Incorrect use of kernel-doc format: $_"; > - ++$warnings; > - } > - } > + process_inline($file, $_); > } elsif ($state == STATE_PROTO) { > process_proto($file, $_); > } elsif ($state == STATE_DOCBLOCK) { > - if (/$doc_end/) > - { > - dump_doc_section($file, $section, $contents); > - $section = $section_default; > - $contents = ""; > - $function = ""; > - %parameterdescs = (); > - %parametertypes = (); > - @parameterlist = (); > - %sections = (); > - @sectionlist = (); > - $prototype = ""; > - $state = STATE_NORMAL; > - } > - elsif (/$doc_content/) > - { > - if ( $1 eq "" ) > - { > - $contents .= $blankline; > - } > - else > - { > - $contents .= $1 . "\n"; > - } > - } > + process_docblock($file, $_); > } > } > + > + # Make sure we got something interesting. > if ($initial_section_counter == $section_counter) { > if ($output_mode ne "none") { > print STDERR "${file}:1: warning: no structured comments found\n"; > -- > 2.14.3 >
On Thu, 8 Feb 2018 13:29:53 +1100 "Tobin C. Harding" <me@tobin.cc> wrote: > It doesn't appear to be introduced by you but the brace positions are > non-uniform in this patch. > > if > { > ... > } > else > { > ... > } > > instead of > > if { > ... > } else { > eee > } True, that's worth fixing up while I'm in the neighborhood. I'll do that before I commit the set. Thanks, jon
On Thu, 08 Feb 2018, Jonathan Corbet <corbet@lwn.net> wrote: > On Thu, 8 Feb 2018 13:29:53 +1100 > "Tobin C. Harding" <me@tobin.cc> wrote: > >> It doesn't appear to be introduced by you but the brace positions are >> non-uniform in this patch. >> >> if >> { >> ... >> } >> else >> { >> ... >> } >> >> instead of >> >> if { >> ... >> } else { >> eee >> } > > True, that's worth fixing up while I'm in the neighborhood. I'll do that > before I commit the set. With that, Reviewed-by: Jani Nikula <jani.nikula@intel.com> > > Thanks, > > jon > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html -- Jani Nikula, Intel Open Source Technology Center
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 2deddb876156..c6c9370a1e49 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1990,10 +1990,86 @@ sub process_proto($$) { } } +# +# STATE_DOCBLOCK: within a DOC: block. +# +sub process_docblock($$) { + my $file = shift; + + if (/$doc_end/) + { + dump_doc_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + $function = ""; + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = STATE_NORMAL; + } + elsif (/$doc_content/) + { + if ( $1 eq "" ) + { + $contents .= $blankline; + } + else + { + $contents .= $1 . "\n"; + } + } +} + +# +# STATE_INLINE: docbook comments within a prototype. +# +sub process_inline($$) { + my $file = shift; + + # First line (state 1) needs to be a @parameter + if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { + $section = $1; + $contents = $2; + $new_start_line = $.; + if ($contents ne "") { + while (substr($contents, 0, 1) eq " ") { + $contents = substr($contents, 1); + } + $contents .= "\n"; + } + $inline_doc_state = STATE_INLINE_TEXT; + # Documentation block end */ + } elsif (/$doc_inline_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + $state = STATE_PROTO; + $inline_doc_state = STATE_INLINE_NA; + # Regular text + } elsif (/$doc_content/) { + if ($inline_doc_state == STATE_INLINE_TEXT) { + $contents .= $1 . "\n"; + # nuke leading blank lines + if ($contents =~ /^\s*$/) { + $contents = ""; + } + } elsif ($inline_doc_state == STATE_INLINE_NAME) { + $inline_doc_state = STATE_INLINE_ERROR; + print STDERR "${file}:$.: warning: "; + print STDERR "Incorrect use of kernel-doc format: $_"; + ++$warnings; + } + } +} + sub process_file($) { my $file; - my $func; my $initial_section_counter = $section_counter; my ($orig_file) = @_; @@ -2014,6 +2090,8 @@ sub process_file($) { } # Replace tabs by spaces while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; + + # Hand this line to the appropriate state handler if ($state == STATE_NORMAL) { process_normal(); } elsif ($state == STATE_NAME) { @@ -2021,72 +2099,15 @@ sub process_file($) { } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { 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) { - $section = $1; - $contents = $2; - $new_start_line = $.; - if ($contents ne "") { - while (substr($contents, 0, 1) eq " ") { - $contents = substr($contents, 1); - } - $contents .= "\n"; - } - $inline_doc_state = STATE_INLINE_TEXT; - # Documentation block end */ - } elsif (/$doc_inline_end/) { - if (($contents ne "") && ($contents ne "\n")) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - } - $state = STATE_PROTO; - $inline_doc_state = STATE_INLINE_NA; - # Regular text - } elsif (/$doc_content/) { - if ($inline_doc_state == STATE_INLINE_TEXT) { - $contents .= $1 . "\n"; - # nuke leading blank lines - if ($contents =~ /^\s*$/) { - $contents = ""; - } - } elsif ($inline_doc_state == STATE_INLINE_NAME) { - $inline_doc_state = STATE_INLINE_ERROR; - print STDERR "${file}:$.: warning: "; - print STDERR "Incorrect use of kernel-doc format: $_"; - ++$warnings; - } - } + process_inline($file, $_); } elsif ($state == STATE_PROTO) { process_proto($file, $_); } elsif ($state == STATE_DOCBLOCK) { - if (/$doc_end/) - { - dump_doc_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - $function = ""; - %parameterdescs = (); - %parametertypes = (); - @parameterlist = (); - %sections = (); - @sectionlist = (); - $prototype = ""; - $state = STATE_NORMAL; - } - elsif (/$doc_content/) - { - if ( $1 eq "" ) - { - $contents .= $blankline; - } - else - { - $contents .= $1 . "\n"; - } - } + process_docblock($file, $_); } } + + # Make sure we got something interesting. if ($initial_section_counter == $section_counter) { if ($output_mode ne "none") { print STDERR "${file}:1: warning: no structured comments found\n";
Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now actually fits on a single screen. Delete an unused variable and add a couple of comments while I'm at it. Signed-off-by: Jonathan Corbet <corbet@lwn.net> --- scripts/kernel-doc | 145 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 62 deletions(-) -- 2.14.3