Updated X509v3_get_ext_by_NID.pod and X509_CRL_get0_by_serial.pod

Updated these to the current documentation style.
Moved X509v3_delete_ext() under BUGS
to NOTES and added information to call free.

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18786)

2 files changed, 59 insertions, 56 deletions

diff --git a/doc/man3/X509_CRL_get0_by_serial.pod b/doc/man3/X509_CRL_get0_by_serial.pod
index d1e0f077a3..e0061563bc 100644
--- a/doc/man3/X509_CRL_get0_by_serial.pod
+++ b/doc/man3/X509_CRL_get0_by_serial.pod
@@ -30,42 +30,42 @@ functions
 
 =head1 DESCRIPTION
 
-X509_CRL_get0_by_serial() attempts to find a revoked entry in B<crl> for
-serial number B<serial>. If it is successful it sets B<*ret> to the internal
-pointer of the matching entry, as a result B<*ret> must not be freed up
+X509_CRL_get0_by_serial() attempts to find a revoked entry in I<crl> for
+serial number I<serial>. If it is successful, it sets I<*ret> to the internal
+pointer of the matching entry. As a result, I<*ret> B<MUST NOT> be freed
 after the call.
 
 X509_CRL_get0_by_cert() is similar to X509_get0_by_serial() except it
-looks for a revoked entry using the serial number of certificate B<x>.
+looks for a revoked entry using the serial number of certificate I<x>.
 
-X509_CRL_get_REVOKED() returns an internal pointer to a stack of all
-revoked entries for B<crl>.
+X509_CRL_get_REVOKED() returns an internal pointer to a STACK of all
+revoked entries for I<crl>.
 
 X509_REVOKED_get0_serialNumber() returns an internal pointer to the
-serial number of B<r>.
+serial number of I<r>.
 
 X509_REVOKED_get0_revocationDate() returns an internal pointer to the
-revocation date of B<r>.
+revocation date of I<r>.
 
-X509_REVOKED_set_serialNumber() sets the serial number of B<r> to B<serial>.
-The supplied B<serial> pointer is not used internally so it should be
-freed up after use.
+X509_REVOKED_set_serialNumber() sets the serial number of I<r> to I<serial>.
+The supplied I<serial> pointer is not used internally so it should be
+freed after use.
 
-X509_REVOKED_set_revocationDate() sets the revocation date of B<r> to
-B<tm>. The supplied B<tm> pointer is not used internally so it should be
-freed up after use.
+X509_REVOKED_set_revocationDate() sets the revocation date of I<r> to
+I<tm>. The supplied I<tm> pointer is not used internally so it should be
+freed after use.
 
-X509_CRL_add0_revoked() appends revoked entry B<rev> to CRL B<crl>. The
-pointer B<rev> is used internally so it must not be freed up after the call:
+X509_CRL_add0_revoked() appends revoked entry I<rev> to CRL I<crl>. The
+pointer I<rev> is used internally so it B<MUST NOT> be freed after the call:
 it is freed when the parent CRL is freed.
 
-X509_CRL_sort() sorts the revoked entries of B<crl> into ascending serial
+X509_CRL_sort() sorts the revoked entries of I<crl> into ascending serial
 number order.
 
 =head1 NOTES
 
 Applications can determine the number of revoked entries returned by
-X509_CRL_get_revoked() using sk_X509_REVOKED_num() and examine each one
+X509_CRL_get_REVOKED() using sk_X509_REVOKED_num() and examine each one
 in turn using sk_X509_REVOKED_value().
 
 =head1 RETURN VALUES
@@ -74,15 +74,15 @@ X509_CRL_get0_by_serial() and X509_CRL_get0_by_cert() return 0 for failure,
 1 on success except if the revoked entry has the reason C<removeFromCRL> (8),
 in which case 2 is returned.
 
-X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(),
-X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for
-failure.
+X509_CRL_get_REVOKED() returns a STACK of revoked entries.
 
