More doc cleanup

Add missing entries to NAME section
Add SYNOPSIS lines, remove old NAME entries
Update find-doc-nits; better regexp's for parsing SYNOPSIS sections.
Rename a couple of files to have an API name.
Remove RSA_private_decrypt; it was duplicate content
Update for recent doc additions

Reviewed-by: Matt Caswell <matt@openssl.org>

74 files changed, 377 insertions, 266 deletions

diff --git a/doc/crypto/ASN1_STRING_length.pod b/doc/crypto/ASN1_STRING_length.pod
index 78513f8a89..a51d984454 100644
--- a/doc/crypto/ASN1_STRING_length.pod
+++ b/doc/crypto/ASN1_STRING_length.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
-ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 -
+ASN1_STRING_type, ASN1_STRING_data, ASN1_STRING_to_UTF8 -
 ASN1_STRING utility functions
 
 =head1 SYNOPSIS
diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod
index b5139a34a9..20bc1ad2aa 100644
--- a/doc/crypto/ASYNC_start_job.pod
+++ b/doc/crypto/ASYNC_start_job.pod
@@ -2,8 +2,8 @@
 
 =head1 NAME
 
+ASYNC_get_wait_ctx,
 ASYNC_init_thread, ASYNC_cleanup_thread, ASYNC_start_job, ASYNC_pause_job,
-ASYNC_in_job, ASYNC_get_wait_fd, ASYNC_set_wait_fd, ASYNC_clear_wait_fd,
 ASYNC_get_current_job, ASYNC_block_pause, ASYNC_unblock_pause, ASYNC_is_capable
 - asynchronous job management functions
 
diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod
index 68811c3c93..286a39c9ed 100644
--- a/doc/crypto/BIO_f_buffer.pod
+++ b/doc/crypto/BIO_f_buffer.pod
@@ -2,6 +2,11 @@
 
 =head1 NAME
 
+BIO_get_buffer_num_lines,
+BIO_set_read_buffer_size,
+BIO_set_write_buffer_size,
+BIO_set_buffer_size,
+BIO_set_buffer_read_data,
 BIO_f_buffer - buffering BIO
 
 =head1 SYNOPSIS
diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod
index 4c9da6a2ca..4007130150 100644
--- a/doc/crypto/BIO_f_ssl.pod
+++ b/doc/crypto/BIO_f_ssl.pod
@@ -2,7 +2,9 @@
 
 =head1 NAME
 
-BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode, BIO_set_ssl_renegotiate_bytes,
+BIO_do_handshake,
+BIO_f_ssl, BIO_set_ssl, BIO_get_ssl, BIO_set_ssl_mode,
+BIO_set_ssl_renegotiate_bytes,
 BIO_get_num_renegotiates, BIO_set_ssl_renegotiate_timeout, BIO_new_ssl,
 BIO_new_ssl_connect, BIO_new_buffer_ssl_connect, BIO_ssl_copy_session_id,
 BIO_ssl_shutdown - SSL BIO
diff --git a/doc/crypto/BIO_find_type.pod b/doc/crypto/BIO_find_type.pod
index c5029837b0..f03071ad9b 100644
--- a/doc/crypto/BIO_find_type.pod
+++ b/doc/crypto/BIO_find_type.pod
@@ -2,6 +2,12 @@
 
 =head1 NAME
 
+BIO_TYPE_NONE, BIO_TYPE_MEM, BIO_TYPE_FILE, BIO_TYPE_FD, BIO_TYPE_SOCKET,
+BIO_TYPE_NULL, BIO_TYPE_SSL, BIO_TYPE_MD, BIO_TYPE_BUFFER, BIO_TYPE_CIPHER,
+BIO_TYPE_BASE64, BIO_TYPE_CONNECT, BIO_TYPE_ACCEPT, BIO_TYPE_PROXY_CLIENT,
+BIO_TYPE_PROXY_SERVER, BIO_TYPE_NBIO_TEST, BIO_TYPE_NULL_FILTER,
+BIO_TYPE_BER, BIO_TYPE_BIO, BIO_TYPE_DESCRIPTOR, BIO_TYPE_FILTER,
+BIO_TYPE_SOURCE_SINK,
 BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
 
 =head1 SYNOPSIS
diff --git a/doc/crypto/BIO_get_ex_new_index.pod b/doc/crypto/BIO_get_ex_new_index.pod
index 21e5bb76ab..3e24f10bc3 100644
--- a/doc/crypto/BIO_get_ex_new_index.pod
+++ b/doc/crypto/BIO_get_ex_new_index.pod
@@ -15,28 +15,38 @@ ECDSA_get_ex_new_index, ECDSA_set_ex_data, ECDSA_get_ex_data,
 RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data
 - application-specific data
 
-=head1 SYNOPSIS
+=for comment generic
 
-The synopsis below is for the X509 structure, but is the same for all
-crypto structures:
+=head1 SYNOPSIS
 
  #include <openssl/x509.h>
 
- int X509_get_ex_new_index(long argl, void *argp,
+ int TYPE_get_ex_new_index(long argl, void *argp,
                 CRYPTO_EX_new *new_func,
                 CRYPTO_EX_dup *dup_func,
                 CRYPTO_EX_free *free_func);
 
- int X509_set_ex_data(X509 *d, int idx, void *arg);
+ int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
 
- void *X509_get_ex_data(X509 *d, int idx);
+ void *TYPE_get_ex_data(TYPE *d, int idx);
 
 =head1 DESCRIPTION
 
-These functions handle application-specific data for OpenSSL crypto
+In the description here, I<TYPE> is used a placeholder
+for any of the OpenSSL datatypes listed in
+L<CRYPTO_get_ex_new_index(3)>.
+
+These functions handle application-specific data for OpenSSL data
 structures.
 
-For details, see L<CRYPTO_get_ex_new_index(3)>.
+TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
+with the correct B<index> value.
+
+TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
+an offset into the opaque exdata part of the TYPE object.
+
+TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with an
+an offset into the opaque exdata part of the TYPE object.
 
 =head1 SEE ALSO
 
diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod
index ad7bfaac4b..a9259ab217 100644
--- a/doc/crypto/BIO_s_accept.pod
+++ b/doc/crypto/BIO_s_accept.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+BIO_BIND_NORMAL, BIO_BIND_REUSEADDR_IF_UNUSED, BIO_BIND_REUSEADDR,
 BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
 BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
 BIO_get_bind_mode, BIO_do_accept - accept BIO
diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod
index d97d5899a5..29192a6cf0 100644
--- a/doc/crypto/BIO_s_connect.pod
+++ b/doc/crypto/BIO_s_connect.pod
@@ -2,9 +2,10 @@
 
 =head1 NAME
 
+BIO_set_conn_address, BIO_get_conn_address,
 BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
-BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
-BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
+BIO_get_conn_hostname,
+BIO_get_conn_port,
 BIO_set_nbio, BIO_do_connect - connect BIO
 
 =head1 SYNOPSIS
diff --git a/doc/crypto/BIO_s_mem.pod b/doc/crypto/BIO_s_mem.pod
index 56d10bd8dd..afde930906 100644
--- a/doc/crypto/BIO_s_mem.pod
+++ b/doc/crypto/BIO_s_mem.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+BIO_s_secmem,
 BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
 BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
 
diff --git a/doc/crypto/BIO_s_socket.pod b/doc/crypto/BIO_s_socket.pod
index 88aaa88c49..ad0574aee6 100644
--- a/doc/crypto/BIO_s_socket.pod
+++ b/doc/crypto/BIO_s_socket.pod
@@ -10,9 +10,6 @@ BIO_s_socket, BIO_new_socket - socket BIO
 
  const BIO_METHOD *BIO_s_socket(void);
 
- long BIO_set_fd(BIO *b, int fd, long close_flag);
- long BIO_get_fd(BIO *b, int *c);
-
  BIO *BIO_new_socket(int sock, int close_flag);
 
 =head1 DESCRIPTION
@@ -26,12 +23,6 @@ BIO_puts() is supported but BIO_gets() is not.
 If the close flag is set then the socket is shut down and closed
 when the BIO is freed.
 
-BIO_set_fd() sets the socket of BIO B<b> to B<fd> and the close
-flag to B<close_flag>.
-
-BIO_get_fd() places the socket in B<c> if it is not NULL, it also
-returns the socket. If B<c> is not NULL it should be of type (int *).
-
 BIO_new_socket() returns a socket BIO using B<sock> and B<close_flag>.
 
 =head1 NOTES
@@ -44,17 +35,10 @@ platforms sockets are not file descriptors and use distinct I/O routines,
 Windows is one such platform. Any code mixing the two will not work on
 all platforms.
 
-BIO_set_fd() and BIO_get_fd() are macros.
-
 =head1 RETURN VALUES
 
 BIO_s_socket() returns the socket BIO method.
 
-BIO_set_fd() always returns 1.
-
-BIO_get_fd() returns the socket or -1 if the BIO has not been
-initialized.
-
 BIO_new_socket() returns the newly allocated BIO or NULL is an error
 occurred.
 
diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod
index fc728ff9f2..2a6485af9a 100644
--- a/doc/crypto/BIO_should_retry.pod
+++ b/doc/crypto/BIO_should_retry.pod
@@ -2,6 +2,8 @@
 
 =head1 NAME
 
+BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL, BIO_FLAGS_RWS,
+BIO_FLAGS_SHOULD_RETRY,
 BIO_should_read, BIO_should_write,
 BIO_should_io_special, BIO_retry_type, BIO_should_retry,
 BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod
index f2edd49a97..ca54590517 100644
--- a/doc/crypto/BN_CTX_new.pod
+++ b/doc/crypto/BN_CTX_new.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-BN_CTX_new, BN_CTX_secure_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
+BN_CTX_new, BN_CTX_secure_new, BN_CTX_free - allocate and free BN_CTX structures
 
 =head1 SYNOPSIS
 
diff --git a/doc/crypto/BN_bn2bin.pod b/doc/crypto/BN_bn2bin.pod
index b0a8b50d5e..14b152e430 100644
--- a/doc/crypto/BN_bn2bin.pod
+++ b/doc/crypto/BN_bn2bin.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+BN_bn2binpad,
 BN_bn2bin, BN_bin2bn, BN_bn2lebinpad, BN_lebin2bn, BN_bn2hex, BN_bn2dec,
 BN_hex2bn, BN_dec2bn, BN_print, BN_print_fp, BN_bn2mpi,
 BN_mpi2bn - format conversions
diff --git a/doc/crypto/BN_mod_mul_montgomery.pod b/doc/crypto/BN_mod_mul_montgomery.pod
index 152185f6f2..bf1ef343cd 100644
--- a/doc/crypto/BN_mod_mul_montgomery.pod
+++ b/doc/crypto/BN_mod_mul_montgomery.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-BN_mod_mul_montgomery, BN_MONT_CTX_new, BN_MONT_CTX_init,
+BN_mod_mul_montgomery, BN_MONT_CTX_new,
 BN_MONT_CTX_free, BN_MONT_CTX_set, BN_MONT_CTX_copy,
 BN_from_montgomery, BN_to_montgomery - Montgomery multiplication
 
@@ -69,26 +69,6 @@ The error codes can be obtained by L<ERR_get_error(3)>.
 The inputs must be reduced modulo B<m>, otherwise the result will be
 outside the expected range.
 
-=head1 REMOVED FUNCTIONALITY
-
- void BN_MONT_CTX_init(BN_MONT_CTX *c);
-
-BN_MONT_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to
-initialize an existing uninitialized B<BN_MONT_CTX>. Typically this would be
-done as follows:
-
- BN_MONT_CTX ctx;
- BN_MONT_CTX_init(&ctx);
-
-Instead applications should create a BN_MONT_CTX structure using
-BN_MONT_CTX_new:
-
- BN_MONT_CTX *ctx;
- ctx = BN_MONT_CTX_new();
- if(!ctx) /* handle error */
- ...
- BN_MONT_CTX_free(ctx);
-
 =head1 SEE ALSO
 
 L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
diff --git a/doc/crypto/BN_mod_mul_reciprocal.pod b/doc/crypto/BN_mod_mul_reciprocal.pod
index 86fb486385..23832b3b6c 100644
--- a/doc/crypto/BN_mod_mul_reciprocal.pod
+++ b/doc/crypto/BN_mod_mul_reciprocal.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-BN_mod_mul_reciprocal,  BN_div_recp, BN_RECP_CTX_new, BN_RECP_CTX_init,
+BN_mod_mul_reciprocal,  BN_div_recp, BN_RECP_CTX_new,
 BN_RECP_CTX_free, BN_RECP_CTX_set - modular multiplication using
 reciprocal
 
@@ -30,7 +30,6 @@ using B<recp>=1/B<m>, which is set as described below.  B<ctx> is a
 previously allocated B<BN_CTX> used for temporary variables.
 
 BN_RECP_CTX_new() allocates and initializes a B<BN_RECP> structure.
-BN_RECP_CTX_init() initializes an existing uninitialized B<BN_RECP>.
 
 BN_RECP_CTX_free() frees the components of the B<BN_RECP>, and, if it
 was created by BN_RECP_CTX_new(), also the structure itself.
@@ -51,31 +50,11 @@ The B<BN_RECP_CTX> structure cannot be shared between threads.
 BN_RECP_CTX_new() returns the newly allocated B<BN_RECP_CTX>, and NULL
 on error.
 
-BN_RECP_CTX_init() and BN_RECP_CTX_free() have no return values.
+BN_RECP_CTX_free() has no return value.
 
 For the other functions, 1 is returned for success, 0 on error.
 The error codes can be obtained by L<ERR_get_error(3)>.
 
-=head1 REMOVED FUNCTIONALITY
-
- void BN_RECP_CTX_init(BN_RECP_CTX *recp);
-
-BN_RECP_CTX_init() is no longer available as of OpenSSL 1.1.0. It was used to
-initialize an existing uninitialized B<BN_RECP_CTX>. Typically this would be
-done as follows:
-
- BN_RECP_CTX ctx;
- BN_RECP_CTX_init(&ctx);
-
-Applications should replace use of BN_RECP_CTX_init with BN_RECP_CTX_new
-instead:
-
- BN_RECP_CTX *ctx;
- ctx = BN_RECP_CTX_new();
- if(!ctx) /* Handle error */
- ...
- BN_RECP_CTX_free(ctx);
-
 =head1 SEE ALSO
 
 L<bn(3)>, L<ERR_get_error(3)>, L<BN_add(3)>,
@@ -83,7 +62,7 @@ L<BN_CTX_new(3)>
 
 =head1 HISTORY
 
-BN_RECP_CTX_init was removed in OpenSSL 1.1.0
+BN_RECP_CTX_init() was removed in OpenSSL 1.1.0
 
 =head1 COPYRIGHT
 
diff --git a/doc/crypto/BUF_MEM_new.pod b/doc/crypto/BUF_MEM_new.pod
index 16fe3daa84..1a975776aa 100644
--- a/doc/crypto/BUF_MEM_new.pod
+++ b/doc/crypto/BUF_MEM_new.pod
@@ -2,8 +2,10 @@
 
 =head1 NAME
 
-BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow - simple
-character array structure
+BUF_MEM_FLAG_SECURE,
+BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow
+BUF_MEM_grow_clean, BUF_reverse
+- simple character array structure
 
 standard C library equivalents
 
@@ -17,9 +19,12 @@ standard C library equivalents
 
  BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
 
- void   BUF_MEM_free(BUF_MEM *a);
+ void BUF_MEM_free(BUF_MEM *a);