From patchwork Wed Feb 14 18:40:08 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 128378 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp911750ljc; Wed, 14 Feb 2018 10:40:55 -0800 (PST) X-Google-Smtp-Source: AH8x225UQ788sE1f5W9u7ZSq/vIeVPE5AS/Fgx50u7HOOqP45cpvZwvucZkk+aJtrjMEZi9YfkFo X-Received: by 10.98.97.198 with SMTP id v189mr28996pfb.110.1518633655674; Wed, 14 Feb 2018 10:40:55 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518633655; cv=none; d=google.com; s=arc-20160816; b=mgQ+l87p2OR6DooQc7eVz8LzYPUaIyWMw1Qlj7esekmtkazLK2SBDIzOukbpO8La44 GFbabVrIrEQoU1305ZWwBi/w2OXS2isOSLM1yXnxOfv0DB7HfQ5MPk/y0m7c9TYgOFu8 kt+onM62gGSTFUCXHMap/Wu74GhBWjQxJMQAfAFr4s3+wXx2W0d4BlSqIlLXc6cBhMk5 VByYCdGKOBrlfg+X+WeAKjIYbrUh/vC5uyUhFFIuSQ8bmJcrTXCBmqCa6I3ILN/kNs// zbsoTYH4gLrXNSy4ACnHYeUiQOpFwqQekiezoryN+MD++I3tGyXafKNh7EUX8S56nila lb/Q== 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=Rtj3GXRMsqJ1e/8gKh7TIvLrlPRfDevEHsPtduD9sjc=; b=JuT9l+jlzJcAUUclvOklrcBHmtgMG8QG2sXLbSWZbT1Kuv9iNPFohdfTti0akchcR6 xiD4V/oUVYAUWMGOmZVAPnYm2cHlAjvs2SO5yifDXh9gfsod4eOTbkm4IfCWN82nRoB8 Dfni/1BfRRO9alUz9YCP6Vj+jd+Q1SAwN28VVlOQVfF+aqZGoRjmIERxj6wzl7xDUBoX JB3vtYVjhVORPMjE59UpXVW2Fsm3QxgA+XkhitL5A/IXb2/3cWZRAEtDFDqifG2gRmzr 1CjaZGcwrwyT8G8tov3Dh6816U1NQTmYyYWhePKsH3eWw3JsqgFVwZ18lKCpMLurSP5G iUsg== 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 q10si1676051pgd.335.2018.02.14.10.40.55; Wed, 14 Feb 2018 10:40:55 -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 S1162253AbeBNSkh (ORCPT + 28 others); Wed, 14 Feb 2018 13:40:37 -0500 Received: from ms.lwn.net ([45.79.88.28]:54702 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161773AbeBNSke (ORCPT ); Wed, 14 Feb 2018 13:40:34 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id D53C631D; Wed, 14 Feb 2018 18:40:33 +0000 (UTC) From: Jonathan Corbet To: linux-doc@vger.kernel.org Cc: linux-kernel@vger.kernel.org, mchehab@kernel.org, me@tobin.cc, jani.nikula@linux.intel.com, Jonathan Corbet Subject: [PATCH 7/8] docs: kernel-doc: Finish moving STATE_* code out of process_file() Date: Wed, 14 Feb 2018 11:40:08 -0700 Message-Id: <20180214184009.12657-8-corbet@lwn.net> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180214184009.12657-1-corbet@lwn.net> References: <20180214184009.12657-1-corbet@lwn.net> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Move STATE_INLINE and STATE_DOCBLOCK code out of process_file(), which now actually fits on a single screen. Delete an unused variable and add a couple of comments while I'm at it. Reviewed-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 139 +++++++++++++++++++++++++++++------------------------ 1 file changed, 77 insertions(+), 62 deletions(-) -- 2.14.3 diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 2deddb876156..fb8fbdb25036 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1990,10 +1990,80 @@ sub process_proto($$) { } } +# +# STATE_DOCBLOCK: within a DOC: block. +# +sub process_docblock($$) { + my $file = shift; + + if (/$doc_end/) { + dump_doc_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + $function = ""; + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = STATE_NORMAL; + } elsif (/$doc_content/) { + if ( $1 eq "" ) { + $contents .= $blankline; + } else { + $contents .= $1 . "\n"; + } + } +} + +# +# STATE_INLINE: docbook comments within a prototype. +# +sub process_inline($$) { + my $file = shift; + + # First line (state 1) needs to be a @parameter + if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { + $section = $1; + $contents = $2; + $new_start_line = $.; + if ($contents ne "") { + while (substr($contents, 0, 1) eq " ") { + $contents = substr($contents, 1); + } + $contents .= "\n"; + } + $inline_doc_state = STATE_INLINE_TEXT; + # Documentation block end */ + } elsif (/$doc_inline_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + $state = STATE_PROTO; + $inline_doc_state = STATE_INLINE_NA; + # Regular text + } elsif (/$doc_content/) { + if ($inline_doc_state == STATE_INLINE_TEXT) { + $contents .= $1 . "\n"; + # nuke leading blank lines + if ($contents =~ /^\s*$/) { + $contents = ""; + } + } elsif ($inline_doc_state == STATE_INLINE_NAME) { + $inline_doc_state = STATE_INLINE_ERROR; + print STDERR "${file}:$.: warning: "; + print STDERR "Incorrect use of kernel-doc format: $_"; + ++$warnings; + } + } +} + sub process_file($) { my $file; - my $func; my $initial_section_counter = $section_counter; my ($orig_file) = @_; @@ -2014,6 +2084,8 @@ sub process_file($) { } # Replace tabs by spaces while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; + + # Hand this line to the appropriate state handler if ($state == STATE_NORMAL) { process_normal(); } elsif ($state == STATE_NAME) { @@ -2021,72 +2093,15 @@ sub process_file($) { } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { 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) { - $section = $1; - $contents = $2; - $new_start_line = $.; - if ($contents ne "") { - while (substr($contents, 0, 1) eq " ") { - $contents = substr($contents, 1); - } - $contents .= "\n"; - } - $inline_doc_state = STATE_INLINE_TEXT; - # Documentation block end */ - } elsif (/$doc_inline_end/) { - if (($contents ne "") && ($contents ne "\n")) { - dump_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - } - $state = STATE_PROTO; - $inline_doc_state = STATE_INLINE_NA; - # Regular text - } elsif (/$doc_content/) { - if ($inline_doc_state == STATE_INLINE_TEXT) { - $contents .= $1 . "\n"; - # nuke leading blank lines - if ($contents =~ /^\s*$/) { - $contents = ""; - } - } elsif ($inline_doc_state == STATE_INLINE_NAME) { - $inline_doc_state = STATE_INLINE_ERROR; - print STDERR "${file}:$.: warning: "; - print STDERR "Incorrect use of kernel-doc format: $_"; - ++$warnings; - } - } + process_inline($file, $_); } elsif ($state == STATE_PROTO) { process_proto($file, $_); } elsif ($state == STATE_DOCBLOCK) { - if (/$doc_end/) - { - dump_doc_section($file, $section, $contents); - $section = $section_default; - $contents = ""; - $function = ""; - %parameterdescs = (); - %parametertypes = (); - @parameterlist = (); - %sections = (); - @sectionlist = (); - $prototype = ""; - $state = STATE_NORMAL; - } - elsif (/$doc_content/) - { - if ( $1 eq "" ) - { - $contents .= $blankline; - } - else - { - $contents .= $1 . "\n"; - } - } + process_docblock($file, $_); } } + + # Make sure we got something interesting. if ($initial_section_counter == $section_counter) { if ($output_mode ne "none") { print STDERR "${file}:1: warning: no structured comments found\n";