From patchwork Wed Feb 7 17:26:20 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 127200 Delivered-To: patch@linaro.org Received: by 10.46.124.24 with SMTP id x24csp684204ljc; Wed, 7 Feb 2018 09:28:27 -0800 (PST) X-Google-Smtp-Source: AH8x226/6cYPrSJh/F+quPIMhOtcCEpEVh+pTWRq5tKAMIQzu49Oh0kDxc9wKJBgwjATUt37QS0B X-Received: by 2002:a17:902:67c5:: with SMTP id g5-v6mr6777173pln.106.1518024507768; Wed, 07 Feb 2018 09:28:27 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1518024507; cv=none; d=google.com; s=arc-20160816; b=rpEEG7w8xijp3YX4gLq6b63KXtvcCXCytNQq3AW/z9K/cUH3U7PjshBePmAJt2RWnw BL9s0NYvdL2VvtUGgGpiLG4/1NI7onkyDvmSw7NMYA05oOCPRAqugLrf2+N2HpMDWNW0 R5ZBYJNG+T1J3PvGoo9BT5dtc+fJrEAIJtEwJzC5Cf1XJYQugXinB35SlUfMRy9kTA7z jHgaloRg89HsmXhuJuhBYP/Jq9Zv+ZC5pipX3ZHug5vkfWvo2p3pdgl8rNMZ5PYk9tN4 k52j8t+p78jDNZjZ4Elm8RJJKppnrVYdP/tVhM5XaqGXoV4Byv6RDTuBgYhmmSd6Kld5 L6bw== 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=L34GV5JNoZqB6XE7wzdYnkPES/GYGbZ+z1VlkAdUvtY=; b=TJ72opJncaO/ozVCLGeEftr9AS5+4EEQyuP/FADLAECR0CSf3rsdqZYF2zWTQfIjCG QGB8bqoxNxCMWB8c6Kk7nYnrRr6Nm6AgNdWjc07tv5nr4dHDxT5ykZEsbqlxkCFJcp22 HDEu8m3S/ExZjZa9Hww0qHAqnWMPxY8cbJ6bXAdkdigeX61m6cWUiv9AH/ltZ8XJ/Uo8 GuhzvMvDjKAJzxn21KfByyYA0sO49x3E6Q6i9q5HvnuH74GyHu/R6+T7CrabewqHdrwk RmCNhfISzjGWsO9KzAvl6b9wjpv9dYVQYJMLCNhvWuh3QXCSqqt34TciLZdNYsuLdWGV V5Aw== 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 x8-v6si1366659plo.616.2018.02.07.09.28.27; Wed, 07 Feb 2018 09:28:27 -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 S1754946AbeBGR20 (ORCPT + 18 others); Wed, 7 Feb 2018 12:28:26 -0500 Received: from ms.lwn.net ([45.79.88.28]:41640 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754833AbeBGR1D (ORCPT ); Wed, 7 Feb 2018 12:27:03 -0500 Received: from tpad.lan (localhost [127.0.0.1]) by ms.lwn.net (Postfix) with ESMTPA id 30781141B; Wed, 7 Feb 2018 17:27:02 +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 4/8] docs: kernel-doc: Move STATE_NAME processing into its own function Date: Wed, 7 Feb 2018 10:26:20 -0700 Message-Id: <20180207172624.24555-5-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 Move this code out of process_file() in the name of readability and maintainability. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 137 ++++++++++++++++++++++++++++------------------------- 1 file changed, 72 insertions(+), 65 deletions(-) -- 2.14.3 Reviewed-by: Jani Nikula 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;