From: Rich Salz Date: Thu, 1 Jun 2017 20:26:26 +0000 (-0400) Subject: Add -p (public only) flag to find-doc-nits X-Git-Tag: OpenSSL_1_1_1-pre1~1401 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=274d1beea2ffff23a469a978658a83e03e46f80f 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 (Merged from https://github.com/openssl/openssl/pull/3603) --- diff --git a/doc/man3/d2i_Netscape_RSA.pod b/doc/man3/d2i_Netscape_RSA.pod deleted file mode 100644 index ee39bd817a..0000000000 --- a/doc/man3/d2i_Netscape_RSA.pod +++ /dev/null @@ -1,38 +0,0 @@ -=pod - -=head1 NAME - -i2d_Netscape_RSA, -d2i_Netscape_RSA -- insecure RSA public and private key encoding functions - -=head1 SYNOPSIS - - #include - - int i2d_Netscape_RSA(RSA *a, unsigned char **pp, int (*cb)()); - RSA * d2i_Netscape_RSA(RSA **a, const unsigned char **pp, long length, int (*cb)()); - -=head1 DESCRIPTION - -These functions decode and encode an RSA private -key in NET format. These functions are present to provide compatibility -with very old software. This format has some severe security weaknesses -and should be avoided if possible. - -These functions are similar to the B functions. - -=head1 SEE ALSO - -L - -=head1 COPYRIGHT - -Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. - -Licensed under the OpenSSL license (the "License"). You may not use -this file except in compliance with the License. You can obtain a copy -in the file LICENSE in the source distribution or at -L. - -=cut 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