-X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> pointer.
+X509_REVOKED_get0_serialNumber() returns an B<ASN1_INTEGER> structure.
 
-X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> value.
+X509_REVOKED_get0_revocationDate() returns an B<ASN1_TIME> structure.
 
-X509_CRL_get_REVOKED() returns a STACK of revoked entries.
+X509_REVOKED_set_serialNumber(), X509_REVOKED_set_revocationDate(),
+X509_CRL_add0_revoked() and X509_CRL_sort() return 1 for success and 0 for
+failure.
 
 =head1 SEE ALSO
 
diff --git a/doc/man3/X509v3_get_ext_by_NID.pod b/doc/man3/X509v3_get_ext_by_NID.pod
index f7fa2b29b6..9d26bfe19a 100644
--- a/doc/man3/X509v3_get_ext_by_NID.pod
+++ b/doc/man3/X509v3_get_ext_by_NID.pod
@@ -41,7 +41,8 @@ X509_REVOKED_add_ext - extension stack utility functions
  int X509_CRL_get_ext_count(const X509_CRL *x);
  X509_EXTENSION *X509_CRL_get_ext(const X509_CRL *x, int loc);
  int X509_CRL_get_ext_by_NID(const X509_CRL *x, int nid, int lastpos);
- int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj, int lastpos);
+ int X509_CRL_get_ext_by_OBJ(const X509_CRL *x, const ASN1_OBJECT *obj,
+                             int lastpos);
  int X509_CRL_get_ext_by_critical(const X509_CRL *x, int crit, int lastpos);
  X509_EXTENSION *X509_CRL_delete_ext(X509_CRL *x, int loc);
  int X509_CRL_add_ext(X509_CRL *x, X509_EXTENSION *ex, int loc);
@@ -57,77 +58,79 @@ X509_REVOKED_add_ext - extension stack utility functions
 
 =head1 DESCRIPTION
 
-X509v3_get_ext_count() retrieves the number of extensions in B<x>.
+X509v3_get_ext_count() retrieves the number of extensions in I<x>.
 
-X509v3_get_ext() retrieves extension B<loc> from B<x>. The index B<loc>
-can take any value from B<0> to X509_get_ext_count(x) - 1. The returned
-extension is an internal pointer which B<must not> be freed up by the
+X509v3_get_ext() retrieves extension I<loc> from I<x>. The index I<loc>
+can take any value from 0 to X509_get_ext_count(I<x>) - 1. The returned
+extension is an internal pointer which B<MUST NOT> be freed by the
 application.
 
 X509v3_get_ext_by_NID() and X509v3_get_ext_by_OBJ() look for an extension
-with B<nid> or B<obj> from extension stack B<x>. The search starts from the
-extension after B<lastpos> or from the beginning if <lastpos> is B<-1>. If
-the extension is found its index is returned otherwise B<-1> is returned.
+with I<nid> or I<obj> from extension STACK I<x>. The search starts from the
+extension after I<lastpos> or from the beginning if I<lastpos> is -1. If
+the extension is found, its index is returned, otherwise -1 is returned.
 
 X509v3_get_ext_by_critical() is similar to X509v3_get_ext_by_NID() except it
-looks for an extension of criticality B<crit>. A zero value for B<crit>
-looks for a non-critical extension a nonzero value looks for a critical
+looks for an extension of criticality I<crit>. A zero value for I<crit>
+looks for a non-critical extension. A nonzero value looks for a critical
 extension.
 
-X509v3_delete_ext() deletes the extension with index B<loc> from B<x>.
+X509v3_delete_ext() deletes the extension with index I<loc> from I<x>.
 The deleted extension is returned and must be freed by the caller.
-If B<loc> is in invalid index value B<NULL> is returned.
+If I<loc> is an invalid index value, NULL is returned.
 
