diff options
author | Matt Caswell <matt@openssl.org> | 2019-06-06 12:12:49 +0100 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2019-06-12 10:12:14 +0100 |
commit | b5283535d52002f892ef17c890a3e1840640a60b (patch) | |
tree | 9980c32d1efb9bb99b25a36d8482b2f9da6c0740 /util/find-doc-nits | |
parent | 51583cb8f464b49d2ea33b2be027274ac0d4b1a0 (diff) |
Make find-doc-nits check for newly added undocumented symbols
We create lists of undocumented functions and macros as they are now so
that find-doc-nits can check for newly introduced functions/macros that
are undocumented.
This works in a similar way to the -u and -d options to find-doc-nits.
These count undocumented symbols and print a detailed list of undocumented
symbols repsectively. This commit adds the -v and -e options to restrict
the count/detailed list to newly added undocumented symbols only.
There is also a new -s option that does the same as -e except that it
produces no output if there are no newly undocumented symbols.
We also amend "make doc-nits" to add the -s option which should cause
travis to fail if a PR adds undocumented symbols.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9094)
Diffstat (limited to 'util/find-doc-nits')
-rwxr-xr-x | util/find-doc-nits | 63 |
1 files changed, 52 insertions, 11 deletions
diff --git a/util/find-doc-nits b/util/find-doc-nits index 25f3d5e2c8..51dcd286d5 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -20,11 +20,14 @@ use OpenSSL::Util::Pod; # Options. our($opt_d); +our($opt_e); +our($opt_s); our($opt_h); our($opt_l); our($opt_n); our($opt_p); our($opt_u); +our($opt_v); our($opt_c); sub help() @@ -32,10 +35,13 @@ sub help() print <<EOF; Find small errors (nits) in documentation. Options: -d Detailed list of undocumented (implies -u) + -e Detailed list of new undocumented (implies -v) + -s Same as -e except no output is generated if nothing is undocumented -l Print bogus links -n Print nits in POD pages -p Warn if non-public name documented (implies -n) -u Count undocumented functions + -v Count new undocumented functions -h Print this help message -c List undocumented commands and options EOF @@ -291,12 +297,31 @@ sub getdocced my %docced; +sub loadmissing($) +{ + my $missingfile = shift; + my @missing; + + open FH, $missingfile + || die "Can't open $missingfile"; + while ( <FH> ) { + chomp; + next if /^#/; + push @missing, $_; + } + close FH; + + return @missing; +} + sub checkmacros() { my $count = 0; my %seen; - print "# Checking macros (approximate)\n"; + my @missing = loadmissing('util/missingmacro.txt') if ($opt_v); + + print "# Checking macros (approximate)\n" if !$opt_s; foreach my $f ( glob('include/openssl/*.h') ) { # Skip some internals we don't want to document yet. next if $f eq 'include/openssl/asn1.h'; @@ -312,33 +337,43 @@ sub checkmacros() || $macro =~ /DEPRECATEDIN/ || $macro =~ /IMPLEMENT_/ || $macro =~ /DECLARE_/; - print "$f:$macro\n" if $opt_d; + + # Skip macros known to be missing + next if $opt_v && grep( /^$macro$/, @missing); + + print "$f:$macro\n" if $opt_d || $opt_e; $count++; $seen{$macro} = 1; } close(IN); } - print "# Found $count macros missing (not all should be documented)\n" + print "# Found $count macros missing\n" if !$opt_s || $count > 0; } sub printem() { my $libname = shift; my $numfile = shift; + my $missingfile = shift; my $count = 0; my %seen; + my @missing = loadmissing($missingfile) if ($opt_v); + foreach my $func ( &parsenum($numfile) ) { next if $docced{$func} || defined $seen{$func}; # Skip ASN1 utilities next if $func =~ /^ASN1_/; - print "$libname:$func\n" if $opt_d; + # Skip functions known to be missing + next if $opt_v && grep( /^$func$/, @missing); + + print "$libname:$func\n" if $opt_d || $opt_e; $count++; $seen{$func} = 1; } - print "# Found $count missing from $numfile\n\n"; + print "# Found $count missing from $numfile\n\n" if !$opt_s || $count > 0; } @@ -503,14 +538,20 @@ sub checkflags() { return $ok; } -getopts('cdlnphu'); +getopts('cdeslnphuv'); &help() if $opt_h; + $opt_n = 1 if $opt_p; $opt_u = 1 if $opt_d; +$opt_e = 1 if $opt_s; +$opt_v = 1 if $opt_e; + +die "Cannot use both -u and -v" if $opt_u && $opt_v; +die "Cannot use both -d and -e" if $opt_d && $opt_e; -die "Need one of -[cdlnpu] flags.\n" - unless $opt_c or $opt_l or $opt_n or $opt_u; +die "Need one of -[cdelnpuv] flags.\n" + unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v; if ( $opt_c ) { my $ok = 1; @@ -571,13 +612,13 @@ if ( $opt_n ) { } } -if ( $opt_u ) { +if ( $opt_u || $opt_v) { my %temp = getdocced('doc/man3'); foreach ( keys %temp ) { $docced{$_} = $temp{$_}; } - &printem('crypto', 'util/libcrypto.num'); - &printem('ssl', 'util/libssl.num'); + &printem('crypto', 'util/libcrypto.num', 'util/missingcrypto.txt'); + &printem('ssl', 'util/libssl.num', 'util/missingssl.txt'); &checkmacros(); } |