Docs: better deprecation text
authorRichard Levitte <levitte@openssl.org>
Mon, 3 Dec 2018 09:59:11 +0000 (10:59 +0100)
committerRichard Levitte <levitte@openssl.org>
Mon, 3 Dec 2018 11:32:31 +0000 (12:32 +0100)
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)

15 files changed:
doc/man3/BN_generate_prime.pod
doc/man3/CONF_modules_free.pod
doc/man3/DH_generate_parameters.pod
doc/man3/DSA_generate_parameters.pod
doc/man3/ENGINE_add.pod
doc/man3/ERR_load_crypto_strings.pod
doc/man3/ERR_remove_state.pod
doc/man3/HMAC.pod
doc/man3/OBJ_nid2obj.pod
doc/man3/OpenSSL_add_all_algorithms.pod
doc/man3/RAND_add.pod
doc/man3/RAND_bytes.pod
doc/man3/RSA_generate_key.pod
doc/man3/SSL_COMP_add_compression_method.pod
util/find-doc-nits

index b505841..3ac65c3 100644 (file)
@@ -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
 
index 5c3debb..452c295 100644 (file)
@@ -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
 
index 3c84710..a610d45 100644 (file)
@@ -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
 
index 970f6a6..9cc25b9 100644 (file)
@@ -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
 
index a2fc299..1ded482 100644 (file)
@@ -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
 
index c503241..0af636b 100644 (file)
@@ -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
 
index 8f4d3fc..ab54a99 100644 (file)
@@ -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
 
index c480a9c..5aed367 100644 (file)
@@ -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
 
index cbf889f..2b88ff1 100644 (file)
@@ -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
 
index 0c086d1..bdb5b69 100644 (file)
@@ -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
 
index b6753fd..79524d1 100644 (file)
@@ -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
 
index fca1ad6..292d7d5 100644 (file)
@@ -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
 
index a4c078a..c4c74e1 100644 (file)
@@ -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
 
index 1dc8eb1..53b6fed 100644 (file)
@@ -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
 
index 860bb99..c041c1c 100755 (executable)
@@ -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\([^)]+\)//;