util/find-doc-nits: read full declarations as one line in name_synopsis()

name_synopsis was reading physical SYNOPSIS lines.  This changes it to
consider a declaration at a time, so we treat a C declaration that's
been broken up in several lines as one.

This makes it mandatory to end all C declarations in the SYNOPSIS with
a semicolon.  Those can be detected in two ways:

1.  Parsing an individual .pod file outputs this error:

    doc/man3/SOMETHING.pod:1: Can't parse rest of synopsis:

     int SOMETHING_status(SOMETHING *s)
     int SOMETHING_start(SOMETHING *s)

    (declarations not ending with a semicolon (;)?)

2.  Errors like this:

    doc/man3/SOMETHING.pod:1: SOMETHING_status missing from SYNOPSIS
    doc/man3/SOMETHING.pod:1: SOMETHING_start missing from SYNOPSIS

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/12452)

diff --git a/util/find-doc-nits b/util/find-doc-nits
index d2317459ec04f1f1076e06c8f2fd7b2d2849177d..bcae76e4834c1578de645c16993c6a6bf122630e 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -311,8 +311,22 @@ sub name_synopsis {
     # Find all functions in SYNOPSIS
     return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
     my $syn = $1;
-    foreach my $line ( split /\n+/, $syn ) {
-        next unless $line =~ /^\s/;
+    # Remove all non-code lines
+    $syn =~ s/^(?:\s*?|\S.*?)$//msg;
+    # Remove all comments
+    $syn =~ s/\/\*.*?\*\///msg;
+    while ( $syn ) {
+        # "env" lines end at a newline.
+        # Preprocessor lines start with a # and end at a newline.
+        # Other lines end with a semicolon, and may cover more than
+        # one physical line.
+        if ( $syn !~ /^ \s*(env .*?|#.*?|.*?;)\s*$/ms ) {
+            err($id, "Can't parse rest of synopsis:\n$syn\n(declarations not ending with a semicolon (;)?)");
+            last;
+        }
+        my $line = $1;
+        $syn = $';
+
         my $sym;
         my $is_prototype = 1;
         $line =~ s/STACK_OF\([^)]+\)/int/g;