Received: by 10.223.176.5 with SMTP id f5csp444104wra; Fri, 9 Feb 2018 01:30:46 -0800 (PST) X-Google-Smtp-Source: AH8x227S8h77MfRHA8I/JbuGh/5ZAVb7XqMmosv58s6dmb/FyVhO7+G5fhWkGg6PVPzpO47havor X-Received: by 2002:a17:902:968b:: with SMTP id n11-v6mr1985777plp.168.1518168646822; Fri, 09 Feb 2018 01:30:46 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518168646; cv=none; d=google.com; s=arc-20160816; b=BhhLhjXOhmANr7tUm1lhLM1hftJ1uT8NG5732JOz4fPuhuBWZhLk6cd4JL50U43+CV YHJt7SnxkLSLbxIAdkAoQ9WmxFpQprLEJzlnUrDo0rD9jsE7t5jupyvekmwjgVld220m aW85ngx5JGDEya6dl7W2VmZdIPS8yeM3SlL2IctJDgNJKznHks10tbQ/cQRVtzWuijVH VDgE/gSEfvlULYe1hf1SFng2dmpDaVH1H96AV+Ne3945tFvACnEYl0rNPF+5/8o2gc4l nLwF3w+sSbMT7hxnQCea4NPWnogdmipstRJcInKZbxeGcPfQaeQVkuQHOKa7/miZhV5Y CzKQ== 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=StIQ0T2OZ217NdcFGGR7M1Nkil1OYmTZUEGuVTSPpd0=; b=wpH0MaHSkudstHOCeSvY1gPtoiaxpoKLdH7ST4x/i6FHB3SIR/xPiVgVBrT3MrdAMl DlDdfpye7zx94MtKBtY7NLcPI6VfxGRDD6U3Qr/FUCMRVzn9yLyfVvNxBp6Df1O2RWvI 9tiP/CggFxIWjxs44KYAtU4VgRVRRqUJ0CbjjYwyl+S2w7ZlCGKupI7L0gulvMVKwIUG UcTCRtgIDCix7BCvEDdDYpWe+XgccVcFoBFca0toEL0r20PsbzQNsY0Wuhpg2hhsXq3+ z+kIvzbIn7w10aRhdyFVW7f9fvvJUxpjtenn+F23UoZwXjoz02026xeZCPo+KAQ/wdN3 +6Ew== 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 b59-v6si1305643plb.514.2018.02.09.01.30.29; Fri, 09 Feb 2018 01:30:46 -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 S1752606AbeBIJ1c (ORCPT + 99 others); Fri, 9 Feb 2018 04:27:32 -0500 Received: from mga03.intel.com ([134.134.136.65]:28183 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751034AbeBIJ12 (ORCPT ); Fri, 9 Feb 2018 04:27:28 -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 orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 Feb 2018 01:27:28 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.46,482,1511856000"; d="scan'208";a="29437356" Received: from jnikula-mobl2.fi.intel.com (HELO localhost) ([10.237.72.62]) by fmsmga001.fm.intel.com with ESMTP; 09 Feb 2018 01:27:26 -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 4/8] docs: kernel-doc: Move STATE_NAME processing into its own function In-Reply-To: <20180207172624.24555-5-corbet@lwn.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20180207172624.24555-1-corbet@lwn.net> <20180207172624.24555-5-corbet@lwn.net> Date: Fri, 09 Feb 2018 11:27:20 +0200 Message-ID: <87a7wia4xz.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: > Move this code out of process_file() in the name of readability and > maintainability. > > Signed-off-by: Jonathan Corbet I admit I don't fully understand the semantics of perl parameter passing, but looks okay. Reviewed-by: Jani Nikula > --- > scripts/kernel-doc | 137 ++++++++++++++++++++++++++++------------------------- > 1 file 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; -- Jani Nikula, Intel Open Source Technology Center