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