Add -p (public only) flag to find-doc-nits

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

diff --git a/util/find-doc-nits b/util/find-doc-nits
index 537e132cc39902fd112dbe37abdbfc6ee191668d..643fb9fd3ef58c62ed8e054c82e6bfd38bff8f26 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -24,6 +24,7 @@ our($opt_u);
 our($opt_h);
 our($opt_n);
 our($opt_l);
+our($opt_p);
 
 sub help()
 {
@@ -32,6 +33,7 @@ Find small errors (nits) in documentation.  Options:
     -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
     -h Print this help message
 EOF
@@ -40,6 +42,7 @@ EOF
 
 my $temp = '/tmp/docnits.txt';
 my $OUT;
+my %public;
 
 my %mandatory_sections =
     ( '*'    => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
@@ -59,7 +62,10 @@ sub name_synopsis()
     return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms;
     my $tmp = $1;
     $tmp =~ tr/\n/ /;
-    $tmp =~ s/-.*//g;
+    print "$id trailing comma before - in NAME\n" if $tmp =~ /, *-/;
+    $tmp =~ s/ -.*//g;
+    $tmp =~ s/  */ /g;
+    print "$id missing comma in NAME\n" if $tmp =~ /[^,] /;
     $tmp =~ s/,//g;
 
     my $dirname = dirname($filename);
@@ -77,8 +83,10 @@ sub name_synopsis()
     print "$id the following exist as other .pod files:\n",
         join(" ", sort keys %foundfilenames), "\n"
         if %foundfilenames;
-    print "$id $simplename (filename) missing from NAME section\n",
+    print "$id $simplename (filename) missing from NAME section\n"
         unless $foundfilename;
+    print "$id $simplename is not public\n"
+        if $opt_p and !defined $public{$simplename};
 
     # Find all functions in SYNOPSIS
     return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
@@ -96,7 +104,7 @@ sub name_synopsis()
         } elsif ( $line =~ /typedef.* (\S+);/ ) {
             # a simple typedef: typedef ... NAME;
             $sym = $1;
-        } elsif ( $line =~ /enum (\S*) {/ ) {
+        } elsif ( $line =~ /enum (\S*) \{/ ) {
             # an enumeration: enum ... {
             $sym = $1;
         } elsif ( $line =~ /#define ([A-Za-z0-9_]+)/ ) {
@@ -159,6 +167,10 @@ sub check()
         if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms;
     print "$id POD markup in NAME section\n"
         if $contents =~ /=head1 NAME.*[<>].*=head1 SYNOPSIS/ms;
+    print "$id Duplicate $1 in L<>\n"
+        if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2;
+    print "$id Bad =over $1\n"
+        if $contents =~ /=over([^ ][^24])/;
 
     # Look for multiple consecutive openssl #include lines.
     # Consecutive because of files like md5.pod. Sometimes it's okay
@@ -215,6 +227,7 @@ sub parsenum()
         or die "Can't open $file, $!, stopped";
 
     while ( <$IN> ) {
+        next if /^#/;
         next if /\bNOEXIST\b/;
         next if /\bEXPORT_VAR_AS_FUNC\b/;
         push @apis, $1 if /([^\s]+).\s/;
@@ -222,7 +235,7 @@ sub parsenum()
 
     close $IN;
 
-    print "# Found ", scalar(@apis), " in $file\n";
+    print "# Found ", scalar(@apis), " in $file\n" unless $opt_p;
     return sort @apis;
 }
 
@@ -339,14 +352,29 @@ sub checklinks {
     }
 }
 
-getopts('lnshu');
+sub publicize() {
+    foreach my $name ( &parsenum('util/libcrypto.num') ) {
+        $public{$name} = 1;
+    }
+    foreach my $name ( &parsenum('util/libssl.num') ) {
+        $public{$name} = 1;
+    }
+    foreach my $name ( &parsenum('util/private.num') ) {
+        $public{$name} = 1;
+    }
+}
+
+getopts('lnsphu');
+
+&help() if $opt_h;
 
-&help() if ( $opt_h );
+die "Need one of -l -n -s -p or -u flags.\n"
+    unless $opt_l or $opt_n or $opt_s or $opt_p or $opt_u;
 
-die "Need one of -l -n -s or -u flags.\n"
-    unless $opt_l or $opt_n or $opt_s or $opt_u;
+$opt_n = 1 if $opt_s or $opt_p;
 
-if ( $opt_n or $opt_s ) {
+if ( $opt_n ) {
+    &publicize() if $opt_p;
     foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
         &check($_);
     }