docs: kernel-doc: Move STATE_BODY processing to a separate function

Also group the pseudo-global $leading_space variable with its peers.

Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index a27c7016f72def376fef7060116edec80ed4adf1..a6a7bb46ea2967c6fe01c271c2b079e7fc8197da 100755 (executable)
--- 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) {