From patchwork Wed Feb 14 18:40:05 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 128382 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp912759ljc; Wed, 14 Feb 2018 10:42:06 -0800 (PST) X-Google-Smtp-Source: AH8x225tn3KSCMC60KLVvAYViMHJT3pV1KFlOHkVMb4hiWnaM9SluCQfztjp+/axNVj2NHgwGcE7 X-Received: by 10.101.67.2 with SMTP id j2mr116274pgq.159.1518633725964; Wed, 14 Feb 2018 10:42:05 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518633725; cv=none; d=google.com; s=arc-20160816; b=ApebV5oTtl4sNfY/XvKfMyA2dgD8ik6SnX8ZblqLCMWlOd1hC06Uqy7U3DaRPhlyPz rq7zefZ6WQvCx60UiWivKnQ6zeX/pI3IjWeqd9wQXdmz4SSyylRjEq75As+tEIgCD8Kp 328f6pl5VRHOcpJXT2sTy8zKylr9U69HqokAM+5X8CYa+AOU0HVGI3JmZB1IDiKWqKUy aL10arqDKESMmRIcBDY2VjA50aCtfJsuZB5zJTUzy3W/dnYxxs3IpHHRKnlnpJyXkWDW M4O4zOuN9EuNa8j/e10XtvO/BkoHWW2PjV/XpuhYhimvDExIyPLaENwSEjxsQt2JxICz zeTg== 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=C+5Pl7ULW4GfCVD97MrzclLRpcCUgMkpboSNGezpfZ8=; b=crS0YpM9S3g2dv7eiQ3EIuOwdQsaVniNPlqP2zff8xsJQpKw6PfIgMwpnUi6IOb1M1 m5dCPCMC9nTzNdi1nLmO5vLjFQzyPzPZ5KE4fBOLEhfp4L73TQnP+EdYbIVrOLlgjPY0 r0cNrC3gWIIeV0iYe7ILAY1fnU0RYGAT8VaQdhIQPHPoSPvU0o3Wkmk9dm5rRInyVyPY bKU21vUyDyGlaBDmza3lOM7oe7EtnUUUvkbpaKDHJJwKnm736BupoC/fG+O1qSD85JBT QY4QWTCXL+hvosIWHPK61v7OoTpd5kg/JQppofmvCG7YzT9WrYRyjiY1x+jGITH0yK7A q/dw== 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 z12si2900233pgp.788.2018.02.14.10.42.05; Wed, 14 Feb 2018 10:42:05 -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 S1162310AbeBNSmC (ORCPT + 28 others); Wed, 14 Feb 2018 13:42:02 -0500 Received: from ms.lwn.net ([45.79.88.28]:54672 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1162215AbeBNSkc (ORCPT ); Wed, 14 Feb 2018 13:40:32 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 52894537; Wed, 14 Feb 2018 18:40:31 +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 4/8] docs: kernel-doc: Move STATE_NAME processing into its own function Date: Wed, 14 Feb 2018 11:40:05 -0700 Message-Id: <20180214184009.12657-5-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 this code out of process_file() in the name of readability and maintainability. Reviewed-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 137 ++++++++++++++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 65 deletions(-) -- 2.14.3 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;