summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2018-02-05 14:36:33 -0700
committerJonathan Corbet <corbet@lwn.net>2018-02-15 13:11:23 -0700
commit3cac2bc41d1b4c51a1f31059bf65f4dc7cfb35f5 (patch)
treecd50d1907ed9282aa78b9cae77e651b24318196a
parent07048d13136bc068efb20e1d3e372577c2ef6906 (diff)
docs: kernel-doc: Move STATE_NAME processing into its own function
Move this code out of process_file() in the name of readability and maintainability. Reviewed-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
-rwxr-xr-xscripts/kernel-doc137
1 files 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;