| lists.openwall.net | lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC | |
|
Open Source and information security mailing list archives
| ||
|
Message-ID: <877erma4oy.fsf@intel.com>
Date: Fri, 09 Feb 2018 11:32:45 +0200
From: Jani Nikula <jani.nikula@...ux.intel.com>
To: Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org, mchehab@...nel.org, me@...in.cc,
Jonathan Corbet <corbet@....net>
Subject: Re: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function
On Wed, 07 Feb 2018, Jonathan Corbet <corbet@....net> wrote:
> Also group the pseudo-global $leading_space variable with its peers.
>
> Signed-off-by: Jonathan Corbet <corbet@....net>
> ---
> scripts/kernel-doc | 193 ++++++++++++++++++++++++++++-------------------------
> 1 file changed, 101 insertions(+), 92 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index a27c7016f72d..a6a7bb46ea29 100755
> --- 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
The "miguel-style" always intrigued me, but its origin predates git
history. Does anyone know?
Reviewed-by: Jani Nikula <jani.nikula@...el.com>
> + 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) {
--
Jani Nikula, Intel Open Source Technology Center
Powered by blists - more mailing lists