]>
Commit | Line | Data |
---|---|---|
1bc74519 | 1 | #! /usr/bin/env perl |
05ea606a RS |
2 | # Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved. |
3 | # | |
4 | # Licensed under the OpenSSL license (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 | ||
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. |
35ea640a | 22 | our($opt_s); |
71a8b855 RS |
23 | our($opt_u); |
24 | our($opt_h); | |
25 | our($opt_n); | |
9e183d22 | 26 | our($opt_l); |
274d1bee | 27 | our($opt_p); |
71a8b855 RS |
28 | |
29 | sub help() | |
30 | { | |
31 | print <<EOF; | |
32 | Find small errors (nits) in documentation. Options: | |
9e183d22 | 33 | -l Print bogus links |
71a8b855 RS |
34 | -n Print nits in POD pages |
35 | -s Also print missing sections in POD pages (implies -n) | |
274d1bee | 36 | -p Warn if non-public name documented (implies -n) |
71a8b855 RS |
37 | -u List undocumented functions |
38 | -h Print this help message | |
39 | EOF | |
40 | exit; | |
41 | } | |
1bc74519 | 42 | |
05ea606a RS |
43 | my $temp = '/tmp/docnits.txt'; |
44 | my $OUT; | |
274d1bee | 45 | my %public; |
05ea606a | 46 | |
169a8e39 RL |
47 | my %mandatory_sections = |
48 | ( '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ], | |
3dfda1a6 RS |
49 | 1 => [ 'SYNOPSIS', 'OPTIONS' ], |
50 | 3 => [ 'SYNOPSIS', 'RETURN VALUES' ], | |
169a8e39 RL |
51 | 5 => [ ], |
52 | 7 => [ ] ); | |
169a8e39 | 53 | |
35ea640a RS |
54 | # Cross-check functions in the NAME and SYNOPSIS section. |
55 | sub name_synopsis() | |
56 | { | |
57 | my $id = shift; | |
58 | my $filename = shift; | |
59 | my $contents = shift; | |
60 | ||
35ea640a RS |
61 | # Get NAME section and all words in it. |
62 | return unless $contents =~ /=head1 NAME(.*)=head1 SYNOPSIS/ms; | |
63 | my $tmp = $1; | |
64 | $tmp =~ tr/\n/ /; | |
3ba4dac6 | 65 | print "$id trailing comma before - in NAME\n" if $tmp =~ /, *-/; |
2bcb232e RS |
66 | $tmp =~ s/ -.*//g; |
67 | $tmp =~ s/ */ /g; | |
68 | print "$id missing comma in NAME\n" if $tmp =~ /[^,] /; | |
35ea640a | 69 | $tmp =~ s/,//g; |
fbba5d11 RS |
70 | |
71 | my $dirname = dirname($filename); | |
72 | my $simplename = basename($filename); | |
73 | $simplename =~ s/.pod$//; | |
74 | my $foundfilename = 0; | |
75 | my %foundfilenames = (); | |
35ea640a RS |
76 | my %names; |
77 | foreach my $n ( split ' ', $tmp ) { | |
78 | $names{$n} = 1; | |
fbba5d11 RS |
79 | $foundfilename++ if $n eq $simplename; |
80 | $foundfilenames{$n} = 1 | |
81 | if -f "$dirname/$n.pod" && $n ne $simplename; | |
35ea640a | 82 | } |
fbba5d11 RS |
83 | print "$id the following exist as other .pod files:\n", |
84 | join(" ", sort keys %foundfilenames), "\n" | |
85 | if %foundfilenames; | |
274d1bee | 86 | print "$id $simplename (filename) missing from NAME section\n" |
fbba5d11 | 87 | unless $foundfilename; |
274d1bee RS |
88 | print "$id $simplename is not public\n" |
89 | if $opt_p and !defined $public{$simplename}; | |
35ea640a RS |
90 | |
91 | # Find all functions in SYNOPSIS | |
92 | return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms; | |
93 | my $syn = $1; | |
94 | foreach my $line ( split /\n+/, $syn ) { | |
8162f6f5 | 95 | my $sym; |
c952780c RS |
96 | $line =~ s/STACK_OF\([^)]+\)/int/g; |
97 | $line =~ s/__declspec\([^)]+\)//; | |
121677b4 RS |
98 | if ( $line =~ /env (\S*)=/ ) { |
99 | # environment variable env NAME=... | |
100 | $sym = $1; | |
101 | } elsif ( $line =~ /typedef.*\(\*(\S+)\)\(.*/ ) { | |
102 | # a callback function: typedef ... (*NAME)(... | |
103 | $sym = $1; | |
104 | } elsif ( $line =~ /typedef.* (\S+);/ ) { | |
105 | # a simple typedef: typedef ... NAME; | |
8162f6f5 | 106 | $sym = $1; |
5d583521 | 107 | } elsif ( $line =~ /enum (\S*) \{/ ) { |
d4ea9659 RS |
108 | # an enumeration: enum ... { |
109 | $sym = $1; | |
c952780c | 110 | } elsif ( $line =~ /#define ([A-Za-z0-9_]+)/ ) { |
8162f6f5 RS |
111 | $sym = $1; |
112 | } elsif ( $line =~ /([A-Za-z0-9_]+)\(/ ) { | |
113 | $sym = $1; | |
114 | } | |
115 | else { | |
116 | next; | |
117 | } | |
118 | print "$id $sym missing from NAME section\n" | |
119 | unless defined $names{$sym}; | |
120 | $names{$sym} = 2; | |
aebb9aac RS |
121 | |
122 | # Do some sanity checks on the prototype. | |
123 | print "$id prototype missing spaces around commas: $line\n" | |
124 | if ( $line =~ /[a-z0-9],[^ ]/ ); | |
35ea640a RS |
125 | } |
126 | ||
127 | foreach my $n ( keys %names ) { | |
128 | next if $names{$n} == 2; | |
129 | print "$id $n missing from SYNOPSIS\n"; | |
130 | } | |
131 | } | |
132 | ||
1bc74519 RS |
133 | sub check() |
134 | { | |
169a8e39 RL |
135 | my $filename = shift; |
136 | my $dirname = basename(dirname($filename)); | |
843666ff | 137 | |
1bc74519 RS |
138 | my $contents = ''; |
139 | { | |
140 | local $/ = undef; | |
169a8e39 | 141 | open POD, $filename or die "Couldn't open $filename, $!"; |
1bc74519 RS |
142 | $contents = <POD>; |
143 | close POD; | |
144 | } | |
843666ff RS |
145 | |
146 | my $id = "${filename}:1:"; | |
35ea640a | 147 | |
4692340e | 148 | &name_synopsis($id, $filename, $contents) |
8162f6f5 | 149 | unless $contents =~ /=for comment generic/ |
99d63d46 | 150 | or $filename =~ m@man[157]/@; |
35ea640a RS |
151 | |
152 | print "$id doesn't start with =pod\n" | |
05ea606a | 153 | if $contents !~ /^=pod/; |
35ea640a | 154 | print "$id doesn't end with =cut\n" |
05ea606a | 155 | if $contents !~ /=cut\n$/; |
35ea640a | 156 | print "$id more than one cut line.\n" |
05ea606a | 157 | if $contents =~ /=cut.*=cut/ms; |
35ea640a | 158 | print "$id missing copyright\n" |
05ea606a | 159 | if $contents !~ /Copyright .* The OpenSSL Project Authors/; |
35ea640a | 160 | print "$id copyright not last\n" |
05ea606a | 161 | if $contents =~ /head1 COPYRIGHT.*=head/ms; |
35ea640a | 162 | print "$id head2 in All uppercase\n" |
843666ff | 163 | if $contents =~ /head2\s+[A-Z ]+\n/; |
35ea640a RS |
164 | print "$id extra space after head\n" |
165 | if $contents =~ /=head\d\s\s+/; | |
166 | print "$id period in NAME section\n" | |
167 | if $contents =~ /=head1 NAME.*\.\n.*=head1 SYNOPSIS/ms; | |
168 | print "$id POD markup in NAME section\n" | |
169 | if $contents =~ /=head1 NAME.*[<>].*=head1 SYNOPSIS/ms; | |
5a3371e2 RS |
170 | print "$id Duplicate $1 in L<>\n" |
171 | if $contents =~ /L<([^>]*)\|([^>]*)>/ && $1 eq $2; | |
e1271ac2 | 172 | print "$id Bad =over $1\n" |
2f61bc2e | 173 | if $contents =~ /=over([^ ][^24])/; |
843666ff RS |
174 | |
175 | # Look for multiple consecutive openssl #include lines. | |
176 | # Consecutive because of files like md5.pod. Sometimes it's okay | |
177 | # or necessary, as in ssl/SSL_set1_host.pod | |
178 | if ( $contents !~ /=for comment multiple includes/ ) { | |
179 | if ( $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms ) { | |
180 | my $count = 0; | |
181 | foreach my $line ( split /\n+/, $1 ) { | |
182 | if ( $line =~ m@include <openssl/@ ) { | |
183 | if ( ++$count == 2 ) { | |
35ea640a | 184 | print "$id has multiple includes\n"; |
843666ff RS |
185 | } |
186 | } else { | |
187 | $count = 0; | |
188 | } | |
189 | } | |
190 | } | |
191 | } | |
05ea606a | 192 | |
35ea640a RS |
193 | return unless $opt_s; |
194 | ||
843666ff RS |
195 | # Find what section this page is in. If run from "." assume |
196 | # section 3. | |
99d63d46 RS |
197 | my $section = 3; |
198 | $section = $1 if $dirname =~ /man([1-9])/; | |
169a8e39 RL |
199 | |
200 | foreach ((@{$mandatory_sections{'*'}}, @{$mandatory_sections{$section}})) { | |
3dfda1a6 | 201 | print "$id: missing $_ head1 section\n" |
169a8e39 RL |
202 | if $contents !~ /^=head1\s+${_}\s*$/m; |
203 | } | |
204 | ||
35ea640a RS |
205 | open my $OUT, '>', $temp |
206 | or die "Can't open $temp, $!"; | |
169a8e39 | 207 | podchecker($filename, $OUT); |
35ea640a RS |
208 | close $OUT; |
209 | open $OUT, '<', $temp | |
210 | or die "Can't read $temp, $!"; | |
211 | while ( <$OUT> ) { | |
212 | next if /\(section\) in.*deprecated/; | |
213 | print; | |
214 | } | |
215 | close $OUT; | |
216 | unlink $temp || warn "Can't remove $temp, $!"; | |
05ea606a | 217 | } |
1bc74519 | 218 | |
71a8b855 RS |
219 | my %dups; |
220 | ||
221 | sub parsenum() | |
222 | { | |
223 | my $file = shift; | |
224 | my @apis; | |
225 | ||
226 | open my $IN, '<', $file | |
227 | or die "Can't open $file, $!, stopped"; | |
228 | ||
229 | while ( <$IN> ) { | |
274d1bee | 230 | next if /^#/; |
71a8b855 RS |
231 | next if /\bNOEXIST\b/; |
232 | next if /\bEXPORT_VAR_AS_FUNC\b/; | |
233 | push @apis, $1 if /([^\s]+).\s/; | |
234 | } | |
235 | ||
236 | close $IN; | |
237 | ||
274d1bee | 238 | print "# Found ", scalar(@apis), " in $file\n" unless $opt_p; |
71a8b855 RS |
239 | return sort @apis; |
240 | } | |
241 | ||
242 | sub getdocced() | |
243 | { | |
244 | my $dir = shift; | |
245 | my %return; | |
246 | ||
247 | foreach my $pod ( glob("$dir/*.pod") ) { | |
248 | my %podinfo = extract_pod_info($pod); | |
249 | foreach my $n ( @{$podinfo{names}} ) { | |
250 | $return{$n} = $pod; | |
251 | print "# Duplicate $n in $pod and $dups{$n}\n" | |
252 | if defined $dups{$n} && $dups{$n} ne $pod; | |
253 | $dups{$n} = $pod; | |
254 | } | |
255 | } | |
256 | ||
257 | return %return; | |
258 | } | |
259 | ||
260 | my %docced; | |
261 | ||
262 | sub printem() | |
263 | { | |
264 | my $libname = shift; | |
265 | my $numfile = shift; | |
266 | my $count = 0; | |
267 | ||
268 | foreach my $func ( &parsenum($numfile) ) { | |
269 | next if $docced{$func}; | |
270 | ||
271 | # Skip ASN1 utilities | |
272 | next if $func =~ /^ASN1_/; | |
273 | ||
274 | print "$libname:$func\n"; | |
275 | $count++; | |
276 | } | |
277 | print "# Found $count missing from $numfile\n\n"; | |
278 | } | |
279 | ||
280 | ||
9e183d22 RS |
281 | # Collection of links in each POD file. |
282 | # filename => [ "foo(1)", "bar(3)", ... ] | |
283 | my %link_collection = (); | |
284 | # Collection of names in each POD file. | |
285 | # "name(s)" => filename | |
286 | my %name_collection = (); | |
287 | ||
288 | sub collectnames { | |
289 | my $filename = shift; | |
290 | $filename =~ m|man(\d)/|; | |
291 | my $section = $1; | |
292 | my $simplename = basename($filename, ".pod"); | |
293 | my $id = "${filename}:1:"; | |
294 | ||
295 | my $contents = ''; | |
296 | { | |
297 | local $/ = undef; | |
298 | open POD, $filename or die "Couldn't open $filename, $!"; | |
299 | $contents = <POD>; | |
300 | close POD; | |
301 | } | |
302 | ||
303 | $contents =~ /=head1 NAME([^=]*)=head1 /ms; | |
304 | my $tmp = $1; | |
305 | unless (defined $tmp) { | |
306 | print "$id weird name section\n"; | |
307 | return; | |
308 | } | |
309 | $tmp =~ tr/\n/ /; | |
310 | $tmp =~ s/-.*//g; | |
311 | ||
312 | my @names = map { s/\s+//g; $_ } split(/,/, $tmp); | |
313 | unless (grep { $simplename eq $_ } @names) { | |
314 | print "$id missing $simplename\n"; | |
315 | push @names, $simplename; | |
316 | } | |
317 | foreach my $name (@names) { | |
318 | next if $name eq ""; | |
319 | my $name_sec = "$name($section)"; | |
320 | if (! exists $name_collection{$name_sec}) { | |
321 | $name_collection{$name_sec} = $filename; | |
322 | } else { #elsif ($filename ne $name_collection{$name_sec}) { | |
323 | print "$id $name_sec also in $name_collection{$name_sec}\n"; | |
324 | } | |
325 | } | |
326 | ||
327 | my @foreign_names = | |
328 | map { map { s/\s+//g; $_ } split(/,/, $_) } | |
329 | $contents =~ /=for\s+comment\s+foreign\s+manuals:\s*(.*)\n\n/; | |
330 | foreach (@foreign_names) { | |
331 | $name_collection{$_} = undef; # It still exists! | |
332 | } | |
333 | ||
334 | my @links = $contents =~ /L< | |
335 | # if the link is of the form L<something|name(s)>, | |
336 | # then remove 'something'. Note that 'something' | |
337 | # may contain POD codes as well... | |
338 | (?:(?:[^\|]|<[^>]*>)*\|)? | |
339 | # we're only interested in referenses that have | |
340 | # a one digit section number | |
341 | ([^\/>\(]+\(\d\)) | |
342 | /gx; | |
343 | $link_collection{$filename} = [ @links ]; | |
344 | } | |
345 | ||
346 | sub checklinks { | |
347 | foreach my $filename (sort keys %link_collection) { | |
348 | foreach my $link (@{$link_collection{$filename}}) { | |
349 | print "${filename}:1: reference to non-existing $link\n" | |
350 | unless exists $name_collection{$link}; | |
351 | } | |
352 | } | |
353 | } | |
354 | ||
274d1bee RS |
355 | sub publicize() { |
356 | foreach my $name ( &parsenum('util/libcrypto.num') ) { | |
357 | $public{$name} = 1; | |
358 | } | |
359 | foreach my $name ( &parsenum('util/libssl.num') ) { | |
360 | $public{$name} = 1; | |
361 | } | |
362 | foreach my $name ( &parsenum('util/private.num') ) { | |
363 | $public{$name} = 1; | |
364 | } | |
365 | } | |
366 | ||
367 | getopts('lnsphu'); | |
368 | ||
369 | &help() if $opt_h; | |
35ea640a | 370 | |
274d1bee RS |
371 | die "Need one of -l -n -s -p or -u flags.\n" |
372 | unless $opt_l or $opt_n or $opt_s or $opt_p or $opt_u; | |
71a8b855 | 373 | |
274d1bee | 374 | $opt_n = 1 if $opt_s or $opt_p; |
3dfda1a6 | 375 | |
274d1bee RS |
376 | if ( $opt_n ) { |
377 | &publicize() if $opt_p; | |
71a8b855 RS |
378 | foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) { |
379 | &check($_); | |
380 | } | |
381 | } | |
9e183d22 RS |
382 | |
383 | if ( $opt_l ) { | |
384 | foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) { | |
385 | collectnames($_); | |
386 | } | |
387 | checklinks(); | |
388 | } | |
389 | ||
71a8b855 RS |
390 | if ( $opt_u ) { |
391 | my %temp = &getdocced('doc/man3'); | |
392 | foreach ( keys %temp ) { | |
393 | $docced{$_} = $temp{$_}; | |
394 | } | |
395 | &printem('crypto', 'util/libcrypto.num'); | |
396 | &printem('ssl', 'util/libssl.num'); | |
1bc74519 | 397 | } |
05ea606a | 398 | |
35ea640a | 399 | exit; |