Doc fixes.

1 files changed, 210 insertions, 222 deletions

diff --git a/lib/x509/x509_write.c b/lib/x509/x509_write.c
index b583e873cd..5539a5738e 100644
--- a/lib/x509/x509_write.c
+++ b/lib/x509/x509_write.c
@@ -41,25 +41,25 @@
 static void disable_optional_stuff (gnutls_x509_crt_t cert);
 
 /**
-  * gnutls_x509_crt_set_dn_by_oid - This function will set the Certificate request subject's distinguished name
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @oid: holds an Object Identifier in a null terminated string
-  * @raw_flag: must be 0, or 1 if the data are DER encoded
-  * @name: a pointer to the name
-  * @sizeof_name: holds the size of @name
-  *
-  * This function will set the part of the name of the Certificate subject, specified
-  * by the given OID. The input string should be ASCII or UTF-8 encoded.
-  *
-  * Some helper macros with popular OIDs can be found in gnutls/x509.h
-  * With this function you can only set the known OIDs. You can test
-  * for known OIDs using gnutls_x509_dn_oid_known(). For OIDs that are
-  * not known (by gnutls) you should properly DER encode your data, and
-  * call this function with raw_flag set.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_dn_by_oid - Set the Certificate request subject's distinguished name
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @oid: holds an Object Identifier in a null terminated string
+ * @raw_flag: must be 0, or 1 if the data are DER encoded
+ * @name: a pointer to the name
+ * @sizeof_name: holds the size of @name
+ *
+ * This function will set the part of the name of the Certificate
+ * subject, specified by the given OID. The input string should be
+ * ASCII or UTF-8 encoded.
+ *
+ * Some helper macros with popular OIDs can be found in gnutls/x509.h
+ * With this function you can only set the known OIDs. You can test
+ * for known OIDs using gnutls_x509_dn_oid_known(). For OIDs that are
+ * not known (by gnutls) you should properly DER encode your data,
+ * and call this function with @raw_flag set.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t crt, const char *oid,
 			       unsigned int raw_flag, const void *name,
@@ -75,28 +75,29 @@ gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t crt, const char *oid,
 }
 
 /**
-  * gnutls_x509_crt_set_issuer_dn_by_oid - This function will set the Certificate request issuer's distinguished name
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @oid: holds an Object Identifier in a null terminated string
-  * @raw_flag: must be 0, or 1 if the data are DER encoded
-  * @name: a pointer to the name
-  * @sizeof_name: holds the size of @name
-  *
-  * This function will set the part of the name of the Certificate issuer, specified
-  * by the given OID. The input string should be ASCII or UTF-8 encoded.
-  *
-  * Some helper macros with popular OIDs can be found in gnutls/x509.h
-  * With this function you can only set the known OIDs. You can test
-  * for known OIDs using gnutls_x509_dn_oid_known(). For OIDs that are
-  * not known (by gnutls) you should properly DER encode your data, and
-  * call this function with raw_flag set.
-  *
-  * Normally you do not need to call this function, since the signing
-  * operation will copy the signer's name as the issuer of the certificate.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_issuer_dn_by_oid - Set the Certificate request issuer's distinguished name
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @oid: holds an Object Identifier in a null terminated string
+ * @raw_flag: must be 0, or 1 if the data are DER encoded
+ * @name: a pointer to the name
+ * @sizeof_name: holds the size of @name
+ *
+ * This function will set the part of the name of the Certificate
+ * issuer, specified by the given OID.  The input string should be
+ * ASCII or UTF-8 encoded.
+ *
+ * Some helper macros with popular OIDs can be found in gnutls/x509.h
+ * With this function you can only set the known OIDs. You can test
+ * for known OIDs using gnutls_x509_dn_oid_known(). For OIDs that are
+ * not known (by gnutls) you should properly DER encode your data,
+ * and call this function with @raw_flag set.
+ *
+ * Normally you do not need to call this function, since the signing
+ * operation will copy the signer's name as the issuer of the
+ * certificate.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_issuer_dn_by_oid (gnutls_x509_crt_t crt,
 				      const char *oid,
@@ -128,7 +129,6 @@ gnutls_x509_crt_set_issuer_dn_by_oid (gnutls_x509_crt_t crt,
  * set it later by using gnutls_x509_crt_set_dn_by_oid() or similar.
  *
  * Returns 0 on success.
- *
  **/
 int
 gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t crt,gnutls_x509_crt_t eecrt,
