util/find-doc-nits: Fine tune detection of POD markup in NAME section

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

diff --git a/util/find-doc-nits b/util/find-doc-nits
index c041c1c81900bd493498a4faeeec204fa25c4b80..25f3d5e2c839b540278c04d6d3383471036e12de 100755 (executable)
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -1,7 +1,7 @@
 #! /usr/bin/env perl
-# Copyright 2002-2018 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 2002-2019 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
@@ -35,7 +35,7 @@ Find small errors (nits) in documentation.  Options:
     -l Print bogus links
     -n Print nits in POD pages
     -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
@@ -66,9 +66,9 @@ sub name_synopsis()
     $tmp =~ tr/\n/ /;
     print "$id trailing comma before - in NAME\n" if $tmp =~ /, *-/;
     $tmp =~ s/ -.*//g;
+    print "$id POD markup among the names in NAME\n" if $tmp =~ /[<>]/;
     $tmp =~ s/  */ /g;
     print "$id missing comma in NAME\n" if $tmp =~ /[^,] /;
-    $tmp =~ s/,//g;
 
     my $dirname = dirname($filename);
     my $simplename = basename($filename);
@@ -76,7 +76,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
@@ -99,6 +103,7 @@ sub name_synopsis()
         next unless $line =~ /^\s/;
         my $sym;
         $line =~ s/STACK_OF\([^)]+\)/int/g;
+        $line =~ s/SPARSE_ARRAY_OF\([^)]+\)/int/g;
         $line =~ s/__declspec\([^)]+\)//;
         if ( $line =~ /env (\S*)=/ ) {
             # environment variable env NAME=...
@@ -115,7 +120,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;
@@ -138,6 +143,20 @@ sub name_synopsis()
     }
 }
 
+# Check if SECTION is located before BEFORE
+sub check_section_location()
+{
+    my $filename = shift;
+    my $contents = shift;
+    my $section = shift;
+    my $before = shift;
+
+    return unless $contents =~ /=head1 $section/
+        and $contents =~ /=head1 $before/;
+    print "$filename: $section should be placed before $before section\n"
+        if $contents =~ /=head1 $before.*=head1 $section/ms;
+}
+
 sub check()
 {
     my $filename = shift;
@@ -151,6 +170,13 @@ sub check()
         close POD;
     }
 
+    # Check if EXAMPLES is located after RETURN VALUES section.
+    &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
+    # Check if HISTORY is located after SEE ALSO
+    &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|;
+    # Check if SEE ALSO is located after EXAMPLES
+    &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|;
+
     my $id = "${filename}:1:";
 
     &name_synopsis($id, $filename, $contents)
@@ -173,8 +199,6 @@ sub check()
         if $contents =~ /=head\d\s\s+/;
     print "$id period in NAME section\n"
         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"
@@ -247,7 +271,7 @@ sub parsenum()
     return sort @apis;
 }
 
-sub getdocced()
+sub getdocced
 {
     my $dir = shift;
     my %return;
@@ -270,6 +294,7 @@ my %docced;
 sub checkmacros()
 {
     my $count = 0;
+    my %seen;
 
     print "# Checking macros (approximate)\n";
     foreach my $f ( glob('include/openssl/*.h') ) {
@@ -281,7 +306,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/
@@ -289,6 +314,7 @@ sub checkmacros()
                 || $macro =~ /DECLARE_/;
             print "$f:$macro\n" if $opt_d;
             $count++;
+            $seen{$macro} = 1;
         }
         close(IN);
     }
@@ -300,15 +326,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";
 }
@@ -345,13 +373,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;
@@ -520,7 +551,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();
@@ -531,10 +563,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{$_};
     }