SSL: Document SSL_add_{file,dir}_cert_subjects_to_stack()

This also removes the incorrect documentation comments by those
functions.
Reviewed-by: NTomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/10403)

doc/man3/SSL_load_client_CA_file.pod

@@ -2,7 +2,10 @@
 
 =head1 NAME
 
-SSL_load_client_CA_file - load certificate names from file
+SSL_load_client_CA_file,
+SSL_add_file_cert_subjects_to_stack,
+SSL_add_dir_cert_subjects_to_stack
+- load certificate names
 
 =head1 SYNOPSIS
 
@@ -10,11 +13,23 @@ SSL_load_client_CA_file - load certificate names from file
 
  STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file);
 
+ int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+                                         const char *file)
+ int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
+                                        const char *dir)
+
 =head1 DESCRIPTION
 
-SSL_load_client_CA_file() reads certificates from B<file> and returns
+SSL_load_client_CA_file() reads certificates from I<file> and returns
 a STACK_OF(X509_NAME) with the subject names found.
 
+SSL_add_file_cert_subjects_to_stack() reads certificates from I<file>,
+and adds their subject name to the already existing I<stack>.
+
+SSL_add_dir_cert_subjects_to_stack() reads certificates from every
+file in the directory I<dir>, and adds their subject name to the
+already existing I<stack>.
+
 =head1 NOTES
 
 SSL_load_client_CA_file() reads a file of PEM formatted certificates and

ssl/ssl_cert.c

@@ -601,14 +601,6 @@ static unsigned long xname_hash(const X509_NAME *a)
     return X509_NAME_hash((X509_NAME *)a);
 }
 
-/**
- * Load CA certs from a file into a ::STACK. Note that it is somewhat misnamed;
- * it doesn't really have anything to do with clients (except that a common use
- * for a stack of CAs is to send it to the client). Actually, it doesn't have
- * much to do with CAs, either, since it will load any old cert.
- * \param file the file containing one or more certs.
- * \return a ::STACK containing the certs.
- */
 STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file)
 {
     BIO *in = BIO_new(BIO_s_file());
@@ -666,15 +658,6 @@ STACK_OF(X509_NAME) *SSL_load_client_CA_file(const char *file)
     return ret;
 }
 
-/**
- * Add a file of certs to a stack.
- * \param stack the stack to add to.
- * \param file the file to add from. All certs in this file that are not
- * already in the stack will be added.
- * \return 1 for success, 0 for failure. Note that in the case of failure some
- * certs may have been added to \c stack.
- */
-
 int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
                                         const char *file)
 {
@@ -725,17 +708,6 @@ int SSL_add_file_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
     return ret;
 }
 
-/**
- * Add a directory of certs to a stack.
- * \param stack the stack to append to.
- * \param dir the directory to append from. All files in this directory will be
- * examined as potential certs. Any that are acceptable to
- * SSL_add_dir_cert_subjects_to_stack() that are not already in the stack will be
- * included.
- * \return 1 for success, 0 for failure. Note that in the case of failure some
- * certs may have been added to \c stack.
- */
-
 int SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stack,
                                        const char *dir)
 {