]>
git.ipfire.org Git - thirdparty/openssl.git/blob - util/find-doc-nits
2 # Copyright 2002-2019 The OpenSSL Project Authors. All Rights Reserved.
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
16 use File
::Spec
::Functions
;
18 use lib catdir
(dirname
($0), "perl");
19 use OpenSSL
::Util
::Pod
;
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 -o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v)
42 -n Print nits in POD pages
43 -p Warn if non-public name documented (implies -n)
44 -u Count undocumented functions
45 -v Count new undocumented functions
46 -h Print this help message
47 -c List undocumented commands and options
52 my $temp = '/tmp/docnits.txt';
57 my %mandatory_sections =
58 ( '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ],
59 1 => [ 'SYNOPSIS', 'OPTIONS' ],
60 3 => [ 'SYNOPSIS', 'RETURN VALUES' ],
64 # Print error message, set $status.
66 print join(" ", @_), "\n";
70 # Cross-check functions in the NAME and SYNOPSIS section.
76 # Get NAME section and all words in it.
77 return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms;
80 err
($id, "trailing comma before - in NAME")
83 err
($id, "POD markup among the names in NAME")
86 err
($id, "missing comma in NAME")
89 my $dirname = dirname
($filename);
90 my $simplename = basename
(basename
($filename, ".in"), ".pod");
91 my $foundfilename = 0;
92 my %foundfilenames = ();
94 foreach my $n ( split ',', $tmp ) {
97 err
($id, "the name '$n' contains white-space")
100 $foundfilename++ if $n eq $simplename;
101 $foundfilenames{$n} = 1
102 if ((-f
"$dirname/$n.pod.in" || -f
"$dirname/$n.pod")
103 && $n ne $simplename);
105 err
($id, "the following exist as other .pod or .pod.in files:",
106 sort keys %foundfilenames)
108 err
($id, "$simplename (filename) missing from NAME section")
109 unless $foundfilename;
110 foreach my $n ( keys %names ) {
111 err
($id, "$n is not public")
112 if $opt_p and !defined $public{$n};
115 # Find all functions in SYNOPSIS
116 return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms;
118 foreach my $line ( split /\n+/, $syn ) {
119 next unless $line =~ /^\s/;
121 $line =~ s/STACK_OF\([^)]+\)/int/g;
122 $line =~ s/SPARSE_ARRAY_OF\([^)]+\)/int/g;
123 $line =~ s/__declspec\([^)]+\)//;
124 if ( $line =~ /env (\S*)=/ ) {
125 # environment variable env NAME=...
127 } elsif ( $line =~ /typedef.*\(\*(\S+)\)\(.*/ ) {
128 # a callback function pointer: typedef ... (*NAME)(...
130 } elsif ( $line =~ /typedef.* (\S+)\(.*/ ) {
131 # a callback function signature: typedef ... NAME(...
133 } elsif ( $line =~ /typedef.* (\S+);/ ) {
134 # a simple typedef: typedef ... NAME;
136 } elsif ( $line =~ /enum (\S*) \{/ ) {
137 # an enumeration: enum ... {
139 } elsif ( $line =~ /#(?:define|undef) ([A-Za-z0-9_]+)/ ) {
141 } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) {
147 err
($id, "$sym missing from NAME section")
148 unless defined $names{$sym};
151 # Do some sanity checks on the prototype.
152 err
($id, "prototype missing spaces around commas: $line")
153 if ( $line =~ /[a-z0-9],[^ ]/ );
156 foreach my $n ( keys %names ) {
157 next if $names{$n} == 2;
158 err
($id, "$n missing from SYNOPSIS")
162 # Check if SECTION ($3) is located before BEFORE ($4)
163 sub check_section_location
{
165 my $contents = shift;
169 return unless $contents =~ /=head1 $section/
170 and $contents =~ /=head1 $before/;
171 err
($id, "$section should appear before $before section")
172 if $contents =~ /=head1 $before.*=head1 $section/ms;
175 # Check if a =head1 is duplicated, or a =headX is duplicated within a
176 # =head1. Treats =head2 =head3 as equivalent -- it doesn't reset the head3
177 # sets if it finds a =head2 -- but that is good enough for now. Also check
178 # for proper capitalization, trailing periods, etc.
179 sub check_head_style
{
181 my $contents = shift;
185 foreach my $line ( split /\n+/, $contents ) {
186 next unless $line =~ /^=head/;
187 if ( $line =~ /head1/ ) {
188 err
($id, "duplicate section $line")
189 if defined $head1{$line};
193 err
($id, "duplicate subsection $line")
194 if defined $subheads{$line};
195 $subheads{$line} = 1;
197 err
($id, "period in =head")
198 if $line =~ /\.[^\w]/ or $line =~ /\.$/;
199 err
($id, "not all uppercase in =head1")
200 if $line =~ /head1.*[a-z]/;
201 err
($id, "all uppercase in subhead")
202 if $line =~ /head[234][ A-Z0-9]+$/;
207 my $filename = shift;
208 my $dirname = basename
(dirname
($filename));
213 open POD
, $filename or die "Couldn't open $filename, $!";
218 my $id = "${filename}:1:";
219 check_head_style
($id, $contents);
221 # Check ordering of some sections in man3
222 if ( $filename =~ m
|man3
/| ) {
223 check_section_location
($id, $contents, "RETURN VALUES", "EXAMPLES");
224 check_section_location
($id, $contents, "SEE ALSO", "HISTORY");
225 check_section_location
($id, $contents, "EXAMPLES", "SEE ALSO");
228 name_synopsis
($id, $filename, $contents)
229 unless $contents =~ /=for comment generic/
230 or $filename =~ m
@man[157]/@
;
232 err
($id, "doesn't start with =pod")
233 if $contents !~ /^=pod/;
234 err
($id, "doesn't end with =cut")
235 if $contents !~ /=cut\n$/;
236 err
($id, "more than one cut line.")
237 if $contents =~ /=cut.*=cut/ms;
238 err
($id, "EXAMPLE not EXAMPLES section.")
239 if $contents =~ /=head1 EXAMPLE[^S]/;
240 err
($id, "WARNING not WARNINGS section.")
241 if $contents =~ /=head1 WARNING[^S]/;
242 err
($id, "missing copyright")
243 if $contents !~ /Copyright .* The OpenSSL Project Authors/;
244 err
($id, "copyright not last")
245 if $contents =~ /head1 COPYRIGHT.*=head/ms;
246 err
($id, "head2 in All uppercase")
247 if $contents =~ /head2\s+[A-Z ]+\n/;
248 err
($id, "extra space after head")
249 if $contents =~ /=head\d\s\s+/;
250 err
($id, "period in NAME section")
251 if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms;
252 err
($id, "Duplicate $1 in L<>")
253 if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2;
254 err
($id, "Bad =over $1")
255 if $contents =~ /=over([^ ][^24])/;
256 err
($id, "Possible version style issue")
257 if $contents =~ /OpenSSL version [019]/;
259 if ( $contents !~ /=for comment multiple includes/ ) {
260 # Look for multiple consecutive openssl #include lines
261 # (non-consecutive lines are okay; see man3/MD5.pod).
262 if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) {
264 foreach my $line ( split /\n+/, $1 ) {
265 if ( $line =~ m
@include <openssl
/@
) {
266 err
($id, "has multiple includes")
275 open my $OUT, '>', $temp
276 or die "Can't open $temp, $!";
277 podchecker
($filename, $OUT);
279 open $OUT, '<', $temp
280 or die "Can't read $temp, $!";
282 next if /\(section\) in.*deprecated/;
286 unlink $temp || warn "Can't remove $temp, $!";
288 # Find what section this page is in; assume 3.
290 $section = $1 if $dirname =~ /man([1-9])/;
292 foreach ((@
{$mandatory_sections{'*'}}, @
{$mandatory_sections{$section}})) {
293 # Skip "return values" if not -s
294 err
($id, "missing $_ head1 section")
295 if $contents !~ /^=head1\s+${_}\s*$/m;
305 open my $IN, '<', $file
306 or die "Can't open $file, $!, stopped";
310 next if /\bNOEXIST\b/;
311 my @fields = split();
312 die "Malformed line $_"
313 if scalar @fields != 2 && scalar @fields != 4;
314 push @apis, $fields[0];
319 print "# Found ", scalar(@apis), " in $file\n" unless $opt_p;
328 foreach my $pod ( glob("$dir/*.pod"), glob("$dir/*.pod.in") ) {
329 my %podinfo = extract_pod_info
($pod);
330 foreach my $n ( @
{$podinfo{names
}} ) {
332 print "# Duplicate $n in $pod and $dups{$n}\n"
333 if defined $dups{$n} && $dups{$n} ne $pod;
345 my $missingfile = shift;
348 open FH
, $missingfile
349 || die "Can't open $missingfile";
366 @missing = loadmissing
('util/missingmacro111.txt');
368 @missing = loadmissing
('util/missingmacro.txt');
371 print "# Checking macros (approximate)\n"
373 foreach my $f ( glob('include/openssl/*.h') ) {
374 # Skip some internals we don't want to document yet.
375 next if $f eq 'include/openssl/asn1.h';
376 next if $f eq 'include/openssl/asn1t.h';
377 next if $f eq 'include/openssl/err.h';
378 open(IN
, $f) || die "Can't open $f, $!";
380 next unless /^#\s*define\s*(\S+)\(/;
382 next if $docced{$macro} || defined $seen{$macro};
383 next if $macro =~ /i2d_/
385 || $macro =~ /DEPRECATEDIN/
386 || $macro =~ /IMPLEMENT_/
387 || $macro =~ /DECLARE_/;
389 # Skip macros known to be missing
390 next if $opt_v && grep( /^$macro$/, @missing);
399 print "# Found $count macros missing\n"
400 if !$opt_s || $count > 0;
406 my $missingfile = shift;
410 my @missing = loadmissing
($missingfile) if ($opt_v);
412 foreach my $func ( parsenum
($numfile) ) {
413 next if $docced{$func} || defined $seen{$func};
415 # Skip ASN1 utilities
416 next if $func =~ /^ASN1_/;
418 # Skip functions known to be missing
419 next if $opt_v && grep( /^$func$/, @missing);
421 print "$libname:$func\n"
426 print "# Found $count missing from $numfile\n\n"
427 if !$opt_s || $count > 0;
431 # Collection of links in each POD file.
432 # filename => [ "foo(1)", "bar(3)", ... ]
433 my %link_collection = ();
434 # Collection of names in each POD file.
435 # "name(s)" => filename
436 my %name_collection = ();
439 my $filename = shift;
440 $filename =~ m
|man
(\d
)/|;
442 my $simplename = basename
(basename
($filename, ".in"), ".pod");
443 my $id = "${filename}:1:";
448 open POD
, $filename or die "Couldn't open $filename, $!";
453 $contents =~ /=head1 NAME([^=]*)=head1 /ms;
455 unless (defined $tmp) {
456 err
($id, "weird name section");
463 map { s
|/|-|g
; $_ } # Treat slash as dash
464 map { s/^\s+//g; s/\s+$//g; $_ } # Trim prefix and suffix blanks
466 unless (grep { $simplename eq $_ } @names) {
467 err
($id, "missing $simplename");
468 push @names, $simplename;
470 foreach my $name (@names) {
473 err
($id, "'$name' contains white space")
475 my $name_sec = "$name($section)";
476 if (! exists $name_collection{$name_sec}) {
477 $name_collection{$name_sec} = $filename;
478 } elsif ($filename eq $name_collection{$name_sec}) {
479 err
($id, "$name_sec repeated in NAME section of",
480 $name_collection{$name_sec});
482 err
($id, "$name_sec also in NAME section of",
483 $name_collection{$name_sec});
488 map { map { s/\s+//g; $_ } split(/,/, $_) }
489 $contents =~ /=for\s+comment\s+foreign\s+manuals:\s*(.*)\n\n/;
490 foreach (@foreign_names) {
491 $name_collection{$_} = undef; # It still exists!
494 my @links = $contents =~ /L
<
495 # if the link is of the form L<something|name(s)>,
496 # then remove 'something'. Note that 'something'
497 # may contain POD codes as well...
498 (?
:(?
:[^\
|]|<[^>]*>)*\
|)?
499 # we're only interested in references that have
500 # a one digit section number
503 $link_collection{$filename} = [ @links ];
507 foreach my $filename (sort keys %link_collection) {
508 foreach my $link (@
{$link_collection{$filename}}) {
509 err
("${filename}:1:", "reference to non-existing $link")
510 unless exists $name_collection{$link};
516 foreach my $name ( parsenum
('util/libcrypto.num') ) {
519 foreach my $name ( parsenum
('util/libssl.num') ) {
522 foreach my $name ( parsenum
('util/private.num') ) {
550 # Get the list of options in the command.
551 open CFH
, "./apps/openssl list --options $cmd|"
552 || die "Can list options for $cmd, $!";
560 # Get the list of flags from the synopsis
562 || die "Can't open $doc, $!";
565 last if /DESCRIPTION/;
566 next unless /\[B<-([^ >]+)/;
571 # See what's in the command not the manpage.
573 foreach my $k ( keys %cmdopts ) {
574 push @undocced, $k unless $docopts{$k};
576 if ( scalar @undocced > 0 ) {
577 foreach ( @undocced ) {
578 err
("doc/man1/$cmd.pod: Missing -$_");
582 # See what's in the command not the manpage.
584 foreach my $k ( keys %docopts ) {
585 push @unimpl, $k unless $cmdopts{$k};
587 if ( scalar @unimpl > 0 ) {
588 foreach ( @unimpl ) {
589 next if defined $skips{$_};
590 err
("doc/man1/$cmd.pod: Not implemented -$_");
595 getopts
('cdesolnphuv');
599 $opt_n = 1 if $opt_p;
600 $opt_u = 1 if $opt_d;
601 $opt_e = 1 if $opt_s;
602 $opt_v = 1 if $opt_o || $opt_e;
604 die "Cannot use both -u and -v"
606 die "Cannot use both -d and -e"
609 # We only need to check c, l, n, u and v.
610 # Options d, e, s, o and p imply one of the above.
611 die "Need one of -[cdesolnpuv] flags.\n"
612 unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v;
617 # Get list of commands.
618 open FH
, "./apps/openssl list -1 -commands|"
619 || die "Can't list commands, $!";
626 # See if each has a manpage.
627 foreach my $cmd ( @commands ) {
628 next if $cmd eq 'help' || $cmd eq 'exit';
629 my $doc = "doc/man1/$cmd.pod";
630 $doc = "doc/man1/openssl-$cmd.pod" if -f
"doc/man1/openssl-$cmd.pod";
632 err
("$doc does not exist");
634 checkflags
($cmd, $doc);
638 # See what help is missing.
639 open FH
, "./apps/openssl list --missing-help |"
640 || die "Can't list missing help, $!";
643 my ($cmd, $flag) = split;
644 err
("$cmd has no help for -$flag");
652 foreach (@ARGV ?
@ARGV : (glob('doc/*/*.pod'), glob('doc/*/*.pod.in'),
653 glob('doc/internal/*/*.pod'))) {
660 publicize
() if $opt_p;
661 foreach (@ARGV ?
@ARGV : (glob('doc/*/*.pod'), glob('doc/*/*.pod.in'))) {
665 local $opt_p = undef;
666 foreach (@ARGV ?
@ARGV : glob('doc/internal/*/*.pod')) {
672 if ( $opt_u || $opt_v) {
673 my %temp = getdocced
('doc/man3');
674 foreach ( keys %temp ) {
675 $docced{$_} = $temp{$_};
678 printem
('crypto', 'util/libcrypto.num', 'util/missingcrypto111.txt');
679 printem
('ssl', 'util/libssl.num', 'util/missingssl111.txt');
681 printem
('crypto', 'util/libcrypto.num', 'util/missingcrypto.txt');
682 printem
('ssl', 'util/libssl.num', 'util/missingssl.txt');