@@ -161,22 +161,21 @@ gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t crt,gnutls_x509_crt_t eecrt,
 }
 
 /**
-  * gnutls_x509_crt_set_version - This function will set the Certificate request version
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @version: holds the version number. For X.509v1 certificates must be 1.
-  *
-  * This function will set the version of the certificate.  This must
-  * be one for X.509 version 1, and so on.  Plain certificates without
-  * extensions must have version set to one.
-  *
-  * To create well-formed certificates, you must specify version 3 if
-  * you use any certificate extensions.  Extensions are created by
-  * functions such as gnutls_x509_crt_set_subject_alternative_name or
-  * gnutls_x509_crt_set_key_usage.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_version - Set the Certificate request version
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @version: holds the version number. For X.509v1 certificates must be 1.
+ *
+ * This function will set the version of the certificate.  This must
+ * be one for X.509 version 1, and so on.  Plain certificates without
+ * extensions must have version set to one.
+ *
+ * To create well-formed certificates, you must specify version 3 if
+ * you use any certificate extensions.  Extensions are created by
+ * functions such as gnutls_x509_crt_set_subject_alternative_name()
+ * or gnutls_x509_crt_set_key_usage().
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_version (gnutls_x509_crt_t crt, unsigned int version)
 {
@@ -207,8 +206,9 @@ gnutls_x509_crt_set_version (gnutls_x509_crt_t crt, unsigned int version)
   * @crt: should contain a gnutls_x509_crt_t structure
   * @key: holds a private key
   *
-  * This function will set the public parameters from the given private key to the
-  * certificate. Only RSA keys are currently supported.
+  * This function will set the public parameters from the given
+  * private key to the certificate. Only RSA keys are currently
+  * supported.
   *
   * Returns 0 on success.
   *
@@ -240,16 +240,16 @@ gnutls_x509_crt_set_key (gnutls_x509_crt_t crt, gnutls_x509_privkey_t key)
 }
 
 /**
-  * gnutls_x509_crt_set_crq - This function will associate the Certificate with a request
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @crq: holds a certificate request
-  *
-  * This function will set the name and public parameters from the given certificate request to the
-  * certificate. Only RSA keys are currently supported.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_crq - Associate the Certificate with a request
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @crq: holds a certificate request
+ *
+ * This function will set the name and public parameters from the
+ * given certificate request to the certificate. Only RSA keys are
+ * currently supported.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_crq (gnutls_x509_crt_t crt, gnutls_x509_crq_t crq)
 {
@@ -285,19 +285,19 @@ gnutls_x509_crt_set_crq (gnutls_x509_crt_t crt, gnutls_x509_crq_t crq)
 }
 
 /**
-  * gnutls_x509_crt_set_extension_by_oid - This function will set an arbitrary extension
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @oid: holds an Object Identified in null terminated string
-  * @buf: a pointer to a DER encoded data
-  * @sizeof_buf: holds the size of @buf
-  * @critical: should be non zero if the extension is to be marked as critical
-  *
-  * This function will set an the extension, by the specified OID, in the certificate.
-  * The extension data should be binary data DER encoded.
-  *
-  * Returns 0 on success and a negative value in case of an error.
-  *
-  **/
+ * gnutls_x509_crt_set_extension_by_oid - Set an arbitrary extension
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @oid: holds an Object Identified in null terminated string
+ * @buf: a pointer to a DER encoded data
+ * @sizeof_buf: holds the size of @buf
+ * @critical: should be non zero if the extension is to be marked as critical
+ *
+ * This function will set an the extension, by the specified OID, in
+ * the certificate.  The extension data should be binary data DER
+ * encoded.
+ *
+ * Returns 0 on success and a negative value in case of an error.
+ **/
 int
 gnutls_x509_crt_set_extension_by_oid (gnutls_x509_crt_t crt,
 				      const char *oid, const void *buf,
@@ -330,7 +330,7 @@ gnutls_x509_crt_set_extension_by_oid (gnutls_x509_crt_t crt,
 }
 
 /**
- * gnutls_x509_crt_set_basic_constraints - This function will set the basicConstraints extension
+ * gnutls_x509_crt_set_basic_constraints - Set the basicConstraints extension
  * @crt: should contain a gnutls_x509_crt_t structure
  * @ca: true(1) or false(0). Depending on the Certificate authority status.
  * @pathLenConstraint: non-negative values indicate maximum length of path,
@@ -340,7 +340,6 @@ gnutls_x509_crt_set_extension_by_oid (gnutls_x509_crt_t crt,
  * This function will set the basicConstraints certificate extension.
  *
  * Returns 0 on success.
- *
  **/
 int
 gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t crt,
@@ -382,7 +381,7 @@ gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t crt,
 }
 
 /**
- * gnutls_x509_crt_set_ca_status - This function will set the basicConstraints extension
+ * gnutls_x509_crt_set_ca_status - Set the basicConstraints extension
  * @crt: should contain a gnutls_x509_crt_t structure
  * @ca: true(1) or false(0). Depending on the Certificate authority status.
  *
@@ -391,7 +390,6 @@ gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t crt,
  * the pathLenConstraint field too.
  *
  * Returns 0 on success.
- *
  **/
 int
 gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t crt, unsigned int ca)
