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)

Configurations/unix-Makefile.tmpl

@@ -728,7 +728,7 @@ generate: generate_apps generate_crypto_bn generate_crypto_objects \
 
 .PHONY: doc-nits
 doc-nits: build_generated
-	(cd $(SRCDIR); $(PERL) util/find-doc-nits -n -p ) >doc-nits
+	(cd $(SRCDIR); $(PERL) util/find-doc-nits -n -p -s ) >doc-nits
 	@if [ -s doc-nits ] ; then cat doc-nits ; exit 1; \
 	else echo 'doc-nits: no errors.'; rm doc-nits ; fi
 

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 "Need one of -[cdlnpu] flags.\n"
-    unless $opt_c or $opt_l or $opt_n or $opt_u;
+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 -[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();
 }
 

util/missingmacro.txt

@@ -0,0 +1,217 @@
+# A list of macros that are known to be missing documentation as used by the
+# find-doc-nits -v option. The list is as of commit 355b419698.
+BIO_get_flags
+BIO_set_retry_special
+BIO_set_retry_read
+BIO_set_retry_write
+BIO_clear_retry_flags
+BIO_get_retry_flags
+BIO_CB_return
+BIO_cb_pre
+BIO_cb_post
+BIO_set_app_data
+BIO_get_app_data
+BIO_set_conn_mode
+BIO_dup_state
+BIO_buffer_get_num_lines
+BIO_buffer_peek
+BIO_ctrl_dgram_connect
+BIO_ctrl_set_connected
+BIO_dgram_recv_timedout
+BIO_dgram_send_timedout
+BIO_dgram_get_peer
+BIO_dgram_set_peer
+BIO_dgram_get_mtu_overhead
+BIO_sock_cleanup
+ossl_bio__attr__
+BN_prime_checks_for_size
+BN_GF2m_sub
+BN_GF2m_cmp
+BUF_strdup
+BUF_strndup
+BUF_memdup
+BUF_strlcpy
+BUF_strlcat
+BUF_strnlen
+COMP_zlib_cleanup
+NCONF_get_number
+OSSL_CORE_MAKE_FUNC
+OPENSSL_MALLOC_MAX_NELEMS
+CRYPTO_cleanup_all_ex_data
+CRYPTO_num_locks
+CRYPTO_set_locking_callback
+CRYPTO_get_locking_callback
+CRYPTO_set_add_lock_callback
+CRYPTO_get_add_lock_callback
+CRYPTO_THREADID_set_numeric
+CRYPTO_THREADID_set_pointer
+CRYPTO_THREADID_set_callback
+CRYPTO_THREADID_get_callback
+CRYPTO_THREADID_current
+CRYPTO_THREADID_cmp
+CRYPTO_THREADID_cpy
+CRYPTO_THREADID_hash
+CRYPTO_set_id_callback
+CRYPTO_get_id_callback
+CRYPTO_thread_id
+CRYPTO_set_dynlock_create_callback
+CRYPTO_set_dynlock_lock_callback
+CRYPTO_set_dynlock_destroy_callback
+CRYPTO_get_dynlock_create_callback
+CRYPTO_get_dynlock_lock_callback
+CRYPTO_get_dynlock_destroy_callback
+OpenSSLDie
+OPENSSL_assert
+DSA_is_prime
+OPENSSL_GLOBAL_REF
+ECParameters_dup
+ENGINE_load_openssl
+ENGINE_load_dynamic
+ENGINE_load_padlock
+ENGINE_load_capi
+ENGINE_load_afalg
+ENGINE_load_cryptodev
+ENGINE_load_rdrand
+EVP_MD_nid
+EVP_MD_name
+EVP_CIPHER_name
+EVP_ENCODE_LENGTH
+EVP_DECODE_LENGTH
+BIO_set_md_ctx
+EVP_add_cipher_alias
+EVP_add_digest_alias
+EVP_delete_cipher_alias
+EVP_delete_digest_alias
+EVP_MD_CTX_create
+EVP_MD_CTX_init
+EVP_MD_CTX_destroy
+EVP_CIPHER_CTX_init
+EVP_CIPHER_CTX_cleanup
+OPENSSL_add_all_algorithms_conf
+OPENSSL_add_all_algorithms_noconf
+LHASH_HASH_FN
+LHASH_COMP_FN
+LHASH_DOALL_ARG_FN
+LHASH_OF
+DEFINE_LHASH_OF
+int_implement_lhash_doall
+OBJ_create_and_add_object
+OBJ_bsearch
+OBJ_bsearch_ex
+PEM_read_bio_OCSP_REQUEST
+PEM_read_bio_OCSP_RESPONSE
+PEM_write_bio_OCSP_REQUEST
+PEM_write_bio_OCSP_RESPONSE
+ASN1_BIT_STRING_digest
+OCSP_CERTSTATUS_dup
+OPENSSL_VERSION_PREREQ
+OPENSSL_MSTR_HELPER
+OPENSSL_MSTR
+OSSL_PARAM_DEFN
+OSSL_PARAM_int
+OSSL_PARAM_uint
+OSSL_PARAM_long
+OSSL_PARAM_ulong
+OSSL_PARAM_int32
+OSSL_PARAM_uint32
+OSSL_PARAM_int64
+OSSL_PARAM_uint64
+OSSL_PARAM_size_t
+OSSL_PARAM_double
+OSSL_PARAM_SIZED_int
+OSSL_PARAM_SIZED_uint
+OSSL_PARAM_SIZED_long
+OSSL_PARAM_SIZED_ulong
+OSSL_PARAM_SIZED_int32
+OSSL_PARAM_SIZED_uint32
+OSSL_PARAM_SIZED_int64
+OSSL_PARAM_SIZED_uint64
+OSSL_PARAM_SIZED_size_t
+OSSL_PARAM_SIZED_double
+PKCS7_get_signed_attributes
+PKCS7_get_attributes
+PKCS7_type_is_signed
+PKCS7_type_is_encrypted
+PKCS7_type_is_enveloped
+PKCS7_type_is_signedAndEnveloped
+PKCS7_type_is_data
+PKCS7_type_is_digest
+PKCS7_set_detached
+PKCS7_get_detached
+PKCS7_is_detached
+RSA_set_app_data
+RSA_get_app_data
+STACK_OF
+SKM_DEFINE_STACK_OF
+U64
+SSL_set_mtu
+DTLS_set_link_mtu
+DTLS_get_link_min_mtu
+SSL_CTX_set_cert_flags
+SSL_set_cert_flags
+SSL_CTX_clear_cert_flags
+SSL_clear_cert_flags
+SSL_set_app_data
+SSL_get_app_data
+SSL_SESSION_set_app_data
+SSL_SESSION_get_app_data
+SSL_CTX_get_app_data
+SSL_CTX_set_app_data
+SSLeay_add_ssl_algorithms
+DTLSv1_get_timeout
+DTLSv1_handle_timeout
+SSL_num_renegotiations
+SSL_clear_num_renegotiations
+SSL_total_renegotiations
+SSL_CTX_set_dh_auto
+SSL_set_dh_auto
+SSL_get0_certificate_types
+SSL_CTX_set1_client_certificate_types
+SSL_set1_client_certificate_types
+SSL_get0_raw_cipherlist
+SSL_get0_ec_point_formats
+SSL_CTX_need_tmp_RSA
+SSL_CTX_set_tmp_rsa
+SSL_need_tmp_RSA
+SSL_set_tmp_rsa
+SSL_CTX_set_tmp_rsa_callback
+SSL_set_tmp_rsa_callback
+SSL_get_ex_new_index
+SSL_SESSION_get_ex_new_index
+SSL_CTX_get_ex_new_index
+SSL_CTX_set_default_read_ahead
+SSL_cache_hit
+TLS1_get_version
+TLS1_get_client_version
+SSL_set_tlsext_debug_callback
+SSL_set_tlsext_debug_arg
+SSL_get_tlsext_status_exts
+SSL_set_tlsext_status_exts
+SSL_get_tlsext_status_ids
+SSL_set_tlsext_status_ids
+SSL_CTX_get_tlsext_ticket_keys
+SSL_CTX_set_tlsext_ticket_keys
+OSSL_TRACE_CANCEL
+OSSL_TRACE_ENABLED
+OSSL_TRACEV
+OSSL_TRACE
+OSSL_TRACE3
+OSSL_TRACE4
+OSSL_TRACE5
+OSSL_TRACE6
+OSSL_TRACE7
+OSSL_TRACE8
+UI_set_app_data
+UI_get_app_data
+X509_extract_key
+X509_REQ_extract_key
+X509_name_cmp
+X509_STORE_CTX_set_app_data
+X509_STORE_CTX_get_app_data
+X509_LOOKUP_load_file
+X509_LOOKUP_add_dir
+X509V3_conf_err
+X509V3_set_ctx_test
+X509V3_set_ctx_nodb
+EXT_BITSTRING
+EXT_IA5STRING

