51dcd286d5d84f6b73eda638b9a35860843fe8e4
[openssl.git] / util / find-doc-nits
1 #! /usr/bin/env perl
2 # Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
3 #
4 # Licensed under the Apache License 2.0 (the "License").  You may not use
5 # this file except in compliance with the License.  You can obtain a copy
6 # in the file LICENSE in the source distribution or at
7 # https://www.openssl.org/source/license.html
8
9
10 require 5.10.0;
11 use warnings;
12 use strict;
13 use Pod::Checker;
14 use File::Find;
15 use File::Basename;
16 use File::Spec::Functions;
17 use Getopt::Std;
18 use lib catdir(dirname($0), "perl");
19 use OpenSSL::Util::Pod;
20
21 # Options.
22 our($opt_d);
23 our($opt_e);
24 our($opt_s);
25 our($opt_h);
26 our($opt_l);
27 our($opt_n);
28 our($opt_p);
29 our($opt_u);
30 our($opt_v);
31 our($opt_c);
32
33 sub help()
34 {
35     print <<EOF;
36 Find small errors (nits) in documentation.  Options:
37     -d Detailed list of undocumented (implies -u)
38     -e Detailed list of new undocumented (implies -v)
39     -s Same as -e except no output is generated if nothing is undocumented
40     -l Print bogus links
41     -n Print nits in POD pages
42     -p Warn if non-public name documented (implies -n)
43     -u Count undocumented functions
44     -v Count new undocumented functions
45     -h Print this help message
46     -c List undocumented commands and options
47 EOF
48     exit;
49 }
50
51 my $temp = '/tmp/docnits.txt';
52 my $OUT;
53 my %public;
54
55 my %mandatory_sections =
56     ( '*'    => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
57       1      => [ 'SYNOPSIS', 'OPTIONS' ],
58       3      => [ 'SYNOPSIS', 'RETURN VALUES' ],
59       5      => [ ],
60       7      => [ ] );
61
62 # Cross-check functions in the NAME and SYNOPSIS section.
63 sub name_synopsis()
64 {
65     my $id = shift;
66     my $filename = shift;
67     my $contents = shift;
68
69     # Get NAME section and all words in it.
70     return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms;
71     my $tmp = $1;
72     $tmp =~ tr/\n/ /;
73     print "$id trailing comma before - in NAME\n" if $tmp =~ /, *-/;
74     $tmp =~ s/ -.*//g;
75     print "$id POD markup among the names in NAME\n" if $tmp =~ /[<>]/;
76     $tmp =~ s/  */ /g;
77     print "$id missing comma in NAME\n" if $tmp =~ /[^,] /;
78
79     my $dirname = dirname($filename);
80     my $simplename = basename($filename);
81     $simplename =~ s/.pod$//;
82     my $foundfilename = 0;
83     my %foundfilenames = ();
84     my %names;
85     foreach my $n ( split ',', $tmp ) {
86         $n =~ s/^\s+//;
87         $n =~ s/\s+$//;
88         print "$id the name '$n' contains white-space\n"
89             if $n =~ /\s/;
90         $names{$n} = 1;
91         $foundfilename++ if $n eq $simplename;
92         $foundfilenames{$n} = 1
93             if -f "$dirname/$n.pod" && $n ne $simplename;
94     }
95     print "$id the following exist as other .pod files:\n",
96         join(" ", sort keys %foundfilenames), "\n"
97         if %foundfilenames;
98     print "$id $simplename (filename) missing from NAME section\n"
99         unless $foundfilename;
100     foreach my $n ( keys %names ) {
101         print "$id $n is not public\n"
102             if $opt_p and !defined $public{$n};
103     }
104
105     # Find all functions in SYNOPSIS
106     return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
107     my $syn = $1;
108     foreach my $line ( split /\n+/, $syn ) {
109         next unless $line =~ /^\s/;
110         my $sym;
111         $line =~ s/STACK_OF\([^)]+\)/int/g;
112         $line =~ s/SPARSE_ARRAY_OF\([^)]+\)/int/g;
113         $line =~ s/__declspec\([^)]+\)//;
114         if ( $line =~ /env (\S*)=/ ) {
115             # environment variable env NAME=...
116             $sym = $1;
117         } elsif ( $line =~ /typedef.*\(\*(\S+)\)\(.*/ ) {
118             # a callback function pointer: typedef ... (*NAME)(...
119             $sym = $1;
120         } elsif ( $line =~ /typedef.* (\S+)\(.*/ ) {
121             # a callback function signature: typedef ... NAME(...
122             $sym = $1;
123         } elsif ( $line =~ /typedef.* (\S+);/ ) {
124             # a simple typedef: typedef ... NAME;
125             $sym = $1;
126         } elsif ( $line =~ /enum (\S*) \{/ ) {
127             # an enumeration: enum ... {
128             $sym = $1;
129         } elsif ( $line =~ /#(?:define|undef) ([A-Za-z0-9_]+)/ ) {
130             $sym = $1;
131         } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) {
132             $sym = $1;
133         }
134         else {
135             next;
136         }
137         print "$id $sym missing from NAME section\n"
138             unless defined $names{$sym};
139         $names{$sym} = 2;
140
141         # Do some sanity checks on the prototype.
142         print "$id prototype missing spaces around commas: $line\n"
143             if ( $line =~ /[a-z0-9],[^ ]/ );
144     }
145
146     foreach my $n ( keys %names ) {
147         next if $names{$n} == 2;
148         print "$id $n missing from SYNOPSIS\n";
149     }
150 }
151
152 # Check if SECTION is located before BEFORE
153 sub check_section_location()
154 {
155     my $filename = shift;
156     my $contents = shift;
157     my $section = shift;
158     my $before = shift;
159
160     return unless $contents =~ /=head1 $section/
161         and $contents =~ /=head1 $before/;
162     print "$filename: $section should be placed before $before section\n"
163         if $contents =~ /=head1 $before.*=head1 $section/ms;
164 }
165
166 sub check()
167 {
168     my $filename = shift;
169     my $dirname = basename(dirname($filename));
170
171     my $contents = '';
172     {
173         local $/ = undef;
174         open POD, $filename or die "Couldn't open $filename, $!";
175         $contents = <POD>;
176         close POD;
177     }
178
179     # Check if EXAMPLES is located after RETURN VALUES section.
180     &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
181     # Check if HISTORY is located after SEE ALSO
182     &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|;
183     # Check if SEE ALSO is located after EXAMPLES
184     &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|;
185
186     my $id = "${filename}:1:";
187
188     &name_synopsis($id, $filename, $contents)
189         unless $contents =~ /=for comment generic/
190             or $filename =~ m@man[157]/@;
191
192     print "$id doesn't start with =pod\n"
193         if $contents !~ /^=pod/;
194     print "$id doesn't end with =cut\n"
195         if $contents !~ /=cut\n$/;
196     print "$id more than one cut line.\n"
197         if $contents =~ /=cut.*=cut/ms;
198     print "$id missing copyright\n"
199         if $contents !~ /Copyright .* The OpenSSL Project Authors/;
200     print "$id copyright not last\n"
201         if $contents =~ /head1 COPYRIGHT.*=head/ms;
202     print "$id head2 in All uppercase\n"
203         if $contents =~ /head2\s+[A-Z ]+\n/;
204     print "$id extra space after head\n"
205         if $contents =~ /=head\d\s\s+/;
206     print "$id period in NAME section\n"
207         if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms;
208     print "$id Duplicate $1 in L<>\n"
209         if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2;
210     print "$id Bad =over $1\n"
211         if $contents =~ /=over([^ ][^24])/;
212     print "$id Possible version style issue\n"
213         if $contents =~ /OpenSSL version [019]/;
214
215     if ( $contents !~ /=for comment multiple includes/ ) {
216         # Look for multiple consecutive openssl #include lines
217         # (non-consecutive lines are okay; see man3/MD5.pod).
218         if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
219             my $count = 0;
220             foreach my $line ( split /\n+/, $1 ) {
221                 if ( $line =~ m@include <openssl/@ ) {
222                     print "$id has multiple includes\n" if ++$count == 2;
223                 } else {
224                     $count = 0;
225                 }
226             }
227         }
228     }
229
230     open my $OUT, '>', $temp
231         or die "Can't open $temp, $!";
232     podchecker($filename, $OUT);
233     close $OUT;
234     open $OUT, '<', $temp
235         or die "Can't read $temp, $!";
236     while ( <$OUT> ) {
237         next if /\(section\) in.*deprecated/;
238         print;
239     }
240     close $OUT;
241     unlink $temp || warn "Can't remove $temp, $!";
242
243     # Find what section this page is in; assume 3.
244     my $section = 3;
245     $section = $1 if $dirname =~ /man([1-9])/;
246
247     foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) {
248         # Skip "return values" if not -s
249         print "$id: missing $_ head1 section\n"
250             if $contents !~ /^=head1\s+${_}\s*$/m;
251     }
252 }
253
254 my %dups;
255
256 sub parsenum()
257 {
258     my $file = shift;
259     my @apis;
260
261     open my $IN, '<', $file
262         or die "Can't open $file, $!, stopped";
263
264     while ( <$IN> ) {
265         next if /^#/;
266         next if /\bNOEXIST\b/;
267         next if /\bEXPORT_VAR_AS_FUNC\b/;
268         my @fields = split();
269         die "Malformed line $_"
270             if scalar @fields != 2 && scalar @fields != 4;
271         push @apis, $fields[0];
272     }
273
274     close $IN;
275
276     print "# Found ", scalar(@apis), " in $file\n" unless $opt_p;
277     return sort @apis;
278 }
279
280 sub getdocced
281 {
282     my $dir = shift;
283     my %return;
284
285     foreach my $pod ( glob("$dir/*.pod") ) {
286         my %podinfo = extract_pod_info($pod);
287         foreach my $n ( @{$podinfo{names}} ) {
288             $return{$n} = $pod;
289             print "# Duplicate $n in $pod and $dups{$n}\n"
290                 if defined $dups{$n} && $dups{$n} ne $pod;
291             $dups{$n} = $pod;
292         }
293     }
294
295     return %return;
296 }
297
298 my %docced;
299
300 sub loadmissing($)
301 {
302     my $missingfile = shift;
303     my @missing;
304
305     open FH, $missingfile
306         || die "Can't open $missingfile";
307     while ( <FH> ) {
308         chomp;
309         next if /^#/;
310         push @missing, $_;
311     }
312     close FH;
313
314     return @missing;
315 }
316
317 sub checkmacros()
318 {
319     my $count = 0;
320     my %seen;
321
322     my @missing = loadmissing('util/missingmacro.txt') if ($opt_v);
323
324     print "# Checking macros (approximate)\n" if !$opt_s;
325     foreach my $f ( glob('include/openssl/*.h') ) {
326         # Skip some internals we don't want to document yet.
327         next if $f eq 'include/openssl/asn1.h';
328         next if $f eq 'include/openssl/asn1t.h';
329         next if $f eq 'include/openssl/err.h';
330         open(IN, $f) || die "Can't open $f, $!";
331         while ( <IN> ) {
332             next unless /^#\s*define\s*(\S+)\(/;
333             my $macro = $1;
334             next if $docced{$macro} || defined $seen{$macro};
335             next if $macro =~ /i2d_/
336                 || $macro =~ /d2i_/
337                 || $macro =~ /DEPRECATEDIN/
338                 || $macro =~ /IMPLEMENT_/
339                 || $macro =~ /DECLARE_/;
340
341             # Skip macros known to be missing
342             next if $opt_v && grep( /^$macro$/, @missing);
343     
344             print "$f:$macro\n" if $opt_d || $opt_e;
345             $count++;
346             $seen{$macro} = 1;
347         }
348         close(IN);
349     }
350     print "# Found $count macros missing\n" if !$opt_s || $count > 0;
351 }
352
353 sub printem()
354 {
355     my $libname = shift;
356     my $numfile = shift;
357     my $missingfile = shift;
358     my $count = 0;
359     my %seen;
360
361     my @missing = loadmissing($missingfile) if ($opt_v);
362
363     foreach my $func ( &parsenum($numfile) ) {
364         next if $docced{$func} || defined $seen{$func};
365
366         # Skip ASN1 utilities
367         next if $func =~ /^ASN1_/;
368
369         # Skip functions known to be missing
370         next if $opt_v && grep( /^$func$/, @missing);
371
372         print "$libname:$func\n" if $opt_d || $opt_e;
373         $count++;
374         $seen{$func} = 1;
375     }
376     print "# Found $count missing from $numfile\n\n" if !$opt_s || $count > 0;
377 }
378
379
380 # Collection of links in each POD file.
381 # filename => [ "foo(1)", "bar(3)", ... ]
382 my %link_collection = ();
383 # Collection of names in each POD file.
384 # "name(s)" => filename
385 my %name_collection = ();
386
387 sub collectnames {
388     my $filename = shift;
389     $filename =~ m|man(\d)/|;
390     my $section = $1;
391     my $simplename = basename($filename, ".pod");
392     my $id = "${filename}:1:";
393
394     my $contents = '';
395     {
396         local $/ = undef;
397         open POD, $filename or die "Couldn't open $filename, $!";
398         $contents = <POD>;
399         close POD;
400     }
401
402     $contents =~ /=head1 NAME([^=]*)=head1 /ms;
403     my $tmp = $1;
404     unless (defined $tmp) {
405         print "$id weird name section\n";
406         return;
407     }
408     $tmp =~ tr/\n/ /;
409     $tmp =~ s/-.*//g;
410
411     my @names = map { s/^\s+//g; s/\s+$//g; $_ } split(/,/, $tmp);
412     unless (grep { $simplename eq $_ } @names) {
413         print "$id missing $simplename\n";
414         push @names, $simplename;
415     }
416     foreach my $name (@names) {
417         next if $name eq "";
418         if ($name =~ /\s/) {
419             print "$id '$name' contains white space\n";
420         }
421         my $name_sec = "$name($section)";
422         if (! exists $name_collection{$name_sec}) {
423             $name_collection{$name_sec} = $filename;
424         } else { #elsif ($filename ne $name_collection{$name_sec}) {
425             print "$id $name_sec also in $name_collection{$name_sec}\n";
426         }
427     }
428
429     my @foreign_names =
430         map { map { s/\s+//g; $_ } split(/,/, $_) }
431         $contents =~ /=for\s+comment\s+foreign\s+manuals:\s*(.*)\n\n/;
432     foreach (@foreign_names) {
433         $name_collection{$_} = undef; # It still exists!
434     }
435
436     my @links = $contents =~ /L<
437                               # if the link is of the form L<something|name(s)>,
438                               # then remove 'something'.  Note that 'something'
439                               # may contain POD codes as well...
440                               (?:(?:[^\|]|<[^>]*>)*\|)?
441                               # we're only interested in references that have
442                               # a one digit section number
443                               ([^\/>\(]+\(\d\))
444                              /gx;
445     $link_collection{$filename} = [ @links ];
446 }
447
448 sub checklinks {
449     foreach my $filename (sort keys %link_collection) {
450         foreach my $link (@{$link_collection{$filename}}) {
451             print "${filename}:1: reference to non-existing $link\n"
452                 unless exists $name_collection{$link};
453         }
454     }
455 }
456
457 sub publicize() {
458     foreach my $name ( &parsenum('util/libcrypto.num') ) {
459         $public{$name} = 1;
460     }
461     foreach my $name ( &parsenum('util/libssl.num') ) {
462         $public{$name} = 1;
463     }
464     foreach my $name ( &parsenum('util/private.num') ) {
465         $public{$name} = 1;
466     }
467 }
468
469 my %skips = (
470     'aes128' => 1,
471     'aes192' => 1,
472     'aes256' => 1,
473     'aria128' => 1,
474     'aria192' => 1,
475     'aria256' => 1,
476     'camellia128' => 1,
477     'camellia192' => 1,
478     'camellia256' => 1,
479     'des' => 1,
480     'des3' => 1,
481     'idea' => 1,
482     '[cipher]' => 1,
483     '[digest]' => 1,
484 );
485
486 sub checkflags() {
487     my $cmd = shift;
488     my %cmdopts;
489     my %docopts;
490     my $ok = 1;
491
492     # Get the list of options in the command.
493     open CFH, "./apps/openssl list --options $cmd|"
494         || die "Can list options for $cmd, $!";
495     while ( <CFH> ) {
496         chop;
497         s/ .$//;
498         $cmdopts{$_} = 1;
499     }
500     close CFH;
501
502     # Get the list of flags from the synopsis
503     open CFH, "<doc/man1/$cmd.pod"
504         || die "Can't open $cmd.pod, $!";
505     while ( <CFH> ) {
506         chop;
507         last if /DESCRIPTION/;
508         next unless /\[B<-([^ >]+)/;
509         $docopts{$1} = 1;
510     }
511     close CFH;
512
513     # See what's in the command not the manpage.
514     my @undocced = ();
515     foreach my $k ( keys %cmdopts ) {
516         push @undocced, $k unless $docopts{$k};
517     }
518     if ( scalar @undocced > 0 ) {
519         $ok = 0;
520         foreach ( @undocced ) {
521             print "doc/man1/$cmd.pod: Missing -$_\n";
522         }
523     }
524
525     # See what's in the command not the manpage.
526     my @unimpl = ();
527     foreach my $k ( keys %docopts ) {
528         push @unimpl, $k unless $cmdopts{$k};
529     }
530     if ( scalar @unimpl > 0 ) {
531         $ok = 0;
532         foreach ( @unimpl ) {
533             next if defined $skips{$_};
534             print "doc/man1/$cmd.pod: Not implemented -$_\n";
535         }
536     }
537
538     return $ok;
539 }
540
541 getopts('cdeslnphuv');
542
543 &help() if $opt_h;
544
545 $opt_n = 1 if $opt_p;
546 $opt_u = 1 if $opt_d;
547 $opt_e = 1 if $opt_s;
548 $opt_v = 1 if $opt_e;
549
550 die "Cannot use both -u and -v" if $opt_u && $opt_v;
551 die "Cannot use both -d and -e" if $opt_d && $opt_e;
552
553 die "Need one of -[cdelnpuv] flags.\n"
554     unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v;
555
556 if ( $opt_c ) {
557     my $ok = 1;
558     my @commands = ();
559
560     # Get list of commands.
561     open FH, "./apps/openssl list -1 -commands|"
562         || die "Can't list commands, $!";
563     while ( <FH> ) {
564         chop;
565         push @commands, $_;
566     }
567     close FH;
568
569     # See if each has a manpage.
570     foreach ( @commands ) {
571         next if $_ eq 'help' || $_ eq 'exit';
572         if ( ! -f "doc/man1/$_.pod" ) {
573             print "doc/man1/$_.pod does not exist\n";
574             $ok = 0;
575         } else {
576             $ok = 0 if not &checkflags($_);
577         }
578     }
579
580     # See what help is missing.
581     open FH, "./apps/openssl list --missing-help |"
582         || die "Can't list missing help, $!";
583     while ( <FH> ) {
584         chop;
585         my ($cmd, $flag) = split;
586         print "$cmd has no help for -$flag\n";
587         $ok = 0;
588     }
589     close FH;
590
591     exit 1 if not $ok;
592 }
593
594 if ( $opt_l ) {
595     foreach (@ARGV ? @ARGV : (glob('doc/*/*.pod'),
596                               glob('doc/internal/*/*.pod'))) {
597         collectnames($_);
598     }
599     checklinks();
600 }
601
602 if ( $opt_n ) {
603     &publicize() if $opt_p;
604     foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) {
605         &check($_);
606     }
607     {
608         local $opt_p = undef;
609         foreach (@ARGV ? @ARGV : glob('doc/internal/*/*.pod')) {
610             &check($_);
611         }
612     }
613 }
614
615 if ( $opt_u || $opt_v) {
616     my %temp = getdocced('doc/man3');
617     foreach ( keys %temp ) {
618         $docced{$_} = $temp{$_};
619     }
620     &printem('crypto', 'util/libcrypto.num', 'util/missingcrypto.txt');
621     &printem('ssl', 'util/libssl.num', 'util/missingssl.txt');
622     &checkmacros();
623 }
624
625 exit;