@@ -400,15 +398,14 @@ gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t crt, unsigned int ca)
 }
 
 /**
-  * gnutls_x509_crt_set_key_usage - This function will set the keyUsage extension
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @usage: an ORed sequence of the GNUTLS_KEY_* elements.
-  *
-  * This function will set the keyUsage certificate extension. 
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_key_usage - Set the keyUsage extension
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @usage: an ORed sequence of the GNUTLS_KEY_* elements.
+ *
+ * This function will set the keyUsage certificate extension.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t crt, unsigned int usage)
 {
@@ -446,16 +443,16 @@ gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t crt, unsigned int usage)
 }
 
 /**
-  * gnutls_x509_crt_set_subject_alternative_name - This function will set the subject Alternative Name
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @type: is one of the gnutls_x509_subject_alt_name_t enumerations
-  * @data_string: The data to be set
-  *
-  * This function will set the subject alternative name certificate extension. 
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_subject_alternative_name - Set the subject Alternative Name
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @type: is one of the gnutls_x509_subject_alt_name_t enumerations
+ * @data_string: The data to be set
+ *
+ * This function will set the subject alternative name certificate
+ * extension.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_subject_alternative_name (gnutls_x509_crt_t crt,
 					      gnutls_x509_subject_alt_name_t
@@ -523,7 +520,6 @@ gnutls_x509_crt_set_subject_alternative_name (gnutls_x509_crt_t crt,
  * This function will set the proxyCertInfo extension.
  *
  * Returns 0 on success.
- *
  **/
 int
 gnutls_x509_crt_set_proxy (gnutls_x509_crt_t crt,
@@ -570,22 +566,21 @@ gnutls_x509_crt_set_proxy (gnutls_x509_crt_t crt,
 }
 
 /**
-  * gnutls_x509_crt_sign2 - This function will sign a certificate with a key
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @issuer: is the certificate of the certificate issuer
-  * @issuer_key: holds the issuer's private key
-  * @dig: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
-  * @flags: must be 0
-  *
-  * This function will sign the certificate with the issuer's private key, and
-  * will copy the issuer's information into the certificate.
-  *
-  * This must be the last step in a certificate generation since all
-  * the previously set parameters are now signed.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_sign2 - Sign a certificate with a key
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @issuer: is the certificate of the certificate issuer
+ * @issuer_key: holds the issuer's private key
+ * @dig: The message digest to use. GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
+ * @flags: must be 0
+ *
+ * This function will sign the certificate with the issuer's private key, and
+ * will copy the issuer's information into the certificate.
+ *
+ * This must be the last step in a certificate generation since all
+ * the previously set parameters are now signed.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
 		       gnutls_x509_privkey_t issuer_key,
@@ -615,17 +610,16 @@ gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
 }
 
 /**
-  * gnutls_x509_crt_sign - This function will sign a certificate with a key
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @issuer: is the certificate of the certificate issuer
-  * @issuer_key: holds the issuer's private key
-  *
-  * This function is the same a gnutls_x509_crt_sign2() with no flags, and
-  * SHA1 as the hash algorithm.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_sign - Sign a certificate with a key
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @issuer: is the certificate of the certificate issuer
+ * @issuer_key: holds the issuer's private key
+ *
+ * This function is the same a gnutls_x509_crt_sign2() with no flags,
+ * and SHA1 as the hash algorithm.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_sign (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
 		      gnutls_x509_privkey_t issuer_key)
@@ -634,15 +628,15 @@ gnutls_x509_crt_sign (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
 }
 
 /**
-  * gnutls_x509_crt_set_activation_time - This function will set the Certificate's activation time
-  * @cert: should contain a gnutls_x509_crt_t structure
-  * @act_time: The actual time
-  *
-  * This function will set the time this Certificate was or will be activated.
-  *
-  * Returns 0 on success, or a negative value in case of an error.
-  *
-  **/
+ * gnutls_x509_crt_set_activation_time - Set the Certificate's activation time
+ * @cert: should contain a gnutls_x509_crt_t structure
+ * @act_time: The actual time
+ *
+ * This function will set the time this Certificate was or will be
+ * activated.
+ *
+ * Returns 0 on success, or a negative value in case of an error.
+ **/
 int
 gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t cert, time_t act_time)
 {
@@ -658,15 +652,14 @@ gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t cert, time_t act_time)
 }
 
 /**
-  * gnutls_x509_crt_set_expiration_time - This function will set the Certificate's expiration time
-  * @cert: should contain a gnutls_x509_crt_t structure
-  * @exp_time: The actual time
-  *
-  * This function will set the time this Certificate will expire.
-  *
-  * Returns 0 on success, or a negative value in case of an error.
-  *
-  **/
+ * gnutls_x509_crt_set_expiration_time - Set the Certificate's expiration time
+ * @cert: should contain a gnutls_x509_crt_t structure
+ * @exp_time: The actual time
+ *
+ * This function will set the time this Certificate will expire.
+ *
+ * Returns 0 on success, or a negative value in case of an error.
+ **/
 int
 gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t cert, time_t exp_time)
 {
@@ -680,19 +673,18 @@ gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t cert, time_t exp_time)
 }
 
 /**
-  * gnutls_x509_crt_set_serial - This function will set the certificate's serial number
-  * @cert: should contain a gnutls_x509_crt_t structure
-  * @serial: The serial number
-  * @serial_size: Holds the size of the serial field.
-  *
-  * This function will set the X.509 certificate's serial number. 
-  * Serial is not always a 32 or 64bit number. Some CAs use
-  * large serial numbers, thus it may be wise to handle it as something
-  * opaque. 
-  *
-  * Returns 0 on success, or a negative value in case of an error.
-  *
-  **/
+ * gnutls_x509_crt_set_serial - Set the certificate's serial number
+ * @cert: should contain a gnutls_x509_crt_t structure
+ * @serial: The serial number
+ * @serial_size: Holds the size of the serial field.
+ *
+ * This function will set the X.509 certificate's serial number.
+ * Serial is not always a 32 or 64bit number.  Some CAs use large
+ * serial numbers, thus it may be wise to handle it as something
+ * opaque.
+ *
+ * Returns 0 on success, or a negative value in case of an error.
+ **/
 int
 gnutls_x509_crt_set_serial (gnutls_x509_crt_t cert, const void *serial,
 			    size_t serial_size)
