| Message ID | 20180207172624.24555-5-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: > Move this code out of process_file() in the name of readability and > maintainability. > > Signed-off-by: Jonathan Corbet <corbet@lwn.net> I admit I don't fully understand the semantics of perl parameter passing, but looks okay. Reviewed-by: Jani Nikula <jani.nikula@intel.com> > --- > scripts/kernel-doc | 137 ++++++++++++++++++++++++++++------------------------- > 1 file changed, 72 insertions(+), 65 deletions(-) > > diff --git a/scripts/kernel-doc b/scripts/kernel-doc > index 65150b7c8472..a27c7016f72d 100755 > --- a/scripts/kernel-doc > +++ b/scripts/kernel-doc > @@ -1793,13 +1793,81 @@ sub process_normal() { > } > } > > +# > +# STATE_NAME: Looking for the "name - description" line > +# > +sub process_name($$) { > + my $file = shift; > + my $identifier; > + my $descr; > + > + if (/$doc_block/o) { > + $state = STATE_DOCBLOCK; > + $contents = ""; > + $new_start_line = $. + 1; > + > + if ( $1 eq "" ) { > + $section = $section_intro; > + } else { > + $section = $1; > + } > + } > + elsif (/$doc_decl/o) { > + $identifier = $1; > + if (/\s*([\w\s]+?)\s*-/) { > + $identifier = $1; > + } > > + $state = STATE_BODY; > + # if there's no @param blocks need to set up default section > + # here > + $contents = ""; > + $section = $section_default; > + $new_start_line = $. + 1; > + if (/-(.*)/) { > + # strip leading/trailing/multiple spaces > + $descr= $1; > + $descr =~ s/^\s*//; > + $descr =~ s/\s*$//; > + $descr =~ s/\s+/ /g; > + $declaration_purpose = $descr; > + $state = STATE_BODY_MAYBE; > + } else { > + $declaration_purpose = ""; > + } > + > + if (($declaration_purpose eq "") && $verbose) { > + print STDERR "${file}:$.: warning: missing initial short description on line:\n"; > + print STDERR $_; > + ++$warnings; > + } > + > + if ($identifier =~ m/^struct/) { > + $decl_type = 'struct'; > + } elsif ($identifier =~ m/^union/) { > + $decl_type = 'union'; > + } elsif ($identifier =~ m/^enum/) { > + $decl_type = 'enum'; > + } elsif ($identifier =~ m/^typedef/) { > + $decl_type = 'typedef'; > + } else { > + $decl_type = 'function'; > + } > + > + if ($verbose) { > + print STDERR "${file}:$.: info: Scanning doc for $identifier\n"; > + } > + } else { > + print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", > + " - I thought it was a doc line\n"; > + ++$warnings; > + $state = STATE_NORMAL; > + } > +} > > sub process_file($) { > my $file; > - my $identifier; > my $func; > - my $descr; > my $initial_section_counter = $section_counter; > my ($orig_file) = @_; > my $leading_space; > @@ -1823,69 +1891,8 @@ sub process_file($) { > while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; > if ($state == STATE_NORMAL) { > process_normal(); > - } elsif ($state == STATE_NAME) {# this line is the function name (always) > - if (/$doc_block/o) { > - $state = STATE_DOCBLOCK; > - $contents = ""; > - $new_start_line = $. + 1; > - > - if ( $1 eq "" ) { > - $section = $section_intro; > - } else { > - $section = $1; > - } > - } > - elsif (/$doc_decl/o) { > - $identifier = $1; > - if (/\s*([\w\s]+?)\s*-/) { > - $identifier = $1; > - } > - > - $state = STATE_BODY; > - # if there's no @param blocks need to set up default section > - # here > - $contents = ""; > - $section = $section_default; > - $new_start_line = $. + 1; > - if (/-(.*)/) { > - # strip leading/trailing/multiple spaces > - $descr= $1; > - $descr =~ s/^\s*//; > - $descr =~ s/\s*$//; > - $descr =~ s/\s+/ /g; > - $declaration_purpose = $descr; > - $state = STATE_BODY_MAYBE; > - } else { > - $declaration_purpose = ""; > - } > - > - if (($declaration_purpose eq "") && $verbose) { > - print STDERR "${file}:$.: warning: missing initial short description on line:\n"; > - print STDERR $_; > - ++$warnings; > - } > - > - if ($identifier =~ m/^struct/) { > - $decl_type = 'struct'; > - } elsif ($identifier =~ m/^union/) { > - $decl_type = 'union'; > - } elsif ($identifier =~ m/^enum/) { > - $decl_type = 'enum'; > - } elsif ($identifier =~ m/^typedef/) { > - $decl_type = 'typedef'; > - } else { > - $decl_type = 'function'; > - } > - > - if ($verbose) { > - print STDERR "${file}:$.: info: Scanning doc for $identifier\n"; > - } > - } else { > - print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", > - " - I thought it was a doc line\n"; > - ++$warnings; > - $state = STATE_NORMAL; > - } > + } 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; -- Jani Nikula, Intel Open Source Technology Center
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 65150b7c8472..a27c7016f72d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1793,13 +1793,81 @@ sub process_normal() { } } +# +# STATE_NAME: Looking for the "name - description" line +# +sub process_name($$) { + my $file = shift; + my $identifier; + my $descr; + + if (/$doc_block/o) { + $state = STATE_DOCBLOCK; + $contents = ""; + $new_start_line = $. + 1; + + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_decl/o) { + $identifier = $1; + if (/\s*([\w\s]+?)\s*-/) { + $identifier = $1; + } + $state = STATE_BODY; + # if there's no @param blocks need to set up default section + # here + $contents = ""; + $section = $section_default; + $new_start_line = $. + 1; + if (/-(.*)/) { + # strip leading/trailing/multiple spaces + $descr= $1; + $descr =~ s/^\s*//; + $descr =~ s/\s*$//; + $descr =~ s/\s+/ /g; + $declaration_purpose = $descr; + $state = STATE_BODY_MAYBE; + } else { + $declaration_purpose = ""; + } + + if (($declaration_purpose eq "") && $verbose) { + print STDERR "${file}:$.: warning: missing initial short description on line:\n"; + print STDERR $_; + ++$warnings; + } + + if ($identifier =~ m/^struct/) { + $decl_type = 'struct'; + } elsif ($identifier =~ m/^union/) { + $decl_type = 'union'; + } elsif ($identifier =~ m/^enum/) { + $decl_type = 'enum'; + } elsif ($identifier =~ m/^typedef/) { + $decl_type = 'typedef'; + } else { + $decl_type = 'function'; + } + + if ($verbose) { + print STDERR "${file}:$.: info: Scanning doc for $identifier\n"; + } + } else { + print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", + " - I thought it was a doc line\n"; + ++$warnings; + $state = STATE_NORMAL; + } +} sub process_file($) { my $file; - my $identifier; my $func; - my $descr; my $initial_section_counter = $section_counter; my ($orig_file) = @_; my $leading_space; @@ -1823,69 +1891,8 @@ sub process_file($) { while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; if ($state == STATE_NORMAL) { process_normal(); - } elsif ($state == STATE_NAME) {# this line is the function name (always) - if (/$doc_block/o) { - $state = STATE_DOCBLOCK; - $contents = ""; - $new_start_line = $. + 1; - - if ( $1 eq "" ) { - $section = $section_intro; - } else { - $section = $1; - } - } - elsif (/$doc_decl/o) { - $identifier = $1; - if (/\s*([\w\s]+?)\s*-/) { - $identifier = $1; - } - - $state = STATE_BODY; - # if there's no @param blocks need to set up default section - # here - $contents = ""; - $section = $section_default; - $new_start_line = $. + 1; - if (/-(.*)/) { - # strip leading/trailing/multiple spaces - $descr= $1; - $descr =~ s/^\s*//; - $descr =~ s/\s*$//; - $descr =~ s/\s+/ /g; - $declaration_purpose = $descr; - $state = STATE_BODY_MAYBE; - } else { - $declaration_purpose = ""; - } - - if (($declaration_purpose eq "") && $verbose) { - print STDERR "${file}:$.: warning: missing initial short description on line:\n"; - print STDERR $_; - ++$warnings; - } - - if ($identifier =~ m/^struct/) { - $decl_type = 'struct'; - } elsif ($identifier =~ m/^union/) { - $decl_type = 'union'; - } elsif ($identifier =~ m/^enum/) { - $decl_type = 'enum'; - } elsif ($identifier =~ m/^typedef/) { - $decl_type = 'typedef'; - } else { - $decl_type = 'function'; - } - - if ($verbose) { - print STDERR "${file}:$.: info: Scanning doc for $identifier\n"; - } - } else { - print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", - " - I thought it was a doc line\n"; - ++$warnings; - $state = STATE_NORMAL; - } + } 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;
Move this code out of process_file() in the name of readability and maintainability. Signed-off-by: Jonathan Corbet <corbet@lwn.net> --- scripts/kernel-doc | 137 ++++++++++++++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 65 deletions(-) -- 2.14.3