Don't complain about documented symbols with find-doc-nits -d -o

[openssl.git] / util / find-doc-nits

diff --git a/util/find-doc-nits b/util/find-doc-nits
index b9c72803a1c3c283a4c5e32af4acd45b421d6f65..901e34f384380e9a903f87f1c299015bdd4b1af1 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -144,6 +144,11 @@ sub name_synopsis {
         $line =~ s/STACK_OF\([^)]+\)/int/g;
         $line =~ s/SPARSE_ARRAY_OF\([^)]+\)/int/g;
         $line =~ s/__declspec\([^)]+\)//;
+        if ( $line =~ /typedef.*\(\*\S+\)\s+\(/ ) {
+            # a callback function with whitespace before the argument list:
+            # typedef ... (*NAME) (...
+            err($id, "function typedef has space before arg list: $line");
+        }
         if ( $line =~ /env (\S*)=/ ) {
             # environment variable env NAME=...
             $sym = $1;
@@ -592,7 +597,7 @@ sub loadmissing($)
     my @missing;
 
     open FH, $missingfile
-        || die "Can't open $missingfile";
+        or die "Can't open $missingfile";
     while ( <FH> ) {
         chomp;
         next if /^#/;
@@ -602,7 +607,7 @@ sub loadmissing($)
 
     for (@missing) {
         err("$missingfile:", "$_ is documented in $name_map{$_}")
-            if exists $name_map{$_} && defined $name_map{$_};
+            if !$opt_o && exists $name_map{$_} && defined $name_map{$_};
     }
 
     return @missing;
@@ -626,7 +631,8 @@ sub checkmacros {
         next if $f eq 'include/openssl/asn1.h';
         next if $f eq 'include/openssl/asn1t.h';
         next if $f eq 'include/openssl/err.h';
-        open(IN, $f) || die "Can't open $f, $!";
+        open(IN, $f)
+            or die "Can't open $f, $!";
         while ( <IN> ) {
             next unless /^#\s*define\s*(\S+)\(/;
             my $macro = "$1(3)"; # We know they're all in section 3
@@ -661,7 +667,7 @@ sub printem {
     my $count = 0;
     my %seen;
 
-    my @missing = loadmissing($missingfile) if ( $opt_v );
+    my @missing = loadmissing($missingfile) if $opt_v;
 
     foreach my $func ( parsenum($numfile) ) {
         $func .= '(3)';         # We know they're all in section 3
@@ -695,7 +701,7 @@ sub collectnames {
         err($id, "$simplename not in NAME section");
         push @{$podinfo{names}}, $simplename;
     }
-    foreach my $name (@{$podinfo{names}}) {
+    foreach my $name ( @{$podinfo{names}} ) {
         next if $name eq "";
         err($id, "'$name' contains white space")
             if $name =~ /\s/;
@@ -711,11 +717,10 @@ sub collectnames {
         }
     }
 
-    my @foreign_names =
-        map { map { s/\s+//g; $_ } split(/,/, $_) }
-        $podinfo{contents} =~ /=for\s+openssl\s+foreign\s+manuals:\s*(.*)\n\n/;
-    foreach ( @foreign_names ) {
-        $name_map{$_} = undef; # It still exists!
+    if ( $podinfo{contents} =~ /=for openssl foreign manual (.*)\n/ ) {
+        foreach my $f ( split / /, $1 ) {
+            $name_map{$f} = undef; # It still exists!
+        }
     }
 
     my @links =
@@ -733,8 +738,8 @@ sub collectnames {
 
 # Look for L<> ("link") references that point to files that do not exist.
 sub checklinks {
-    foreach my $filename (sort keys %link_map) {
-        foreach my $link (@{$link_map{$filename}}) {
+    foreach my $filename ( sort keys %link_map ) {
+        foreach my $link ( @{$link_map{$filename}} ) {
             err("${filename}:1:", "reference to non-existing $link")
                 unless exists $name_map{$link};
         }
@@ -783,7 +788,7 @@ sub checkflags {
 
     # Get the list of options in the command.
     open CFH, "./apps/openssl list --options $cmd|"
-        || die "Can list options for $cmd, $!";
+        or die "Can list options for $cmd, $!";
     while ( <CFH> ) {
         chop;
         s/ .$//;
@@ -793,7 +798,7 @@ sub checkflags {
 
     # Get the list of flags from the synopsis
     open CFH, "<$doc"
-        || die "Can't open $doc, $!";
+        or die "Can't open $doc, $!";
     while ( <CFH> ) {
         chop;
         last if /DESCRIPTION/;
@@ -803,8 +808,14 @@ sub checkflags {
             }
             next;
         }
-        next unless /\[B<-([^ >]+)/;
-        my $opt = $1;
+        my $opt;
+        if ( /\[B<-([^ >]+)/ ) {
+            $opt = $1;
+        } elsif ( /^B<-([^ >]+)/ ) {
+            $opt = $1;
+        } else {
+            next;
+        }
         $opt = $1 if $opt =~ /I<(.*)/;
         $docopts{$1} = 1;
     }
@@ -821,7 +832,7 @@ sub checkflags {
     my @unimpl = sort grep { !defined $cmdopts{$_} } keys %docopts;
     foreach ( @unimpl ) {
         next if defined $skips{$_} || defined $localskips{$_};
-        err("$cmd documented but not implemented -$_");
+        err("$doc: $cmd does not implement -$_");
     }
 }
 
@@ -837,7 +848,7 @@ if ( $opt_c ) {
 
     # Get list of commands.
     open FH, "./apps/openssl list -1 -commands|"
-        || die "Can't list commands, $!";
+        or die "Can't list commands, $!";
     while ( <FH> ) {
         chop;
         push @commands, $_;
@@ -847,8 +858,9 @@ if ( $opt_c ) {
     # See if each has a manpage.
     foreach my $cmd ( @commands ) {
         next if $cmd eq 'help' || $cmd eq 'exit';
-        my $doc = "doc/man1/$cmd.pod";
-        $doc = "doc/man1/openssl-$cmd.pod" if -f "doc/man1/openssl-$cmd.pod";
+        my $doc = "doc/man1/openssl-$cmd.pod";
+        # Handle "tsget" and "CA.pl" pod pages
+        $doc = "doc/man1/$cmd.pod" if -f "doc/man1/$cmd.pod";
         if ( ! -f "$doc" ) {
             err("$doc does not exist");
         } else {
@@ -858,7 +870,7 @@ if ( $opt_c ) {
 
     # See what help is missing.
     open FH, "./apps/openssl list --missing-help |"
-        || die "Can't list missing help, $!";
+        or die "Can't list missing help, $!";
     while ( <FH> ) {
         chop;
         my ($cmd, $flag) = split;
@@ -877,6 +889,9 @@ if ( $opt_l || $opt_u || $opt_v ) {
 }
 
 if ( $opt_l ) {
+    foreach my $func ( loadmissing("util/missingcrypto.txt") ) {
+        $name_map{$func} = undef;
+    }
     checklinks();
 }
 
@@ -888,7 +903,7 @@ if ( $opt_n ) {
 
     # If not given args, check that all man1 commands are named properly.
     if ( scalar @ARGV == 0 ) {
-        foreach (glob('doc/man1/*.pod')) {
+        foreach ( glob('doc/man1/*.pod') ) {
             next if /CA.pl/ || /openssl\.pod/ || /tsget\.pod/;
             err("$_ doesn't start with openssl-") unless /openssl-/;
         }