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)

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