util/missingssl.txt

@@ -0,0 +1,46 @@
+# A list of libssl functions that are known to be missing documentation as
+# used by the find-doc-nits -v option. The list is as of commit 355b419698.
+ERR_load_SSL_strings
+SRP_Calc_A_param
+SSL_COMP_get_name
+SSL_COMP_set0_compression_methods
+SSL_CONF_CTX_finish
+SSL_CTX_SRP_CTX_free
+SSL_CTX_SRP_CTX_init
+SSL_CTX_get0_certificate
+SSL_CTX_get0_ctlog_store
+SSL_CTX_get0_privatekey
+SSL_CTX_get_ssl_method
+SSL_CTX_set0_ctlog_store
+SSL_CTX_set_client_cert_engine
+SSL_CTX_set_cookie_generate_cb
+SSL_CTX_set_cookie_verify_cb
+SSL_CTX_set_not_resumable_session_callback
+SSL_CTX_set_purpose
+SSL_CTX_set_trust
+SSL_SRP_CTX_free
+SSL_SRP_CTX_init
+SSL_add_dir_cert_subjects_to_stack
+SSL_add_file_cert_subjects_to_stack
+SSL_add_ssl_module
+SSL_certs_clear
+SSL_copy_session_id
+SSL_dup_CA_list
+SSL_get0_dane
+SSL_get_certificate
+SSL_get_current_compression
+SSL_get_current_expansion
+SSL_get_finished
+SSL_get_peer_finished
+SSL_get_privatekey
+SSL_set_SSL_CTX
+SSL_set_debug
+SSL_set_not_resumable_session_callback
+SSL_set_purpose
+SSL_set_session_secret_cb
+SSL_set_session_ticket_ext
+SSL_set_session_ticket_ext_cb
+SSL_set_trust
+SSL_srp_server_param_with_username
+SSL_test_functions
+SSL_trace