util/find-docs-nits: Extend to handle internal documentation

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

diff --git a/util/find-doc-nits b/util/find-doc-nits
index aaf3eeb4f0d9a91ef180adb3bb7dd16dda608c5d..8001468f1d55b2cd908aa9502dab09d0c74d9e01 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,7 +1,7 @@
 #! /usr/bin/env perl
-# Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
 #
-# Licensed under the OpenSSL license (the "License").  You may not use
+# Licensed under the Apache License 2.0 (the "License").  You may not use
 # this file except in compliance with the License.  You can obtain a copy
 # in the file LICENSE in the source distribution or at
 # https://www.openssl.org/source/license.html
@@ -24,7 +24,6 @@ our($opt_h);
 our($opt_l);
 our($opt_n);
 our($opt_p);
-our($opt_s);
 our($opt_u);
 our($opt_c);
 
@@ -35,9 +34,8 @@ Find small errors (nits) in documentation.  Options:
     -d Detailed list of undocumented (implies -u)
     -l Print bogus links
     -n Print nits in POD pages
-    -s Also print missing sections in POD pages (implies -n)
     -p Warn if non-public name documented (implies -n)
-    -u List undocumented functions
+    -u Count undocumented functions
     -h Print this help message
     -c List undocumented commands and options
 EOF
@@ -70,7 +68,6 @@ sub name_synopsis()
     $tmp =~ s/ -.*//g;
     $tmp =~ s/  */ /g;
     print "$id missing comma in NAME\n" if $tmp =~ /[^,] /;
-    $tmp =~ s/,//g;
 
     my $dirname = dirname($filename);
     my $simplename = basename($filename);
@@ -78,7 +75,11 @@ sub name_synopsis()
     my $foundfilename = 0;
     my %foundfilenames = ();
     my %names;
-    foreach my $n ( split ' ', $tmp ) {
+    foreach my $n ( split ',', $tmp ) {
+        $n =~ s/^\s+//;
+        $n =~ s/\s+$//;
+        print "$id the name '$n' contains white-space\n"
+            if $n =~ /\s/;
         $names{$n} = 1;
         $foundfilename++ if $n eq $simplename;
         $foundfilenames{$n} = 1
@@ -98,6 +99,7 @@ sub name_synopsis()
     return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
     my $syn = $1;
     foreach my $line ( split /\n+/, $syn ) {
+        next unless $line =~ /^\s/;
         my $sym;
         $line =~ s/STACK_OF\([^)]+\)/int/g;
         $line =~ s/__declspec\([^)]+\)//;
@@ -116,7 +118,7 @@ sub name_synopsis()
         } elsif ( $line =~ /enum (\S*) \{/ ) {
             # an enumeration: enum ... {
             $sym = $1;
-        } elsif ( $line =~ /#define ([A-Za-z0-9_]+)/ ) {
+        } elsif ( $line =~ /#(?:define|undef) ([A-Za-z0-9_]+)/ ) {
             $sym = $1;
         } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) {
             $sym = $1;
@@ -217,7 +219,6 @@ sub check()
 
     foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
         # Skip "return values" if not -s
-        next if $_ eq 'RETURN VALUES' and not $opt_s;
         print "$id: missing $_ head1 section\n"
             if $contents !~ /^=head1\s+${_}\s*$/m;
     }
@@ -249,7 +250,7 @@ sub parsenum()
     return sort @apis;
 }
 
-sub getdocced()
+sub getdocced
 {
     my $dir = shift;
     my %return;
@@ -272,6 +273,7 @@ my %docced;
 sub checkmacros()
 {
     my $count = 0;
+    my %seen;
 
     print "# Checking macros (approximate)\n";
     foreach my $f ( glob('include/openssl/*.h') ) {
@@ -283,7 +285,7 @@ sub checkmacros()
         while ( <IN> ) {
             next unless /^#\s*define\s*(\S+)\(/;
             my $macro = $1;
-            next if $docced{$macro};
+            next if $docced{$macro} || defined $seen{$macro};
             next if $macro =~ /i2d_/
                 || $macro =~ /d2i_/
                 || $macro =~ /DEPRECATEDIN/
@@ -291,6 +293,7 @@ sub checkmacros()
                 || $macro =~ /DECLARE_/;
             print "$f:$macro\n" if $opt_d;
             $count++;
+            $seen{$macro} = 1;
         }
         close(IN);
     }
@@ -302,15 +305,17 @@ sub printem()
     my $libname = shift;
     my $numfile = shift;
     my $count = 0;
+    my %seen;
 
     foreach my $func ( &parsenum($numfile) ) {
-        next if $docced{$func};
+        next if $docced{$func} || defined $seen{$func};
 
         # Skip ASN1 utilities
         next if $func =~ /^ASN1_/;
 
         print "$libname:$func\n" if $opt_d;
         $count++;
+        $seen{$func} = 1;
     }
     print "# Found $count missing from $numfile\n\n";
 }
@@ -347,13 +352,16 @@ sub collectnames {
     $tmp =~ tr/\n/ /;
     $tmp =~ s/-.*//g;
 
-    my @names = map { s/\s+//g; $_ } split(/,/, $tmp);
+    my @names = map { s/^\s+//g; s/\s+$//g; $_ } split(/,/, $tmp);
     unless (grep { $simplename eq $_ } @names) {
         print "$id missing $simplename\n";
         push @names, $simplename;
     }
     foreach my $name (@names) {
         next if $name eq "";
+        if ($name =~ /\s/) {
+            print "$id '$name' contains white space\n";
+        }
         my $name_sec = "$name($section)";
         if (! exists $name_collection{$name_sec}) {
             $name_collection{$name_sec} = $filename;
@@ -374,7 +382,7 @@ sub collectnames {
                               # then remove 'something'.  Note that 'something'
                               # may contain POD codes as well...
                               (?:(?:[^\|]|<[^>]*>)*\|)?
-                              # we're only interested in referenses that have
+                              # we're only interested in references that have
                               # a one digit section number
                               ([^\/>\(]+\(\d\))
                              /gx;
@@ -474,13 +482,13 @@ sub checkflags() {
     return $ok;
 }
 
-getopts('cdlnsphu');
+getopts('cdlnphu');
 
 &help() if $opt_h;
-$opt_n = 1 if $opt_s or $opt_p;
+$opt_n = 1 if $opt_p;
 $opt_u = 1 if $opt_d;
 
-die "Need one of -[cdlnspu] flags.\n"
+die "Need one of -[cdlnpu] flags.\n"
     unless $opt_c or $opt_l or $opt_n or $opt_u;
 
 if ( $opt_c ) {
@@ -522,7 +530,8 @@ if ( $opt_c ) {
 }
 
 if ( $opt_l ) {
-    foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
+    foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'),
+                              glob('doc/internal/*/*.pod'))) {
         collectnames($_);
     }
     checklinks();
@@ -533,10 +542,16 @@ if ( $opt_n ) {
     foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
         &check($_);
     }
+    {
+        local $opt_p = undef;
+        foreach (@ARGV ? @ARGV : glob('doc/internal/*/*.pod')) {
+            &check($_);
+        }
+    }
 }
 
 if ( $opt_u ) {
-    my %temp = &getdocced('doc/man3');
+    my %temp = getdocced('doc/man3');
     foreach ( keys %temp ) {
         $docced{$_} = $temp{$_};
     }