util/find-doc-nits: Relax check of function declarations in name_synopsis()

The relaxation allows spaces between function name and argument list,
to allow line breaks like this when there are very long names:

    int (fantastically_long_name_breaks_80char_limit)
        (fantastically_long_name_breaks_80char_limit *something);

This revealed some other intricaties, such as documented internal
structures with function pointers inside, so a check of open
structures was also added, and they are now simply skipped over.

Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/12494)

diff --git a/util/find-doc-nits b/util/find-doc-nits
index c82e647bf5e781ef38bb4ea233ae2d3304ddc5b3..3558180603251195f60a4bb7b6311a5f52a792ca 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -311,6 +311,7 @@ sub name_synopsis {
     # Find all functions in SYNOPSIS
     return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
     my $syn = $1;
+    my $ignore_until = undef;   # If defined, this is a regexp
     # Remove all non-code lines
     $syn =~ s/^(?:\s*?|\S.*?)$//msg;
     # Remove all comments
@@ -327,6 +328,19 @@ sub name_synopsis {
         my $line = $1;
         $syn = $';
 
+        print STDERR "DEBUG[name_synopsis] \$line = '$line'\n" if $debug;
+
+        # Special code to skip over documented structures
+        if ( defined $ignore_until) {
+            next if $line !~ /$ignore_until/;
+            $ignore_until = undef;
+            next;
+        }
+        if ( $line =~ /^\s*(?:typedef\s+)?struct(?:\s+\S+)\s*\{/ ) {
+            $ignore_until = qr/\}.*?;/;
+            next;
+        }
+
         my $sym;
         my $is_prototype = 1;
         $line =~ s/STACK_OF\([^)]+\)/int/g;
@@ -353,7 +367,7 @@ sub name_synopsis {
             # a callback function pointer: typedef ... (*NAME)(...
             # a callback function signature: typedef ... (NAME)(...
             $sym = $1;
-        } elsif ( $line =~ /typedef.* (\S+)\(/ ) {
+        } elsif ( $line =~ /typedef.* (\S+)\s*\(/ ) {
             # a callback function signature: typedef ... NAME(...
             $sym = $1;
         } elsif ( $line =~ /typedef.* (\S+);/ ) {
@@ -366,12 +380,19 @@ sub name_synopsis {
         } elsif ( $line =~ /#\s*(?:define|undef) ([A-Za-z0-9_]+)/ ) {
             $is_prototype = 0;
             $sym = $1;
-        } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) {
+        } elsif ( $line =~ /^[^\(]*?\(\*([A-Za-z0-9_]+)\s*\(/ ) {
+            # a function returning a function pointer: TYPE (*NAME(args))(args)
+            $sym = $1;
+        } elsif ( $line =~ /^[^\(]*?([A-Za-z0-9_]+)\s*\(/ ) {
+            # a simple function declaration
             $sym = $1;
         }
         else {
             next;
         }
+
+        print STDERR "DEBUG[name_synopsis] \$sym = '$sym'\n" if $debug;
+
         err($id, "$sym missing from NAME section")
             unless defined $names{$sym};
         $names{$sym} = 2;