diff options
author | Rich Salz <rsalz@openssl.org> | 2017-06-01 16:26:26 -0400 |
---|---|---|
committer | Rich Salz <rsalz@openssl.org> | 2017-06-01 16:26:26 -0400 |
commit | 274d1beea2ffff23a469a978658a83e03e46f80f (patch) | |
tree | cca4caebf7496d7c5056436bf02cf2f64d4b87ae /util | |
parent | 73bc53708c386c1ea85941d345721e23dc61c05c (diff) |
Add -p (public only) flag to find-doc-nits
Report if any non-public items are documented.
Add util/private.num that lists items that aren't in the public
(lib*.num) files that we do want to document.
Reviewed-by: Andy Polyakov <appro@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3603)
Diffstat (limited to 'util')
-rwxr-xr-x | util/find-doc-nits | 35 | ||||
-rw-r--r-- | util/private.num | 52 |
2 files changed, 80 insertions, 7 deletions
diff --git a/util/find-doc-nits b/util/find-doc-nits index 11acee1a20..643fb9fd3e 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -24,6 +24,7 @@ our($opt_u); our($opt_h); our($opt_n); our($opt_l); +our($opt_p); sub help() { @@ -32,6 +33,7 @@ Find small errors (nits) in documentation. Options: -l Print bogus links -n Print nits in POD pages -s Also print missing sections in POD pages (implies -n) + -p Warn if non-public name documented (implies -n) -u List undocumented functions -h Print this help message EOF @@ -40,6 +42,7 @@ EOF my $temp = '/tmp/docnits.txt'; my $OUT; +my %public; my %mandatory_sections = ( '*' => [ 'NAME', 'DESCRIPTION', 'COPYRIGHT' ], @@ -80,8 +83,10 @@ sub name_synopsis() print "$id the following exist as other .pod files:\n", join(" ", sort keys %foundfilenames), "\n" if %foundfilenames; - print "$id $simplename (filename) missing from NAME section\n", + print "$id $simplename (filename) missing from NAME section\n" unless $foundfilename; + print "$id $simplename is not public\n" + if $opt_p and !defined $public{$simplename}; # Find all functions in SYNOPSIS return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms; @@ -222,6 +227,7 @@ sub parsenum() or die "Can't open $file, $!, stopped"; while ( <$IN> ) { + next if /^#/; next if /\bNOEXIST\b/; next if /\bEXPORT_VAR_AS_FUNC\b/; push @apis, $1 if /([^\s]+).\s/; @@ -229,7 +235,7 @@ sub parsenum() close $IN; - print "# Found ", scalar(@apis), " in $file\n"; + print "# Found ", scalar(@apis), " in $file\n" unless $opt_p; return sort @apis; } @@ -346,14 +352,29 @@ sub checklinks { } } -getopts('lnshu'); +sub publicize() { + foreach my $name ( &parsenum('util/libcrypto.num') ) { + $public{$name} = 1; + } + foreach my $name ( &parsenum('util/libssl.num') ) { + $public{$name} = 1; + } + foreach my $name ( &parsenum('util/private.num') ) { + $public{$name} = 1; + } +} + +getopts('lnsphu'); + +&help() if $opt_h; -&help() if ( $opt_h ); +die "Need one of -l -n -s -p or -u flags.\n" + unless $opt_l or $opt_n or $opt_s or $opt_p or $opt_u; -die "Need one of -l -n -s or -u flags.\n" - unless $opt_l or $opt_n or $opt_s or $opt_u; +$opt_n = 1 if $opt_s or $opt_p; -if ( $opt_n or $opt_s ) { +if ( $opt_n ) { + &publicize() if $opt_p; foreach (@ARGV ? @ARGV : glob('doc/*/*.pod')) { &check($_); } diff --git a/util/private.num b/util/private.num new file mode 100644 index 0000000000..f68c6acf9b --- /dev/null +++ b/util/private.num @@ -0,0 +1,52 @@ +# This isn't a library ".num" file but is a list of documented items +# that don't appear in lib*.num -- because they are define's, in +# assembly language, etc. +BIO_ADDR datatype +BIO_ADDRINFO datatype +UI_STRING datatype +X509_STORE_set_verify_cb_func datatype +OPENSSL_Applink external +OPENSSL_ia32cap environment +OPENSSL_instrument_bus assembler +BIO_should_retry define +BN_num_bytes define +BN_zero define +DTLS_get_link_min_mtu define +DTLS_set_link_mtu define +ERR_GET_LIB define +EVP_PKEY_CTX_add1_tls1_prf_seed define +EVP_PKEY_CTX_set1_hkdf_key define +EVP_PKEY_CTX_set1_hkdf_salt define +EVP_PKEY_CTX_set1_tls1_prf_secret define +EVP_PKEY_CTX_set_hkdf_md define +EVP_PKEY_CTX_set_tls1_prf_md define +EVP_SignInit define +EVP_VerifyInit define +OPENSSL_VERSION_NUMBER define +OPENSSL_malloc define +OPENSSL_secure_malloc define +SSL_CTX_add1_chain_cert define +SSL_CTX_add_extra_chain_cert define +SSL_CTX_clear_mode define +SSL_CTX_get_mode define +SSL_CTX_sess_number define +SSL_CTX_sess_set_cache_size define +SSL_CTX_set1_curves define +SSL_CTX_set1_sigalgs define +SSL_CTX_set1_verify_cert_store define +SSL_CTX_set_max_cert_list define +SSL_CTX_set_min_proto_version define +SSL_CTX_set_mode define +SSL_CTX_set_read_ahead define +SSL_CTX_set_session_cache_mode define +SSL_CTX_set_split_send_fragment define +SSL_CTX_set_tlsext_servername_callback define +SSL_CTX_set_tlsext_status_cb define +SSL_CTX_set_tlsext_ticket_key_cb define +SSL_clear_mode define +SSL_get_extms_support define +SSL_get_mode define +SSL_get_peer_signature_nid define +SSL_get_server_tmp_key define +SSL_set_mode define +SSL_set_mtu define |