linux-kernel - [PATCH 2/8] docs: kernel-doc: Rename and split STATE

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20180214184009.12657-3-corbet@lwn.net>
Date:   Wed, 14 Feb 2018 11:40:03 -0700
From:   Jonathan Corbet <corbet@....net>
To:     linux-doc@...r.kernel.org
Cc:     linux-kernel@...r.kernel.org, mchehab@...nel.org, me@...in.cc,
        jani.nikula@...ux.intel.com, Jonathan Corbet <corbet@....net>
Subject: [PATCH 2/8] docs: kernel-doc: Rename and split STATE_FIELD

STATE_FIELD describes a parser state that can handle any part of a
kerneldoc comment body; rename it to STATE_BODY to reflect that.

The $in_purpose variable was a hidden substate of STATE_FIELD; get rid of
it and make a proper state (STATE_BODY_MAYBE) instead.  This will make the
subsequent process_file() splitup easier.

Reviewed-by: Jani Nikula <jani.nikula@...el.com>
Signed-off-by: Jonathan Corbet <corbet@....net>
---
 scripts/kernel-doc | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 5aa4ce211fc6..ad30c52f91ef 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -328,10 +328,11 @@ my $lineprefix="";
 use constant {
     STATE_NORMAL        => 0, # normal code
     STATE_NAME          => 1, # looking for function name
-    STATE_FIELD         => 2, # scanning field start
-    STATE_PROTO         => 3, # scanning prototype
-    STATE_DOCBLOCK      => 4, # documentation block
-    STATE_INLINE        => 5, # gathering documentation outside main block
+    STATE_BODY_MAYBE    => 2, # body - or maybe more description
+    STATE_BODY          => 3, # the body of the comment
+    STATE_PROTO         => 4, # scanning prototype
+    STATE_DOCBLOCK      => 5, # documentation block
+    STATE_INLINE        => 6, # gathering documentation outside main block
 };
 my $state;
 my $in_doc_sect;
@@ -1784,7 +1785,6 @@ sub process_file($) {
     my $identifier;
     my $func;
     my $descr;
-    my $in_purpose = 0;
     my $initial_section_counter = $section_counter;
     my ($orig_file) = @_;
     my $leading_space;
@@ -1830,7 +1830,7 @@ sub process_file($) {
 		    $identifier = $1;
 		}
 
-		$state = STATE_FIELD;
+		$state = STATE_BODY;
 		# if there's no @param blocks need to set up default section
 		# here
 		$contents = "";
@@ -1843,7 +1843,7 @@ sub process_file($) {
 		    $descr =~ s/\s*$//;
 		    $descr =~ s/\s+/ /g;
 		    $declaration_purpose = $descr;
-		    $in_purpose = 1;
+		    $state = STATE_BODY_MAYBE;
 		} else {
 		    $declaration_purpose = "";
 		}
@@ -1875,7 +1875,7 @@ sub process_file($) {
 		++$warnings;
 		$state = STATE_NORMAL;
 	    }
-	} elsif ($state == STATE_FIELD) {	# look for head: lines, and include content
+	} elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
 	    if (/$doc_sect/i) { # case insensitive for supported section names
 		$newsection = $1;
 		$newcontents = $2;
@@ -1902,7 +1902,7 @@ sub process_file($) {
 		}
 
 		$in_doc_sect = 1;
-		$in_purpose = 0;
+		$state = STATE_BODY;
 		$contents = $newcontents;
                 $new_start_line = $.;
 		while (substr($contents, 0, 1) eq " ") {
@@ -1941,8 +1941,8 @@ sub process_file($) {
 		    } else {
 			$contents .= "\n";
 		    }
-		    $in_purpose = 0;
-		} elsif ($in_purpose == 1) {
+		    $state = STATE_BODY;
+		} elsif ($state == STATE_BODY_MAYBE) {
 		    # Continued declaration purpose
 		    chomp($declaration_purpose);
 		    $declaration_purpose .= " " . $1;
-- 
2.14.3