-X509v3_add_ext() adds extension B<ex> to stack B<*x> at position B<loc>. If
-B<loc> is B<-1> the new extension is added to the end. If B<*x> is B<NULL>
-a new stack will be allocated. The passed extension B<ex> is duplicated
+X509v3_add_ext() adds extension I<ex> to STACK I<*x> at position I<loc>. If
+I<loc> is -1, the new extension is added to the end. If I<*x> is NULL,
+a new STACK will be allocated. The passed extension I<ex> is duplicated
 internally so it must be freed after use.
 
 X509_get_ext_count(), X509_get_ext(), X509_get_ext_by_NID(),
 X509_get_ext_by_OBJ(), X509_get_ext_by_critical(), X509_delete_ext()
-and X509_add_ext() operate on the extensions of certificate B<x> they are
+and X509_add_ext() operate on the extensions of certificate I<x>. They are
 otherwise identical to the X509v3 functions.
 
 X509_CRL_get_ext_count(), X509_CRL_get_ext(), X509_CRL_get_ext_by_NID(),
 X509_CRL_get_ext_by_OBJ(), X509_CRL_get_ext_by_critical(),
 X509_CRL_delete_ext() and X509_CRL_add_ext() operate on the extensions of
-CRL B<x> they are otherwise identical to the X509v3 functions.
+CRL I<x>. They are otherwise identical to the X509v3 functions.
 
 X509_REVOKED_get_ext_count(), X509_REVOKED_get_ext(),
 X509_REVOKED_get_ext_by_NID(), X509_REVOKED_get_ext_by_OBJ(),
 X509_REVOKED_get_ext_by_critical(), X509_REVOKED_delete_ext() and
-X509_REVOKED_add_ext() operate on the extensions of CRL entry B<x>
-they are otherwise identical to the X509v3 functions.
+X509_REVOKED_add_ext() operate on the extensions of CRL entry I<x>.
+They are otherwise identical to the X509v3 functions.
 
 =head1 NOTES
 
-These functions are used to examine stacks of extensions directly. Many
-applications will want to parse or encode and add an extension: they should
-use the extension encode and decode functions instead such as
+These functions are used to examine stacks of extensions directly.
+Applications that want to parse or encode and add an extension should
+use the extension encode and decode functions instead, such as
 X509_add1_ext_i2d() and X509_get_ext_d2i().
 
-Extension indices start from zero, so a zero index return value is B<not> an
-error. These search functions start from the extension B<after> the B<lastpos>
-parameter so it should initially be set to B<-1>, if it is set to zero the
-initial extension will not be checked.
-
-=head1 BUGS
+For X509v3_get_ext_by_NID(), X509v3_get_ext_by_OBJ(),
+X509v3_get_ext_by_critical() and its variants, a zero index return value
+is not an error since extension STACK I<x> indices start from zero.
+These search functions start from the extension B<after> the I<lastpos> parameter
+so it should initially be set to -1. If it is set to zero, the initial extension
+will not be checked.
 
 X509v3_delete_ext() and its variants are a bit counter-intuitive
 because these functions do not free the extension they delete.
+They return an B<X509_EXTENSION> object which must be explicitly freed
+using X509_EXTENSION_free().
 
 =head1 RETURN VALUES
 
 X509v3_get_ext_count() returns the extension count.
 
 X509v3_get_ext(), X509v3_delete_ext() and X509_delete_ext() return an
-B<X509_EXTENSION> pointer or B<NULL> if an error occurs.
+B<X509_EXTENSION> structure or NULL if an error occurs.
 
-X509v3_get_ext_by_NID() X509v3_get_ext_by_OBJ() and
-X509v3_get_ext_by_critical() return the extension index or B<-1> if an
+X509v3_get_ext_by_NID(), X509v3_get_ext_by_OBJ() and
+X509v3_get_ext_by_critical() return the extension index or -1 if an
 error occurs.
 
-X509v3_add_ext() returns a stack of extensions or B<NULL> on error.
+X509v3_add_ext() returns a STACK of extensions or NULL on error.
 
 X509_add_ext() returns 1 on success and 0 on error.