@@ -739,17 +731,16 @@ disable_optional_stuff (gnutls_x509_crt_t cert)
 }
 
 /**
-  * gnutls_x509_crt_set_crl_dist_points - This function will set the CRL dist points
-  * @crt: should contain a gnutls_x509_crt_t structure
-  * @type: is one of the gnutls_x509_subject_alt_name_t enumerations
-  * @data_string: The data to be set
-  * @reason_flags: revocation reasons
-  *
-  * This function will set the CRL distribution points certificate extension. 
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_set_crl_dist_points - Set the CRL dist points
+ * @crt: should contain a gnutls_x509_crt_t structure
+ * @type: is one of the gnutls_x509_subject_alt_name_t enumerations
+ * @data_string: The data to be set
+ * @reason_flags: revocation reasons
+ *
+ * This function will set the CRL distribution points certificate extension.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t crt,
 				     gnutls_x509_subject_alt_name_t
@@ -807,17 +798,16 @@ gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t crt,
 }
 
 /**
-  * gnutls_x509_crt_cpy_crl_dist_points - This function will copy the CRL dist points
-  * @dst: should contain a gnutls_x509_crt_t structure
-  * @src: the certificate where the dist points will be copied from
-  *
-  * This function will copy the CRL distribution points certificate 
-  * extension, from the source to the destination certificate.
-  * This may be useful to copy from a CA certificate to issued ones.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_x509_crt_cpy_crl_dist_points - Copy the CRL dist points
+ * @dst: should contain a gnutls_x509_crt_t structure
+ * @src: the certificate where the dist points will be copied from
+ *
+ * This function will copy the CRL distribution points certificate
+ * extension, from the source to the destination certificate.
+ * This may be useful to copy from a CA certificate to issued ones.
+ *
+ * Returns 0 on success.
+ **/
 int
 gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t dst,
 				     gnutls_x509_crt_t src)
