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>
This commit is contained in:
Jonathan Corbet
parent
3cac2bc41d
commit
d742f24d6c
|
|
@ -336,6 +336,7 @@ use constant {
|
||||||
};
|
};
|
||||||
my $state;
|
my $state;
|
||||||
my $in_doc_sect;
|
my $in_doc_sect;
|
||||||
|
my $leading_space;
|
||||||
|
|
||||||
# Inline documentation state
|
# Inline documentation state
|
||||||
use constant {
|
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($) {
|
sub process_file($) {
|
||||||
my $file;
|
my $file;
|
||||||
my $func;
|
my $func;
|
||||||
my $initial_section_counter = $section_counter;
|
my $initial_section_counter = $section_counter;
|
||||||
my ($orig_file) = @_;
|
my ($orig_file) = @_;
|
||||||
my $leading_space;
|
|
||||||
|
|
||||||
$file = map_filename($orig_file);
|
$file = map_filename($orig_file);
|
||||||
|
|
||||||
|
|
@ -1894,97 +1993,7 @@ sub process_file($) {
|
||||||
} elsif ($state == STATE_NAME) {
|
} elsif ($state == STATE_NAME) {
|
||||||
process_name($file, $_);
|
process_name($file, $_);
|
||||||
} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
|
} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
|
||||||
if (/$doc_sect/i) { # case insensitive for supported section names
|
process_body($file, $_);
|
||||||
$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;
|
|
||||||
}
|
|
||||||
} elsif ($state == STATE_INLINE) { # scanning for inline parameters
|
} elsif ($state == STATE_INLINE) { # scanning for inline parameters
|
||||||
# First line (state 1) needs to be a @parameter
|
# First line (state 1) needs to be a @parameter
|
||||||
if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
|
if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue