Commit b5283535 authored by Matt Caswell's avatar Matt Caswell
Browse files

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: default avatarRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9094)
parent 51583cb8

Configurations/unix-Makefile.tmpl

+1 −1
Original line number Diff line number Diff line
@@ -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

+52 −11
Original line number Diff line number Diff line
@@ -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();

}

util/missingcrypto.txt

0 → 100644
+1499 −0

File added.

Preview size limit exceeded, changes collapsed.

util/missingmacro.txt

0 → 100644
+217 −0
Original line number Diff line number Diff line 
# 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 → 100644
+46 −0
Original line number Diff line number Diff line 
# 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