From patchwork Wed Feb 7 17:26:21 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 127199 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp683937ljc; Wed, 7 Feb 2018 09:28:05 -0800 (PST) X-Google-Smtp-Source: AH8x225A+bAXIcXH3x6oAUOrGTGXBKN9gVGRCa0dPs166M5eT4YCHsdKT7lpFALuFKFNWW4LN6X7 X-Received: by 10.98.98.1 with SMTP id w1mr6723466pfb.9.1518024484880; Wed, 07 Feb 2018 09:28:04 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518024484; cv=none; d=google.com; s=arc-20160816; b=PqxbgSTqpiqOPzse6k+l+drtgb3e0mPL1a1zBNenCjKJAJwS8hWFjJQnxMHQ3orqoP DdPMEsWaa1BgTj0mh2++0TNcfkfDlEBVNOPuZquhoRbXDgWgNkbhCfkn00fHUKAB89qX OvO5fKpr6UC+f67O2GrTc8eHexU23OGGMgNaj48wcbxKFuo2AHP2rdAT3oXrpQk7xnZX 3aHRmZQKdL6x83QFusxUnxs8tj1y6fcOIt+8T11/6SeAAyHTDaSagRGgwoX4B0Oe4NHX siseNu4cJtZsSa1cEmSNuLxN/yqFBV28JmGKt26qyvwJIBsOEvy7bMWpkjQz7J1UR9l0 YfIQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:arc-authentication-results; bh=DJAklSxwQMKVgAJWcYu4/hVGBg7LYRdS/FuZTtT586g=; b=dLdx5J4EFgtl3gekySATkK9atNGtuULFLJIte6H8SHeifJUAPxC1DKCbiBQbw95et+ +tdi9ngjximv5lTkJ+T23c8MSvRceu/IWAuPcK/cHX5PuGaUS8kMl7vqg0Q0SWAYGiPb pglgeXb3tQ29W9DotdXG9t7j7RzCFqlDru6ndq7ClGYyxbLa/elQJ4O+DIGoc2vl9ZDL Fo31PRjCpaON5pgl6b8ZnTpU1s3KUsNxXxzfAfRLfZPhbjOidT+KIDrPHmwuX71Luzic c8+2T1aKmqq8+RLZApmCvq0aC5jenyRXW21n1YbZjZtoEGENrjDkCC284UeFKWXayVvo nsnw== 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 f10si1176226pgu.783.2018.02.07.09.28.04; Wed, 07 Feb 2018 09:28:04 -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 S1754927AbeBGR2C (ORCPT + 18 others); Wed, 7 Feb 2018 12:28:02 -0500 Received: from ms.lwn.net ([45.79.88.28]:41646 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754843AbeBGR1E (ORCPT ); Wed, 7 Feb 2018 12:27:04 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id AA8A8491; Wed, 7 Feb 2018 17:27:03 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, Jonathan Corbet Subject: [PATCH 5/8] docs: kernel-doc: Move STATE_BODY processing to a separate function Date: Wed, 7 Feb 2018 10:26:21 -0700 Message-Id: <20180207172624.24555-6-corbet@lwn.net> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180207172624.24555-1-corbet@lwn.net> References: <20180207172624.24555-1-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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(-) -- 2.14.3 Reviewed-by: Jani Nikula 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 + 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) {