X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=util%2Ffind-doc-nits;h=860bb9958bd2d8b7d86e0b962009fa2e286d2923;hp=0b8308086433e403c2aae5785d4f7ae59003c084;hb=6738bf1417289a14758590fca5a26b62c9b2c0be;hpb=e90fc053c33a2241004451cfdeecfbf3cbdeb728

diff --git a/util/find-doc-nits b/util/find-doc-nits
index 0b83080864..860bb9958b 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,5 +1,5 @@
 #! /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
 # this file except in compliance with the License.  You can obtain a copy
@@ -19,23 +19,25 @@ use lib catdir(dirname($0), "perl");
 use OpenSSL::Util::Pod;
 
 # Options.
-our($opt_s);
-our($opt_u);
+our($opt_d);
 our($opt_h);
-our($opt_n);
 our($opt_l);
+our($opt_n);
 our($opt_p);
+our($opt_u);
+our($opt_c);
 
 sub help()
 {
     print <<EOF;
 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
     -h Print this help message
+    -c List undocumented commands and options
 EOF
     exit;
 }
@@ -101,7 +103,10 @@ sub name_synopsis()
             # environment variable env NAME=...
             $sym = $1;
         } elsif ( $line =~ /typedef.*\(\*(\S+)\)\(.*/ ) {
-            # a callback function: typedef ... (*NAME)(...
+            # a callback function pointer: typedef ... (*NAME)(...
+            $sym = $1;
+        } elsif ( $line =~ /typedef.* (\S+)\(.*/ ) {
+            # a callback function signature: typedef ... NAME(...
             $sym = $1;
         } elsif ( $line =~ /typedef.* (\S+);/ ) {
             # a simple typedef: typedef ... NAME;
@@ -210,7 +215,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;
     }
@@ -282,12 +286,12 @@ sub checkmacros()
                 || $macro =~ /DEPRECATEDIN/
                 || $macro =~ /IMPLEMENT_/
                 || $macro =~ /DECLARE_/;
-            print "$f:$macro\n";
+            print "$f:$macro\n" if $opt_d;
             $count++;
         }
         close(IN);
     }
-    print "# Found $count macros missing (not all should be documnted)\n"
+    print "# Found $count macros missing (not all should be documented)\n"
 }
 
 sub printem()
@@ -302,7 +306,7 @@ sub printem()
         # Skip ASN1 utilities
         next if $func =~ /^ASN1_/;
 
-        print "$libname:$func\n";
+        print "$libname:$func\n" if $opt_d;
         $count++;
     }
     print "# Found $count missing from $numfile\n\n";
@@ -367,7 +371,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;
@@ -395,20 +399,123 @@ sub publicize() {
     }
 }
 
-getopts('lnsphu');
+my %skips = (
+    'aes128' => 1,
+    'aes192' => 1,
+    'aes256' => 1,
+    'aria128' => 1,
+    'aria192' => 1,
+    'aria256' => 1,
+    'camellia128' => 1,
+    'camellia192' => 1,
+    'camellia256' => 1,
+    'des' => 1,
+    'des3' => 1,
+    'idea' => 1,
+    '[cipher]' => 1,
+    '[digest]' => 1,
+);
+
+sub checkflags() {
+    my $cmd = shift;
+    my %cmdopts;
+    my %docopts;
+    my $ok = 1;
+
+    # Get the list of options in the command.
+    open CFH, "./apps/openssl list --options $cmd|"
+        || die "Can list options for $cmd, $!";
+    while ( <CFH> ) {
+        chop;
+        s/ .$//;
+        $cmdopts{$_} = 1;
+    }
+    close CFH;
+
+    # Get the list of flags from the synopsis
+    open CFH, "<doc/man1/$cmd.pod"
+        || die "Can't open $cmd.pod, $!";
+    while ( <CFH> ) {
+        chop;
+        last if /DESCRIPTION/;
+        next unless /\[B<-([^ >]+)/;
+        $docopts{$1} = 1;
+    }
+    close CFH;
 
-&help() if $opt_h;
+    # See what's in the command not the manpage.
+    my @undocced = ();
+    foreach my $k ( keys %cmdopts ) {
+        push @undocced, $k unless $docopts{$k};
+    }
+    if ( scalar @undocced > 0 ) {
+        $ok = 0;
+        foreach ( @undocced ) {
+            print "doc/man1/$cmd.pod: Missing -$_\n";
+        }
+    }
 
-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;
+    # See what's in the command not the manpage.
+    my @unimpl = ();
+    foreach my $k ( keys %docopts ) {
+        push @unimpl, $k unless $cmdopts{$k};
+    }
+    if ( scalar @unimpl > 0 ) {
+        $ok = 0;
+        foreach ( @unimpl ) {
+            next if defined $skips{$_};
+            print "doc/man1/$cmd.pod: Not implemented -$_\n";
+        }
+    }
 
-$opt_n = 1 if $opt_s or $opt_p;
+    return $ok;
+}
 
-if ( $opt_n ) {
-    &publicize() if $opt_p;
-    foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
-        &check($_);
+getopts('cdlnphu');
+
+&help() if $opt_h;
+$opt_n = 1 if $opt_p;
+$opt_u = 1 if $opt_d;
+
+die "Need one of -[cdlnpu] flags.\n"
+    unless $opt_c or $opt_l or $opt_n or $opt_u;
+
+if ( $opt_c ) {
+    my $ok = 1;
+    my @commands = ();
+
+    # Get list of commands.
+    open FH, "./apps/openssl list -1 -commands|"
+        || die "Can't list commands, $!";
+    while ( <FH> ) {
+        chop;
+        push @commands, $_;
+    }
+    close FH;
+
+    # See if each has a manpage.
+    foreach ( @commands ) {
+        next if $_ eq 'help' || $_ eq 'exit';
+        if ( ! -f "doc/man1/$_.pod" ) {
+            print "doc/man1/$_.pod does not exist\n";
+            $ok = 0;
+        } else {
+            $ok = 0 if not &checkflags($_);
+        }
+    }
+
+    # See what help is missing.
+    open FH, "./apps/openssl list --missing-help |"
+        || die "Can't list missing help, $!";
+    while ( <FH> ) {
+        chop;
+        my ($cmd, $flag) = split;
+        print "$cmd has no help for -$flag\n";
+        $ok = 0;
     }
+    close FH;
+
+    exit 1 if not $ok;
 }
 
 if ( $opt_l ) {
@@ -418,6 +525,13 @@ if ( $opt_l ) {
     checklinks();
 }
 
+if ( $opt_n ) {
+    &publicize() if $opt_p;
+    foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
+        &check($_);
+    }
+}
+
 if ( $opt_u ) {
     my %temp = &getdocced('doc/man3');
     foreach ( keys %temp ) {