Received: by 10.223.176.5 with SMTP id f5csp447596wra; Fri, 9 Feb 2018 01:34:48 -0800 (PST) X-Google-Smtp-Source: AH8x226SiA2SJn+4qUYJgKZwfrlR3d0Yc15LIuPC1cgkOZrJsAYUh8aQf6iJEZbXbuk1+Fjtil7O X-Received: by 2002:a17:902:6bc3:: with SMTP id m3-v6mr1971989plt.442.1518168888827; Fri, 09 Feb 2018 01:34:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518168888; cv=none; d=google.com; s=arc-20160816; b=QRzfE9AY4xvowwpx1XXJhvTsy1XR6K0n3xwj28NM3+sDpjTQDqASTflwwDHZSIV9dd cYPDJmPxu9BUhmeTLJehcaEGxfeNaa9b1C6iSYoKB+/FI4SkASs30j0MhSJamrFbENt/ se3I6PDz7bQIuJU4cZamC8Jx2mhPERG9LbZ8FLVyXakzknYf5drXNQl785YAjki2kGM+ 1cN5gVv+c3N2Tr3Y0KYvlP3xgX4KJVThOAuI1RAOYvt5uHp66NVxmaxgAvkVyoqE0RSv 6GTQvF+Bp+MrXANImulcsazVEXxZ8wpxUHsrHeKKfEMjY/dqMOJoRmRZyaNyLrN1P28U 4Gjg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:mime-version:message-id:date:references :organization:in-reply-to:subject:cc:to:from :arc-authentication-results; bh=yfSurzC+Y7pC5vcosbgI1tHfaJ0iTY05C/G/b8XuL4E=; b=MCU8IJZk8VQ3f8KrN5NMeDW+UX7m7Gn696Cap0qIzssvNGFUUUqCKLo9vyDfax5hs2 z8XaKqZCnreFW2J+x3pqF7sPwofjgyf2K6mBmhphlgtCtVDsv0U1Rzk7+np9fvB9Aew3 2SQKXKRBxUBsitQs/OnxEkhlT1W3sZbTWHoexrZ7PSuSZ8gHNb7pAz7AOKsEKeXrwgzx ifgf2KVasYX3IMPDAC+NhKLX1Qux+UWkxTDfXe/zu0WRVoZJuY/tg8JZ0Dn8Mh0O661+ wsrQhPacYdhrjDHaWD79PFeCRMJ42nNnVhfUsh487xzPAzMnS+lxuDi60OIIGS9iO1Wa 9tsA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id bd7-v6si92557plb.823.2018.02.09.01.34.31; Fri, 09 Feb 2018 01:34:48 -0800 (PST) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752454AbeBIJc4 (ORCPT + 99 others); Fri, 9 Feb 2018 04:32:56 -0500 Received: from mga12.intel.com ([192.55.52.136]:60334 "EHLO mga12.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750973AbeBIJcx (ORCPT ); Fri, 9 Feb 2018 04:32:53 -0500 X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 Feb 2018 01:32:52 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,482,1511856000"; d="scan'208";a="29438417" Received: from jnikula-mobl2.fi.intel.com (HELO localhost) ([10.237.72.62]) by fmsmga001.fm.intel.com with ESMTP; 09 Feb 2018 01:32:50 -0800 From: Jani Nikula To: Jonathan Corbet , linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, Jonathan Corbet Subject: Re: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function In-Reply-To: <20180207172624.24555-6-corbet@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20180207172624.24555-1-corbet@lwn.net> <20180207172624.24555-6-corbet@lwn.net> Date: Fri, 09 Feb 2018 11:32:45 +0200 Message-ID: <877erma4oy.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 07 Feb 2018, Jonathan Corbet wrote: > Also group the pseudo-global $leading_space variable with its peers. > > Signed-off-by: Jonathan Corbet > --- > 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 + + 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 > + 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 + + 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