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 <Matthias.St.Pierre@ncp-e.com>
(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 b505841832ec6e3a1fa2c0c923766c22b502cde1..3ac65c3952b9240a0e41d469be1de0f6c818973c 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 5c3debb48dced34feb69e68d7101f9e0cf1b9364..452c29509c934fa7d05867c29fe777a011775ea8 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 3c847104327a0e4fc0d445e974b74fa9db4f7302..a610d458d3a68e03e4fb160fc57d5ffd5431ecd9 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 970f6a6b08afe9726238fca82f24e704a7c0fe5e..9cc25b98786fe7efcbbe43498a92a221e67136ee 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 a2fc299482fc06f2a53edeb83a6ee884f253d614..1ded4828374b8bbc4fa5598acace367f53ed598e 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 c503241d16c48dd14d7c333a808e4e70a94a40f9..0af636b69a94f5325b636ccfc75fed0420236961 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
  #include <openssl/err.h>
 
- #if OPENSSL_API_COMPAT < 0x10100000L
  void ERR_load_crypto_strings(void);
  void ERR_free_strings(void);
- #endif
 
  #include <openssl/ssl.h>
 
- #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 8f4d3fcafa4e834b7c1f58c2269ce355a0793d33..ab54a99e262005d8a42a24617526f846c4d2d49c 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
  void ERR_remove_thread_state(void *tid);
- #endif
 
 =head1 DESCRIPTION
 

diff --git a/doc/man3/HMAC.pod b/doc/man3/HMAC.pod
index c480a9c9ebefb018b2a2f73b7f1d4fc12d48faa1..5aed367a4756527827b3ad90f92ce2d7217ab1f0 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 cbf889f2c7114c6fe598e7baad5671fe9cebcce4..2b88ff18435adf3c14ca9e4276c1a9ce40fdc6a4 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 0c086d1291d3f667b67376cf143e704b66442392..bdb5b69f9ffb44c149848ecda9c625116e38c280 100644 (file)
--- 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 <openssl/evp.h>
 
-Deprecated:
+Deprecated since OpenSSL 1.1.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- # 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 b6753fd2ed0b1b0cac0885303226b90d76ed0622..79524d12a9497d074dedbabcde2e68719e48a2a4 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 fca1ad6961debc193f2525c2f5c13161df702760..292d7d59d0a3fa1da2838c43bcfaa4a9ecdfb17c 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 a4c078a4b0bacce5240b8bb99cec048bd5196af9..c4c74e1a8ab42d64e49b96e32e459a8cc1d3ad15 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 1dc8eb149947d94ebff0e825071a226cbff1fd9d..53b6fedcab9a1f2a1baebdb038477cd2b3b40903 100644 (file)
--- 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<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
 
- #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 860bb9958bd2d8b7d86e0b962009fa2e286d2923..c041c1c81900bd493498a4faeeec204fa25c4b80 100755 (executable)
--- 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\([^)]+\)//;