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

Enable find-doc-nits to find undocumented symbols since 1.1.1 



A previous commit added the ability to find newly undocumented symbols.
We extend this capability to check anything that was newly added since
1.1.1 which is undocumented. A new option -o is added to find-doc-nits
to amend the behaviour of -v or -e to check symbols that were newly
added since the release of 1.1.1.

Reviewed-by: default avatarRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9094)
parent 8caab503

util/find-doc-nits

+20 −6
Original line number Diff line number Diff line
@@ -22,6 +22,7 @@ use OpenSSL::Util::Pod; 
our($opt_d);

our($opt_e);

our($opt_s);

our($opt_o);

our($opt_h);

our($opt_l);

our($opt_n);
@@ -37,6 +38,7 @@ 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

    -o Causes -e/-v to count symbols added since 1.1.1 as new (implies -v)

    -l Print bogus links

    -n Print nits in POD pages

    -p Warn if non-public name documented (implies -n)
@@ -318,8 +320,13 @@ sub checkmacros() 
{

    my $count = 0;

    my %seen;

    my @missing;



    my @missing = loadmissing('util/missingmacro.txt') if ($opt_v);

    if ($opt_o) {

        @missing = loadmissing('util/missingmacro111.txt');

    } elsif ($opt_v) {

        @missing = loadmissing('util/missingmacro.txt');

    }



    print "# Checking macros (approximate)\n" if !$opt_s;

    foreach my $f ( glob('include/openssl/*.h') ) {
@@ -538,19 +545,21 @@ sub checkflags() { 
    return $ok;

}



getopts('cdeslnphuv');

getopts('cdesolnphuv');



&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;

$opt_v = 1 if $opt_o || $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 -[cdelnpuv] flags.\n"

# We only need to check c, l, n, u and v.

# Options d, e, s, o and p imply one of the above.

die "Need one of -[cdesolnpuv] flags.\n"

    unless $opt_c or $opt_l or $opt_n or $opt_u or $opt_v;



if ( $opt_c ) {
@@ -617,8 +626,13 @@ if ( $opt_u || $opt_v) { 
    foreach ( keys %temp ) {

        $docced{$_} = $temp{$_};

    }

    if ($opt_o) {

        &printem('crypto', 'util/libcrypto.num', 'util/missingcrypto111.txt');

        &printem('ssl', 'util/libssl.num', 'util/missingssl111.txt');

    } else {

        &printem('crypto', 'util/libcrypto.num', 'util/missingcrypto.txt');

        &printem('ssl', 'util/libssl.num', 'util/missingssl.txt');

    }

    &checkmacros();

}

util/missingcrypto111.txt

0 → 100644
+1610 −0

File added.

Preview size limit exceeded, changes collapsed.

util/missingmacro111.txt

0 → 100644
+232 −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 -o option. The list is as of commit 1708e3e85b (the release

# of 1.1.1).

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

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

EVP_PKEY_CTX_set_dh_paramgen_subprime_len

EVP_PKEY_CTX_set_dh_paramgen_type

EVP_PKEY_CTX_set_dh_rfc5114

EVP_PKEY_CTX_set_dhx_rfc5114

EVP_PKEY_CTX_set_dh_kdf_type

EVP_PKEY_CTX_get_dh_kdf_type

EVP_PKEY_CTX_set0_dh_kdf_oid

EVP_PKEY_CTX_get0_dh_kdf_oid

EVP_PKEY_CTX_set_dh_kdf_md

EVP_PKEY_CTX_get_dh_kdf_md

EVP_PKEY_CTX_set_dh_kdf_outlen

EVP_PKEY_CTX_get_dh_kdf_outlen

EVP_PKEY_CTX_set0_dh_kdf_ukm

EVP_PKEY_CTX_get0_dh_kdf_ukm

DSA_is_prime

OPENSSL_GLOBAL_REF

OPENSSL_GLOBAL_REF

ECParameters_dup

EVP_PKEY_CTX_set_ecdh_cofactor_mode

EVP_PKEY_CTX_get_ecdh_cofactor_mode

EVP_PKEY_CTX_set_ecdh_kdf_type

EVP_PKEY_CTX_get_ecdh_kdf_type

EVP_PKEY_CTX_set_ecdh_kdf_md

EVP_PKEY_CTX_get_ecdh_kdf_md

EVP_PKEY_CTX_set_ecdh_kdf_outlen

EVP_PKEY_CTX_get_ecdh_kdf_outlen

EVP_PKEY_CTX_set0_ecdh_kdf_ukm

EVP_PKEY_CTX_get0_ecdh_kdf_ukm

ENGINE_load_openssl

ENGINE_load_dynamic

ENGINE_load_padlock

ENGINE_load_capi

ENGINE_load_afalg

ENGINE_load_cryptodev

ENGINE_load_rdrand

EVP_PKEY_assign_SIPHASH

EVP_PKEY_assign_POLY1305

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

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

EVP_PKEY_CTX_get_rsa_padding

EVP_PKEY_CTX_get_rsa_pss_saltlen

EVP_PKEY_CTX_set_rsa_keygen_primes

EVP_PKEY_CTX_set_rsa_mgf1_md

EVP_PKEY_CTX_set_rsa_oaep_md

EVP_PKEY_CTX_get_rsa_mgf1_md

EVP_PKEY_CTX_get_rsa_oaep_md

EVP_PKEY_CTX_set0_rsa_oaep_label

EVP_PKEY_CTX_get0_rsa_oaep_label

RSA_set_app_data

RSA_get_app_data

STACK_OF

SKM_DEFINE_STACK_OF

U64

U64

U64

SSL_set_mtu

DTLS_set_link_mtu

DTLS_get_link_min_mtu

SSL_heartbeat

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_tmp_ecdh

SSL_CTX_set_dh_auto

SSL_set_dh_auto

SSL_set_tmp_ecdh

SSL_CTX_get_extra_chain_certs

SSL_CTX_get_extra_chain_certs_only

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_ecdh_auto

SSL_set_ecdh_auto

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

SSL_get_dtlsext_heartbeat_pending

SSL_set_dtlsext_heartbeat_no_requests

SSL_get_tlsext_heartbeat_pending

SSL_set_tlsext_heartbeat_no_requests

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/missingssl111.txt

0 → 100644
+60 −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 -o option. The list is as of commit 1708e3e85b

# (the release of 1.1.1).

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_srp_cb_arg

SSL_CTX_set_srp_client_pwd_callback

SSL_CTX_set_srp_password

SSL_CTX_set_srp_strength

SSL_CTX_set_srp_username

SSL_CTX_set_srp_username_callback

SSL_CTX_set_srp_verify_param_callback

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_get_srp_N

SSL_get_srp_g

SSL_get_srp_userinfo

SSL_get_srp_username

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_srp_server_param

SSL_set_srp_server_param_pw

SSL_set_trust

SSL_srp_server_param_with_username

SSL_test_functions

SSL_trace