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