@@ -859,16 +849,16 @@ gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t dst,
 }
 
 /**
-  * gnutls_x509_crt_set_subject_key_id - This function will set the certificate's subject key id
-  * @cert: should contain a gnutls_x509_crt_t structure
-  * @id: The key ID
-  * @id_size: Holds the size of the serial field.
-  *
-  * This function will set the X.509 certificate's subject key ID extension.
-  *
-  * Returns 0 on success, or a negative value in case of an error.
-  *
-  **/
+ * gnutls_x509_crt_set_subject_key_id - Set the certificate's subject key id
+ * @cert: should contain a gnutls_x509_crt_t structure
+ * @id: The key ID
+ * @id_size: Holds the size of the serial field.
+ *
+ * This function will set the X.509 certificate's subject key ID
+ * extension.
+ *
+ * Returns 0 on success, or a negative value in case of an error.
+ **/
 int
 gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t cert,
 				    const void *id, size_t id_size)
@@ -921,17 +911,16 @@ gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t cert,
 }
 
 /**
-  * gnutls_x509_crt_set_authority_key_id - This function will set the certificate authority's key id
-  * @cert: should contain a gnutls_x509_crt_t structure
-  * @id: The key ID
-  * @id_size: Holds the size of the serial field.
-  *
-  * This function will set the X.509 certificate's authority key ID extension.
-  * Only the keyIdentifier field can be set with this function.
-  *
-  * Returns 0 on success, or a negative value in case of an error.
-  *
-  **/
+ * gnutls_x509_crt_set_authority_key_id - Set the certificate authority's key id
+ * @cert: should contain a gnutls_x509_crt_t structure
+ * @id: The key ID
+ * @id_size: Holds the size of the serial field.
+ *
+ * This function will set the X.509 certificate's authority key ID extension.
+ * Only the keyIdentifier field can be set with this function.
+ *
+ * Returns 0 on success, or a negative value in case of an error.
+ **/
 int
 gnutls_x509_crt_set_authority_key_id (gnutls_x509_crt_t cert,
 				      const void *id, size_t id_size)
@@ -984,20 +973,19 @@ gnutls_x509_crt_set_authority_key_id (gnutls_x509_crt_t cert,
 }
 
 /**
-  * gnutls_x509_crt_set_key_purpose_oid - This function sets the Certificate's key purpose OIDs
-  * @cert: should contain a gnutls_x509_crt_t structure
-  * @oid: a pointer to a null terminated string that holds the OID
-  * @critical: Whether this extension will be critical or not
-  *
-  * This function will set the key purpose OIDs of the Certificate.
-  * These are stored in the Extended Key Usage extension (2.5.29.37)
-  * See the GNUTLS_KP_* definitions for human readable names.
-  *
-  * Subsequent calls to this function will append OIDs to the OID list.
-  *
-  * On success 0 is returned.
-  *
-  **/
+ * gnutls_x509_crt_set_key_purpose_oid - Sets the Certificate's key purpose OIDs
+ * @cert: should contain a gnutls_x509_crt_t structure
+ * @oid: a pointer to a null terminated string that holds the OID
+ * @critical: Whether this extension will be critical or not
+ *
+ * This function will set the key purpose OIDs of the Certificate.
+ * These are stored in the Extended Key Usage extension (2.5.29.37)
+ * See the GNUTLS_KP_* definitions for human readable names.
+ *
+ * Subsequent calls to this function will append OIDs to the OID list.
+ *
+ * On success 0 is returned.
+ **/
 int
 gnutls_x509_crt_set_key_purpose_oid (gnutls_x509_crt_t cert,
 				     const void *oid, unsigned int critical)