Simplify and clarify doc/internal/man7/deprecation.pod

doc/internal/man7/deprecation.pod was unclear in some areas, and
included general documentation that has no place there.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13240)

2 files changed, 117 insertions, 148 deletions

diff --git a/doc/internal/man3/OSSL_DEPRECATED.pod b/doc/internal/man3/OSSL_DEPRECATED.pod
new file mode 100644
index 0000000000..8370d60f18
--- /dev/null
+++ b/doc/internal/man3/OSSL_DEPRECATED.pod
@@ -0,0 +1,54 @@
+=pod
+
+=head1 NAME
+
+OSSL_DEPRECATED, OSSL_DEPRECATED_FOR - General deprecation macros
+
+=head1 SYNOPSIS
+
+ #include <openssl/macros.h>
+
+ #define OSSL_DEPRECATED(since)
+ #define OSSL_DEPRECATED_FOR(since, msg)
+
+=head1 DESCRIPTION
+
+OSSL_DEPRECATED() implements the deprecated attribute if the compiler
+supports it, otherwise it expands to nothing.  It takes one argument
+I<since> that should be set to the OpenSSL version where the symbol was
+deprecated, and will be displayed with the deprecation warning message,
+for compilers that support user specified deprecation messages.
+
+OSSL_DEPRECATED_FOR() does the same as OSSL_DEPRECATED(), but also takes a
+second argument I<msg>, which is an additional text messages to be displayed
+with the deprecation warning along with the OpenSSL version number, for
+compilers that support user specified deprecation messages.
+
+These macros are used to define the version specific deprecation macros
+described in L<deprecation(7)>.
+
+=begin comment
+
+[RETURN VALUES isn't relevant for these macros, but find-doc-nits demands
+the presence of this section]
+
+=head1 RETURN VALUES
+
+[podchecker doesn't like empty sections]
+
+=end comment
+
+=head1 SEE ALSO
+
+L<deprecation(7)>
+
+=head1 COPYRIGHT
+
+Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/internal/man7/deprecation.pod b/doc/internal/man7/deprecation.pod
index e55da1ffe4..15e1c7aef1 100644
--- a/doc/internal/man7/deprecation.pod
+++ b/doc/internal/man7/deprecation.pod
@@ -2,185 +2,98 @@
 
 =head1 NAME
 
-deprecation - Macros used for deprecating symbols and simulate removal
-
-=head1 SYNOPSIS
-
- #include <openssl/macros.h>
-
- OSSL_DEPRECATED(since)
- OSSL_DEPRECATED_FOR(since, msg)
-
- OPENSSL_NO_DEPRECATED_3_0
- OSSL_DEPRECATEDIN_3_0
- OSSL_DEPRECATEDIN_3_0_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_1_1
- OSSL_DEPRECATEDIN_1_1_1
- OSSL_DEPRECATEDIN_1_1_1_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_1_0
- OSSL_DEPRECATEDIN_1_1_0
- OSSL_DEPRECATEDIN_1_1_0_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_0_2
- OSSL_DEPRECATEDIN_1_0_2
- OSSL_DEPRECATEDIN_1_0_2_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_0_1
- OSSL_DEPRECATEDIN_1_0_1
- OSSL_DEPRECATEDIN_1_0_1_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_1_0_0
- OSSL_DEPRECATEDIN_1_0_0
- OSSL_DEPRECATEDIN_1_0_0_FOR(msg)
-
- OPENSSL_NO_DEPRECATED_0_9_8
- OSSL_DEPRECATEDIN_0_9_8
- OSSL_DEPRECATEDIN_0_9_8_FOR(msg)
+OPENSSL_NO_DEPRECATED_3_0, OSSL_DEPRECATEDIN_3_0,
+OPENSSL_NO_DEPRECATED_1_1_1, OSSL_DEPRECATEDIN_1_1_1,
+OPENSSL_NO_DEPRECATED_1_1_0, OSSL_DEPRECATEDIN_1_1_0,
+OPENSSL_NO_DEPRECATED_1_0_2, OSSL_DEPRECATEDIN_1_0_2,
+OPENSSL_NO_DEPRECATED_1_0_1, OSSL_DEPRECATEDIN_1_0_1,
+OPENSSL_NO_DEPRECATED_1_0_0, OSSL_DEPRECATEDIN_1_0_0,
+OPENSSL_NO_DEPRECATED_0_9_8, OSSL_DEPRECATEDIN_0_9_8,
+deprecation - How to do deprecation
 
 =head1 DESCRIPTION
 
 Deprecation of a symbol is adding an attribute to the declaration of that
 symbol (function, type, variable, but we currently only do that for
-functions in our F<< <openssl/*.h> >> header files).
+functions in our public header files, F<< <openssl/*.h> >>).
 
 Removal of a symbol is not the same thing as deprecation, as it actually
-removes the symbol from public view.
+explicitly removes the symbol from public view.
 
 OpenSSL configuration supports deprecation as well as simulating removal of
-symbols from public view, and also supports doing this in terms of a
-specified OpenSSL version.
+symbols from public view (with the configuration option `no-deprecated`, or
+if the user chooses to do so, with L<OPENSSL_NO_DEPRECATED(7)>), and also
+supports doing this in terms of a specified OpenSSL version (with the
+configuration option `--api`, or if the user chooses to do so, with
+L<OPENSSL_API_COMPAT(7)>).
 
-Deprecation is done using attribute macros having names starting with
-B<OSSL_DEPRECATED>, used with any declaration it applies to.
+Deprecation is done using attribute macros named
+B<OSSL_DEPRECATEDIN_I<version>>, used with any declaration it applies to.
 
-Simulating removal is done with guard macros having names starting with
-L<OPENSSL_NO_DEPRECATED(7)>.
+Simulating removal is done with C<#ifndef> preprocessor guards using macros
+named B<OPENSSL_NO_DEPRECATED_I<version>>.
 
-The implementation of a deprecated symbol is kept for two reasons:
+B<OSSL_DEPRECATEDIN_I<version>> and B<OPENSSL_NO_DEPRECATED_I<version>> are
+defined in F<< <openssl/macros.h> >>.
 
-=over 4
-
-=item Kept as legacy for the deprecation period
-
-It's implemented only to have it available as long as the symbol isn't
-removed entirely (be it by explicitly removing it when it's judged that it
-has been deprecated long enough, or because the removal is simulated).
-These need to be guarded appropriately, as shown in the L</Implementations
-kept as legacy>.
-
-=item Kept for internal purposes
-
-The implementation doesn't need to change or be guarded.  However, it's
-necessary to ensure that the declaration remains available for the
-translation unit where the implementation is located, even when the symbol
-is publicly unavailable through simulated removal.  That's done by including
-an internal header file very early in the translation unit.  See
-L</Implementations kept for internal purposes>.
+In those macro names, B<I<version>> corresponds to the OpenSSL release since
+which the deprecation applies, with underscores instead of periods.  Because
+of the change in version scheme with OpenSSL 3.0, the B<I<version>> for
+versions before that are three numbers (such as C<1_1_0>), while they are
+two numbers (such as C<3_0>) from 3.0 and on.
 
-In a future cleanup, the declaration should be explicitly moved to an
-internal header file, with the deprecation attribute removed, and the
-translation unit should adjust its header inclusions accordingly.
+The implementation of a deprecated symbol is kept for one of two reasons:
 
-=back
-
-=head2 General macros
-
-I<Note: none of these macros should be used directly, please use the version
-specific macros instead>
-
-OSSL_DEPRECATED() implements the deprecated attribute if the compiler
-supports it, otherwise it expands to nothing.  It takes one argument
-I<since> that should be set to the OpenSSL version where the symbol was
-deprecated, and will be displayed with the deprecation warning message,
-for compilers that support user specified deprecation messages.
+=over 4
 
-OSSL_DEPRECATED_FOR() does the same as OSSL_DEPRECATED(), but also takes a
-second argument I<msg>, which is an additional text messages to be displayed
-with the deprecation warning along with the OpenSSL version number, for
-compilers that support user specified deprecation messages.
+=item Planned to be removed
 
-B<OPENSSL_NO_DEPRECATED> is a macro that's generated by OpenSSL
-configuration in response to the C<no-deprecated> configuration option.
-This macro suppresses the definition of deprecated symbols.
+The symbol and its implementation are planned to be removed some time in the
+future, but needs to remain available until that time.
+Such an implementation needs to be guarded appropriately, as shown in
+L</Implementations to be removed> below.
 
-=head2 Version specific macros
+=item Planned to remain internally
 
-OSSL_DEPRECATEDIN_I<major>_I<minor>() macros that are defined to
-OSSL_DEPRECATED() with that version number as I<since>, for any version up
-to and including the one expressed with L<OPENSSL_API_COMPAT(7)>.  For any
-known version above the version expressed with L<OPENSSL_API_COMPAT(7)>,
-The are defined to nothing.
+The symbol is planned to be removed from public view, but will otherwise
+remain for internal purposes.  In this case, the implementation doesn't need
+to change or be guarded.
 
-OSSL_DEPRECATEDIN_I<major>_I<minor>_FOR() macros that are defined to
-OSSL_DEPRECATED() with that version number as I<since>, under the same
-conditions as OSSL_DEPRECATEDIN_I<major>_I<minor>().
+However, it's necessary to ensure that the declaration remains available for
+the translation unit where the symbol is used or implemented, even when the
+symbol is publicly unavailable through simulated removal.  That's done by
+including an internal header file very early in the affected translation
+units.  See L</Implementations to remain internally> below.
 
-B<OPENSSL_NO_DEPRECATED_I<major>_I<minor>> macros should be used as
-guards around declarations that will eventually disappear from the public
-header files (F<< <openssl/*.h> >>).
+In the future, when the deprecated declaration is to actually be removed
+from public view, it should be moved to an internal header file, with the
+deprecation attribute removed, and the translation units that implement or
+use that symbol should adjust their header inclusions accordingly.
 
-Any set of symbols deprecated with a B<OSSL_DEPRECATEDIN_I<major>_I<minor>>
-attribute macro B<must> be wrapped with a guard using the corresponding
-B<OPENSSL_NO_DEPRECATED_I<major>_I<minor>> macro, see L</Header files>
-example below.  This not only affects what the user of the header file will
-have available, it's also used to determine the conditions for exporting the
-symbol in the shared libraries.
+=back
 
 =head1 EXAMPLES
 
 =head2 Header files
 
-In public header files (F<< <openssl/*.h> >>), a deprecated symbol will
-always be wrapped with a negative test of the guard:
+In public header files (F<< <openssl/*.h> >>), this is what a deprecation is
+expected to look like, including the preprocessor wrapping for simulated
+removal:
 
- # ifndef OPENSSL_NO_DEPRECATED_1_1_0
- /* ... */
- OSSL_DEPRECATEDIN_1_1_0 __owur int
- HMAC_Init(HMAC_CTX *ctx, const void *key, int len, const EVP_MD *md);
+ # ifndef OPENSSL_NO_DEPRECATED_3_0
  /* ... */
- # endif
-
-=head2 Implementations of deprecated symbols
-
-At least for the period of deprecation for any symbol, its implementation
-needs to be kept, and for symbols that are kept internally, for longer than
-that.  There are two things to deal with:
-
-=over 4
-
-=item Deprecation warnings
-
-To remedy deprecation warnings, simply define the macro
-B<OPENSSL_SUPPRESS_DEPRECATED> at the beginning of the translation unit.
-
-=item Simulated removal
 
-=over 4
-
-=item *
-
-For symbols that are kept as legacy, the simulated removal should be
-enforced, by guarding the implementation the exact same way as the
-declaration in the public header file.
-
-=item *
-
-For symbols that are planned to be kept internally beyond their deprecation
-period, the translation units that implement them must ensure that the
-public header files they include to that declare the symbols don't remove
-the symbols, even when removal is otherwise simulated.
+ OSSL_DEPRECATEDIN_3_0 RSA *RSA_new_method(ENGINE *engine);
 
-=back
-
-=back
+ /* ... */
+ # endif
 
-=head3 Implementations kept as legacy
+=head2 Implementations to be removed
 
-For a deprecated function that we plan to simply remove, for example
+For a deprecated function that we plan to remove in the future, for example
 RSA_new_method(), the following should be found very early (before including
-any OpenSSL header file) in the translation unit:
+any OpenSSL header file) in the translation unit that implements it and in
+any translation unit that uses it:
 
  /*
   * Suppress deprecation warnings for RSA low level implementations that are
@@ -188,7 +101,8 @@ any OpenSSL header file) in the translation unit:
   */
  #define OPENSSL_SUPPRESS_DEPRECATED
 
-And RSA_new_method() implementation itself should be guarded like this:
+The RSA_new_method() implementation itself must be guarded the same way as
+its declaration in the public header file is:
 
  #ifndef OPENSSL_NO_DEPRECATED_3_0
  RSA *RSA_new_method(ENGINE *engine)
@@ -197,11 +111,12 @@ And RSA_new_method() implementation itself should be guarded like this:
  }
  #endif
 
-=head3 Implementations kept for internal purposes
+=head2 Implementations to remain internally
 
 For a deprecated function that we plan to keep internally, for example
 RSA_size(), the following should be found very early (before including any
-other OpenSSL header file) in the translation unit:
+other OpenSSL header file) in the translation unit that implements it and in
+any translation unit that uses it:
 
  /*
   * RSA low level APIs are deprecated for public use, but are kept for