From: Richard Levitte Date: Mon, 3 Dec 2018 09:59:11 +0000 (+0100) Subject: Docs: better deprecation text X-Git-Tag: openssl-3.0.0-alpha1~2852 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=be80b21d2a9c1e0d4fb920ca023e4ec225d878a7 Docs: better deprecation text Expand the text on deprecation to be more descriptive and to refer back to openssl_user_macros(7). Incidently, this required a small change in util/find-doc-nits, to have it skip over any line that isn't part of a block (i.e. that hasn't been indented with at least one space. That makes it skip over deprecation text. Reviewed-by: Matthias St. Pierre (Merged from https://github.com/openssl/openssl/pull/7745) --- diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod index b505841832..3ac65c3952 100644 --- a/doc/man3/BN_generate_prime.pod +++ b/doc/man3/BN_generate_prime.pod @@ -33,9 +33,10 @@ for primality void *BN_GENCB_get_arg(BN_GENCB *cb); -Deprecated: +Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x00908000L BIGNUM *BN_generate_prime(BIGNUM *ret, int num, int safe, BIGNUM *add, BIGNUM *rem, void (*callback)(int, int, void *), void *cb_arg); @@ -46,7 +47,6 @@ Deprecated: int BN_is_prime_fasttest(const BIGNUM *a, int checks, void (*callback)(int, int, void *), BN_CTX *ctx, void *cb_arg, int do_trial_division); - #endif =head1 DESCRIPTION diff --git a/doc/man3/CONF_modules_free.pod b/doc/man3/CONF_modules_free.pod index 5c3debb48d..452c29509c 100644 --- a/doc/man3/CONF_modules_free.pod +++ b/doc/man3/CONF_modules_free.pod @@ -12,11 +12,11 @@ OpenSSL configuration cleanup functions void CONF_modules_finish(void); void CONF_modules_unload(int all); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L void CONF_modules_free(void) - #endif =head1 DESCRIPTION diff --git a/doc/man3/DH_generate_parameters.pod b/doc/man3/DH_generate_parameters.pod index 3c84710432..a610d458d3 100644 --- a/doc/man3/DH_generate_parameters.pod +++ b/doc/man3/DH_generate_parameters.pod @@ -21,12 +21,12 @@ parameters int DH_check_params_ex(const DH *dh); int DH_check_pub_key_ex(const DH *dh, const BIGNUM *pub_key); -Deprecated: +Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x00908000L DH *DH_generate_parameters(int prime_len, int generator, void (*callback)(int, int, void *), void *cb_arg); - #endif =head1 DESCRIPTION diff --git a/doc/man3/DSA_generate_parameters.pod b/doc/man3/DSA_generate_parameters.pod index 970f6a6b08..9cc25b9878 100644 --- a/doc/man3/DSA_generate_parameters.pod +++ b/doc/man3/DSA_generate_parameters.pod @@ -13,13 +13,13 @@ DSA_generate_parameters_ex, DSA_generate_parameters - generate DSA parameters int *counter_ret, unsigned long *h_ret, BN_GENCB *cb); -Deprecated: +Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x00908000L DSA *DSA_generate_parameters(int bits, unsigned char *seed, int seed_len, int *counter_ret, unsigned long *h_ret, void (*callback)(int, int, void *), void *cb_arg); - #endif =head1 DESCRIPTION diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod index a2fc299482..1ded482837 100644 --- a/doc/man3/ENGINE_add.pod +++ b/doc/man3/ENGINE_add.pod @@ -154,11 +154,11 @@ ENGINE_unregister_digests EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id, UI_METHOD *ui_method, void *callback_data); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L void ENGINE_cleanup(void) - #endif =head1 DESCRIPTION diff --git a/doc/man3/ERR_load_crypto_strings.pod b/doc/man3/ERR_load_crypto_strings.pod index c503241d16..0af636b69a 100644 --- a/doc/man3/ERR_load_crypto_strings.pod +++ b/doc/man3/ERR_load_crypto_strings.pod @@ -7,20 +7,18 @@ load and free error strings =head1 SYNOPSIS -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: #include - #if OPENSSL_API_COMPAT < 0x10100000L void ERR_load_crypto_strings(void); void ERR_free_strings(void); - #endif #include - #if OPENSSL_API_COMPAT < 0x10100000L void SSL_load_error_strings(void); - #endif =head1 DESCRIPTION diff --git a/doc/man3/ERR_remove_state.pod b/doc/man3/ERR_remove_state.pod index 8f4d3fcafa..ab54a99e26 100644 --- a/doc/man3/ERR_remove_state.pod +++ b/doc/man3/ERR_remove_state.pod @@ -6,15 +6,17 @@ ERR_remove_thread_state, ERR_remove_state - DEPRECATED =head1 SYNOPSIS -Deprecated: +Deprecated since OpenSSL 1.0.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10000000L void ERR_remove_state(unsigned long tid); - #endif - #if OPENSSL_API_COMPAT < 0x10100000L +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: + void ERR_remove_thread_state(void *tid); - #endif =head1 DESCRIPTION diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod index c480a9c9eb..5aed367a47 100644 --- a/doc/man3/HMAC.pod +++ b/doc/man3/HMAC.pod @@ -40,12 +40,12 @@ HMAC_size size_t HMAC_size(const HMAC_CTX *e); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L int HMAC_Init(HMAC_CTX *ctx, const void *key, int key_len, const EVP_MD *md); - #endif =head1 DESCRIPTION diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod index cbf889f2c7..2b88ff1843 100644 --- a/doc/man3/OBJ_nid2obj.pod +++ b/doc/man3/OBJ_nid2obj.pod @@ -35,11 +35,11 @@ OBJ_dup, OBJ_txt2obj, OBJ_obj2txt, OBJ_create, OBJ_cleanup size_t OBJ_length(const ASN1_OBJECT *obj); const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L void OBJ_cleanup(void) - #endif =head1 DESCRIPTION diff --git a/doc/man3/OpenSSL_add_all_algorithms.pod b/doc/man3/OpenSSL_add_all_algorithms.pod index 0c086d1291..bdb5b69f9f 100644 --- a/doc/man3/OpenSSL_add_all_algorithms.pod +++ b/doc/man3/OpenSSL_add_all_algorithms.pod @@ -9,15 +9,15 @@ add algorithms to internal table #include -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - # if OPENSSL_API_COMPAT < 0x10100000L void OpenSSL_add_all_algorithms(void); void OpenSSL_add_all_ciphers(void); void OpenSSL_add_all_digests(void); void EVP_cleanup(void) -# endif =head1 DESCRIPTION diff --git a/doc/man3/RAND_add.pod b/doc/man3/RAND_add.pod index b6753fd2ed..79524d12a9 100644 --- a/doc/man3/RAND_add.pod +++ b/doc/man3/RAND_add.pod @@ -18,12 +18,12 @@ RAND_keep_random_devices_open void RAND_keep_random_devices_open(int keep); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L int RAND_event(UINT iMsg, WPARAM wParam, LPARAM lParam); void RAND_screen(void); - #endif =head1 DESCRIPTION diff --git a/doc/man3/RAND_bytes.pod b/doc/man3/RAND_bytes.pod index fca1ad6961..292d7d59d0 100644 --- a/doc/man3/RAND_bytes.pod +++ b/doc/man3/RAND_bytes.pod @@ -11,11 +11,11 @@ RAND_bytes, RAND_priv_bytes, RAND_pseudo_bytes - generate random data int RAND_bytes(unsigned char *buf, int num); int RAND_priv_bytes(unsigned char *buf, int num); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L int RAND_pseudo_bytes(unsigned char *buf, int num); - #endif =head1 DESCRIPTION diff --git a/doc/man3/RSA_generate_key.pod b/doc/man3/RSA_generate_key.pod index a4c078a4b0..c4c74e1a8a 100644 --- a/doc/man3/RSA_generate_key.pod +++ b/doc/man3/RSA_generate_key.pod @@ -12,12 +12,12 @@ RSA_generate_multi_prime_key - generate RSA key pair int RSA_generate_key_ex(RSA *rsa, int bits, BIGNUM *e, BN_GENCB *cb); int RSA_generate_multi_prime_key(RSA *rsa, int bits, int primes, BIGNUM *e, BN_GENCB *cb); -Deprecated: +Deprecated since OpenSSL 0.9.8, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x00908000L RSA *RSA_generate_key(int num, unsigned long e, void (*callback)(int, int, void *), void *cb_arg); - #endif =head1 DESCRIPTION diff --git a/doc/man3/SSL_COMP_add_compression_method.pod b/doc/man3/SSL_COMP_add_compression_method.pod index 1dc8eb1499..53b6fedcab 100644 --- a/doc/man3/SSL_COMP_add_compression_method.pod +++ b/doc/man3/SSL_COMP_add_compression_method.pod @@ -15,11 +15,11 @@ SSL_COMP_get0_name, SSL_COMP_get_id, SSL_COMP_free_compression_methods const char *SSL_COMP_get0_name(const SSL_COMP *comp); int SSL_COMP_get_id(const SSL_COMP *comp); -Deprecated: +Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining +B with a suitable version value, see +L: - #if OPENSSL_API_COMPAT < 0x10100000L void SSL_COMP_free_compression_methods(void) - #endif =head1 DESCRIPTION diff --git a/util/find-doc-nits b/util/find-doc-nits index 860bb9958b..c041c1c819 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -96,6 +96,7 @@ sub name_synopsis() return unless $contents =~ /=head1 SYNOPSIS(.*)=head1 DESCRIPTION/ms; my $syn = $1; foreach my $line ( split /\n+/, $syn ) { + next unless $line =~ /^\s/; my $sym; $line =~ s/STACK_OF\([^)]+\)/int/g; $line =~ s/__declspec\([^)]+\)//;