Doc fix.

1 files changed, 266 insertions, 276 deletions

diff --git a/lib/x509/crq.c b/lib/x509/crq.c
index 772ec055f1..fb4c6f97b1 100644
--- a/lib/x509/crq.c
+++ b/lib/x509/crq.c
@@ -22,7 +22,8 @@
  *
  */
 
-/* This file contains functions to handle PKCS #10 certificate requests.
+/* This file contains functions to handle PKCS #10 certificate
+   requests, see RFC 2986.
  */
 
 #include <gnutls_int.h>
@@ -39,43 +40,44 @@
 #include <libtasn1.h>
 
 /**
-  * gnutls_x509_crq_init - This function initializes a gnutls_x509_crq_t structure
-  * @crq: The structure to be initialized
-  *
-  * This function will initialize a PKCS10 certificate request structure. 
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_init - initializes a #gnutls_x509_crq_t structure
+ * @crq: The structure to be initialized
+ *
+ * This function will initialize a PKCS#10 certificate request
+ * structure.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_init (gnutls_x509_crq_t * crq)
 {
+  int result;
+
   *crq = gnutls_calloc (1, sizeof (gnutls_x509_crq_int));
+  if (!*crq)
+    return GNUTLS_E_MEMORY_ERROR;
 
-  if (*crq)
+  result = asn1_create_element (_gnutls_get_pkix (),
+				"PKIX1.pkcs-10-CertificationRequest",
+				&((*crq)->crq));
+  if (result != ASN1_SUCCESS)
     {
-      int result = asn1_create_element (_gnutls_get_pkix (),
-					"PKIX1.pkcs-10-CertificationRequest",
-					&((*crq)->crq));
-      if (result != ASN1_SUCCESS)
-	{
-	  gnutls_assert ();
-	  gnutls_free (*crq);
-	  return _gnutls_asn2err (result);
-	}
-      return 0;			/* success */
+      gnutls_assert ();
+      gnutls_free (*crq);
+      return _gnutls_asn2err (result);
     }
-  return GNUTLS_E_MEMORY_ERROR;
+
+  return 0;
 }
 
 /**
-  * gnutls_x509_crq_deinit - This function deinitializes memory used by a gnutls_x509_crq_t structure
-  * @crq: The structure to be initialized
-  *
-  * This function will deinitialize a CRL structure. 
-  *
-  **/
+ * gnutls_x509_crq_deinit - deinitializes a #gnutls_x509_crq_t structure
+ * @crq: The structure to be initialized
+ *
+ * This function will deinitialize a PKCS#10 certificate request
+ * structure.
+ **/
 void
 gnutls_x509_crq_deinit (gnutls_x509_crq_t crq)
 {
@@ -92,14 +94,14 @@ gnutls_x509_crq_deinit (gnutls_x509_crq_t crq)
 #define PEM_CRQ2 "CERTIFICATE REQUEST"
 
 /**
- * gnutls_x509_crq_import - This function will import a DER or PEM encoded Certificate request
+ * gnutls_x509_crq_import - import a DER or PEM encoded Certificate request
  * @crq: The structure to store the parsed certificate request.
  * @data: The DER or PEM encoded certificate.
  * @format: One of DER or PEM
  *
- * This function will convert the given DER or PEM encoded Certificate
- * to the native gnutls_x509_crq_t format. The output will be stored
- * in @crq.
+ * This function will convert the given DER or PEM encoded certificate
+ * request to a #gnutls_x509_crq_t structure.  The output will be
+ * stored in @crq.
  *
  * If the Certificate is PEM encoded it should have a header of "NEW
  * CERTIFICATE REQUEST".
@@ -170,23 +172,21 @@ cleanup:
 
 
 /**
-  * gnutls_x509_crq_get_dn - This function returns the Certificate request subject's distinguished name
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @buf: a pointer to a structure to hold the name (may be null)
-  * @sizeof_buf: initially holds the size of @buf
-  *
-  * This function will copy the name of the Certificate request
-  * subject in the provided buffer. The name will be in the form
-  * "C=xxxx,O=yyyy,CN=zzzz" as described in RFC2253. The output string
-  * will be ASCII or UTF-8 encoded, depending on the certificate data.
-  *
-  * If @buf is null then only the size will be filled.
-  *
-  * Returns: GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
-  * long enough, and in that case the *sizeof_buf will be updated with
-  * the required size.  On success 0 is returned.
-  *
-  **/
+ * gnutls_x509_crq_get_dn - get certificate request subject's distinguished name
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @buf: a pointer to a structure to hold the name (may be %NULL)
+ * @sizeof_buf: initially holds the size of @buf
+ *
+ * This function will copy the name of the Certificate request subject
+ * to the provided buffer.  The name will be in the form
+ * "C=xxxx,O=yyyy,CN=zzzz" as described in RFC 2253. The output string
+ * @buf will be ASCII or UTF-8 encoded, depending on the certificate
+ * data.
+ *
+ * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+ *   long enough, and in that case the *@sizeof_buf will be updated with
+ *   the required size.  On success 0 is returned.
+ **/
 int
 gnutls_x509_crq_get_dn (gnutls_x509_crq_t crq, char *buf, size_t * sizeof_buf)
 {
@@ -202,33 +202,30 @@ gnutls_x509_crq_get_dn (gnutls_x509_crq_t crq, char *buf, size_t * sizeof_buf)
 }
 
 /**
-  * gnutls_x509_crq_get_dn_by_oid - This function returns the Certificate request subject's distinguished name
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @oid: holds an Object Identified in null terminated string
-  * @indx: In case multiple same OIDs exist in the RDN, this specifies
-  *   which to send. Use zero to get the first one.
-  * @raw_flag: If non zero returns the raw DER data of the DN part.
-  * @buf: a pointer to a structure to hold the name (may be null)
-  * @sizeof_buf: initially holds the size of @buf
-  *
-  * This function will extract the part of the name of the Certificate
-  * request subject, specified by the given OID. The output will be
-  * encoded as described in RFC2253. The output string will be ASCII
-  * or UTF-8 encoded, depending on the certificate data.
-  *
-  * Some helper macros with popular OIDs can be found in gnutls/x509.h
-  * If raw flag is zero, this function will only return known OIDs as
-  * text. Other OIDs will be DER encoded, as described in RFC2253 --
-  * in hex format with a '\#' prefix.  You can check about known OIDs
-  * using gnutls_x509_dn_oid_known().
-  *
-  * If @buf is null then only the size will be filled.
-  *
-  * Returns: GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
-  * long enough, and in that case the *sizeof_buf will be updated with
-  * the required size.  On success 0 is returned.
-  *
-  **/
+ * gnutls_x509_crq_get_dn_by_oid - get certificate request subject's distinguished name
+ * @crq: should contain a gnutls_x509_crq_t structure
+ * @oid: holds an Object Identified in null terminated string
+ * @indx: In case multiple same OIDs exist in the RDN, this specifies
+ *   which to send. Use zero to get the first one.
+ * @raw_flag: If non zero returns the raw DER data of the DN part.
+ * @buf: a pointer to a structure to hold the name (may be %NULL)
+ * @sizeof_buf: initially holds the size of @buf
+ *
+ * This function will extract the part of the name of the Certificate
+ * request subject, specified by the given OID. The output will be
+ * encoded as described in RFC2253. The output string will be ASCII
+ * or UTF-8 encoded, depending on the certificate data.
+ *
+ * Some helper macros with popular OIDs can be found in gnutls/x509.h
+ * If raw flag is zero, this function will only return known OIDs as
+ * text. Other OIDs will be DER encoded, as described in RFC2253 --
+ * in hex format with a '\#' prefix.  You can check about known OIDs
+ * using gnutls_x509_dn_oid_known().
+ *
+ * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is
+ *   not long enough, and in that case the *@sizeof_buf will be
+ *   updated with the required size.  On success 0 is returned.
+ **/
 int
 gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t crq, const char *oid,
 			       int indx, unsigned int raw_flag,
@@ -240,28 +237,26 @@ gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t crq, const char *oid,
       return GNUTLS_E_INVALID_REQUEST;
     }
 
-  return _gnutls_x509_parse_dn_oid (crq->crq,
-				    "certificationRequestInfo.subject.rdnSequence",
-				    oid, indx, raw_flag, buf, sizeof_buf);
+  return _gnutls_x509_parse_dn_oid
+    (crq->crq,
+     "certificationRequestInfo.subject.rdnSequence",
+     oid, indx, raw_flag, buf, sizeof_buf);
 }
 
 /**
-  * gnutls_x509_crq_get_dn_oid - This function returns the Certificate request subject's distinguished name OIDs
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @indx: Specifies which DN OID to send. Use zero to get the first one.
-  * @oid: a pointer to a structure to hold the name (may be null)
-  * @sizeof_oid: initially holds the size of @oid
-  *
-  * This function will extract the requested OID of the name of the
-  * Certificate request subject, specified by the given index.
-  *
-  * If oid is null then only the size will be filled.
-  *
-  * Returns: GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
-  * long enough, and in that case the *sizeof_oid will be updated with
-  * the required size.  On success 0 is returned.
-  *
-  **/
+ * gnutls_x509_crq_get_dn_oid - This function returns the Certificate request subject's distinguished name OIDs
+ * @crq: should contain a gnutls_x509_crq_t structure
+ * @indx: Specifies which DN OID to send. Use zero to get the first one.
+ * @oid: a pointer to a structure to hold the name (may be %NULL)
+ * @sizeof_oid: initially holds the size of @oid
+ *
+ * This function will extract the requested OID of the name of the
+ * certificate request subject, specified by the given index.
+ *
+ * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is
+ *   not long enough, and in that case the *@sizeof_oid will be
+ *   updated with the required size.  On success 0 is returned.
+ **/
 int
 gnutls_x509_crq_get_dn_oid (gnutls_x509_crq_t crq,
 			    int indx, void *oid, size_t * sizeof_oid)
@@ -280,9 +275,11 @@ gnutls_x509_crq_get_dn_oid (gnutls_x509_crq_t crq,
 /* Parses an Attribute list in the asn1_struct, and searches for the
  * given OID. The index indicates the attribute value to be returned.
  *
- * If raw==0 only printable data are returned, or GNUTLS_E_X509_UNSUPPORTED_ATTRIBUTE.
+ * If raw==0 only printable data are returned, or
+ * GNUTLS_E_X509_UNSUPPORTED_ATTRIBUTE.
  *
- * asn1_attr_name must be a string in the form "certificationRequestInfo.attributes"
+ * asn1_attr_name must be a string in the form
+ * "certificationRequestInfo.attributes"
  *
  */
 static int
@@ -327,7 +324,7 @@ parse_attribute (ASN1_TYPE asn1_struct,
 
       /* Move to the attibute type and values
        */
-      /* Read the OID 
+      /* Read the OID
        */
       _gnutls_str_cpy (tmpbuffer3, sizeof (tmpbuffer3), tmpbuffer1);
       _gnutls_str_cat (tmpbuffer3, sizeof (tmpbuffer3), ".type");
@@ -347,7 +344,7 @@ parse_attribute (ASN1_TYPE asn1_struct,
       if (strcmp (oid, given_oid) == 0)
 	{			/* Found the OID */
 
-	  /* Read the Value 
+	  /* Read the Value
 	   */
 	  snprintf (tmpbuffer3, sizeof (tmpbuffer3), "%s.values.?%u",
 		    tmpbuffer1, indx + 1);
@@ -411,18 +408,16 @@ cleanup:
 }
 
 /**
-  * gnutls_x509_crq_get_challenge_password - This function will get the challenge password 
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @pass: will hold a null terminated password
-  * @sizeof_pass: Initially holds the size of @pass.
-  *
-  * This function will return the challenge password in the
-  * request.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_get_challenge_password - get challenge password
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @pass: will hold a zero-terminated password string
+ * @sizeof_pass: Initially holds the size of @pass.
+ *
+ * This function will return the challenge password in the request.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_get_challenge_password (gnutls_x509_crq_t crq,
 					char *pass, size_t * sizeof_pass)
@@ -438,7 +433,7 @@ gnutls_x509_crq_get_challenge_password (gnutls_x509_crq_t crq,
 }
 
 /* This function will attempt to set the requested attribute in
- * the given X509v3 certificate. 
+ * the given X509v3 certificate.
  *
  * Critical will be either 0 or 1.
  */
@@ -565,11 +560,11 @@ set_attribute (ASN1_TYPE asn, const char *root,
 	      return _gnutls_asn2err (result);
 	    }
 
-	  /* Handle Extension 
+	  /* Handle Extension
 	   */
 	  if (strcmp (extnID, ext_id) == 0)
 	    {
-	      /* attribute was found 
+	      /* attribute was found
 	       */
 	      return overwrite_attribute (asn, root, k, ext_data);
 	    }
@@ -595,19 +590,19 @@ set_attribute (ASN1_TYPE asn, const char *root,
 }
 
 /**
-  * gnutls_x509_crq_set_attribute_by_oid - This function will set an attribute in the request
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @oid: holds an Object Identified in null terminated string
-  * @buf: a pointer to a structure that holds the attribute data
-  * @sizeof_buf: holds the size of @buf
-  *
-  * This function will set the attribute in the certificate request specified
-  * by the given Object ID. The attribute must be be DER encoded.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_set_attribute_by_oid - set attribute in the request
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @oid: holds an Object Identified in zero-terminated string
+ * @buf: a pointer to a structure that holds the attribute data
+ * @sizeof_buf: holds the size of @buf
+ *
+ * This function will set the attribute in the certificate request
+ * specified by the given Object ID.  The attribute must be be DER
+ * encoded.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_set_attribute_by_oid (gnutls_x509_crq_t crq,
 				      const char *oid, void *buf,
@@ -626,21 +621,21 @@ gnutls_x509_crq_set_attribute_by_oid (gnutls_x509_crq_t crq,
 }
 
 /**
-  * gnutls_x509_crq_get_attribute_by_oid - This function will get an attribute of the request 
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @oid: holds an Object Identified in null terminated string
-  * @indx: In case multiple same OIDs exist in the attribute list, this specifies
-  *   which to send. Use zero to get the first one.
-  * @buf: a pointer to a structure to hold the attribute data (may be null)
-  * @sizeof_buf: initially holds the size of @buf
-  *
-  * This function will return the attribute in the certificate request specified
-  * by the given Object ID. The attribute will be DER encoded.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_get_attribute_by_oid - get an attribute in the request
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @oid: holds an Object Identified in zero-terminated string
+ * @indx: In case multiple same OIDs exist in the attribute list, this
+ *   specifies which to send, use zero to get the first one
+ * @buf: a pointer to a structure to hold the attribute data (may be %NULL)
+ * @sizeof_buf: initially holds the size of @buf
+ *
+ * This function will return the attribute in the certificate request
+ * specified by the given Object ID.  The attribute will be DER
+ * encoded.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_get_attribute_by_oid (gnutls_x509_crq_t crq,
 				      const char *oid, int indx, void *buf,
@@ -657,22 +652,22 @@ gnutls_x509_crq_get_attribute_by_oid (gnutls_x509_crq_t crq,
 }
 
 /**
- * gnutls_x509_crq_set_dn_by_oid - This function will set the Certificate request subject's distinguished name
- * @crq: should contain a gnutls_x509_crq_t structure
- * @oid: holds an Object Identifier in a null terminated string
+ * gnutls_x509_crq_set_dn_by_oid - set the certificate request subject's distinguished name
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @oid: holds an Object Identifier in a zero-terminated string
  * @raw_flag: must be 0, or 1 if the data are DER encoded
  * @data: a pointer to the input data
  * @sizeof_data: holds the size of @data
  *
  * This function will set the part of the name of the Certificate
- * request subject, specified by the given OID. The input string
+ * request 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.
+ * 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: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
  *   negative error value.
@@ -693,17 +688,16 @@ gnutls_x509_crq_set_dn_by_oid (gnutls_x509_crq_t crq, const char *oid,
 }
 
 /**
-  * gnutls_x509_crq_set_version - This function will set the Certificate request version
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @version: holds the version number. For v1 Requests must be 1.
-  *
-  * This function will set the version of the certificate request. For
-  * version 1 requests this must be one.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_set_version - set the Certificate request version
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @version: holds the version number, for v1 Requests must be 1
+ *
+ * This function will set the version of the certificate request.  For
+ * version 1 requests this must be one.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_set_version (gnutls_x509_crq_t crq, unsigned int version)
 {
@@ -731,14 +725,15 @@ gnutls_x509_crq_set_version (gnutls_x509_crq_t crq, unsigned int version)
 }
 
 /**
-  * gnutls_x509_crq_get_version - This function returns the Certificate request's version number
-  * @crq: should contain a gnutls_x509_crq_t structure
-  *
-  * This function will return the version of the specified Certificate request.
-  *
-  * Returns: version of certificate request, or a negative value on
-  *   error.
-  **/
+ * gnutls_x509_crq_get_version - get certificate request's version number
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ *
+ * This function will return the version of the specified Certificate
+ * request.
+ *
+ * Returns: version of certificate request, or a negative value on
+ *   error.
+ **/
 int
 gnutls_x509_crq_get_version (gnutls_x509_crq_t crq)
 {
@@ -767,17 +762,16 @@ gnutls_x509_crq_get_version (gnutls_x509_crq_t crq)
 }
 
 /**
-  * gnutls_x509_crq_set_key - This function will associate the Certificate request with a key
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @key: holds a private key
-  *
-  * This function will set the public parameters from the given private key to the
-  * request. Only RSA keys are currently supported.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_set_key - associate the certificate request with a key
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @key: holds a private key
+ *
+ * This function will set the public parameters from the given private
+ * key to the request.  Only RSA keys are currently supported.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_set_key (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)
 {
@@ -789,11 +783,12 @@ gnutls_x509_crq_set_key (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)
       return GNUTLS_E_INVALID_REQUEST;
     }
 
-  result = _gnutls_x509_encode_and_copy_PKI_params (crq->crq,
-						    "certificationRequestInfo.subjectPKInfo",
-						    key->pk_algorithm,
-						    key->params,
-						    key->params_size);
+  result = _gnutls_x509_encode_and_copy_PKI_params
+    (crq->crq,
+     "certificationRequestInfo.subjectPKInfo",
+     key->pk_algorithm,
+     key->params,
+     key->params_size);
 
   if (result < 0)
     {
@@ -920,11 +915,12 @@ gnutls_x509_crq_set_key_rsa_raw (gnutls_x509_crq_t crq,
       goto error;
     }
 
-  result = _gnutls_x509_encode_and_copy_PKI_params (crq->crq,
-						    "certificationRequestInfo.subjectPKInfo",
-						    GNUTLS_PK_RSA,
-						    temp_params,
-						    RSA_PUBLIC_PARAMS);
+  result = _gnutls_x509_encode_and_copy_PKI_params
+    (crq->crq,
+     "certificationRequestInfo.subjectPKInfo",
+     GNUTLS_PK_RSA,
+     temp_params,
+     RSA_PUBLIC_PARAMS);
 
   if (result < 0)
     {
@@ -942,16 +938,16 @@ error:
 }
 
 /**
-  * gnutls_x509_crq_set_challenge_password - This function will set a challenge password 
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @pass: holds a null terminated password
-  *
-  * This function will set a challenge password to be used when revoking the request.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_set_challenge_password - set a challenge password
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @pass: holds a zero-terminated password
+ *
+ * This function will set a challenge password to be used when
+ * revoking the request.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_set_challenge_password (gnutls_x509_crq_t crq,
 					const char *pass)
@@ -994,7 +990,7 @@ gnutls_x509_crq_set_challenge_password (gnutls_x509_crq_t crq,
  * gnutls_x509_crq_sign2 - Sign a Certificate request with a key
  * @crq: should contain a #gnutls_x509_crq_t structure
  * @key: holds a private key
- * @dig: The message digest to use, %GNUTLS_DIG_SHA1 is the safe choice unless you know what you're doing.
+ * @dig: The message digest to use, i.e., %GNUTLS_DIG_SHA1
  * @flags: must be 0
  *
  * This function will sign the certificate request with a private key.
@@ -1006,9 +1002,9 @@ gnutls_x509_crq_set_challenge_password (gnutls_x509_crq_t crq,
  * since all the previously set parameters are now signed.
  *
  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
- * %GNUTLS_E_ASN1_VALUE_NOT_FOUND is returned if you didn't set all
- * information in the certificate request (e.g., the version using
- * gnutls_x509_crq_set_version()).
+ *   %GNUTLS_E_ASN1_VALUE_NOT_FOUND is returned if you didn't set all
+ *   information in the certificate request (e.g., the version using
+ *   gnutls_x509_crq_set_version()).
  *
  **/
 int
@@ -1076,17 +1072,16 @@ gnutls_x509_crq_sign2 (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key,
 }
 
 /**
-  * gnutls_x509_crq_sign - This function will sign a Certificate request with a key
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @key: holds a private key
-  *
-  * This function is the same a gnutls_x509_crq_sign2() with no flags, and
-  * SHA1 as the hash algorithm.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crq_sign - sign a Certificate request with a key
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @key: holds a private key
+ *
+ * This function is the same a gnutls_x509_crq_sign2() with no flags,
+ * and SHA1 as the hash algorithm.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crq_sign (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)
 {
@@ -1094,26 +1089,26 @@ gnutls_x509_crq_sign (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)
 }
 
 /**
-  * gnutls_x509_crq_export - Export the generated certificate request
-  * @crq: Holds the request
-  * @format: the format of output params. One of PEM or DER.
-  * @output_data: will contain a certificate request PEM or DER encoded
-  * @output_data_size: holds the size of output_data (and will be
-  *   replaced by the actual size of parameters)
-  *
-  * This function will export the certificate request to a PKCS10
-  *
-  * If the buffer provided is not long enough to hold the output, then
-  * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned and
-  * *output_data_size will be updated.
-  *
-  * If the structure is PEM encoded, it will have a header of "BEGIN
-  * NEW CERTIFICATE REQUEST".
-  *
-  * Return value: In case of failure a negative value will be
-  *   returned, and 0 on success.
-  *
-  **/
+ * gnutls_x509_crq_export - Export the generated certificate request
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @format: the format of output params. One of PEM or DER.
+ * @output_data: will contain a certificate request PEM or DER encoded
+ * @output_data_size: holds the size of output_data (and will be
+ *   replaced by the actual size of parameters)
+ *
+ * This function will export the certificate request to a PEM or DER
+ * encoded PKCS10 structure.
+ *
+ * If the buffer provided is not long enough to hold the output, then
+ * %GNUTLS_E_SHORT_MEMORY_BUFFER will be returned and
+ * *@output_data_size will be updated.
+ *
+ * If the structure is PEM encoded, it will have a header of "BEGIN
+ * NEW CERTIFICATE REQUEST".
+ *
+ * Return value: In case of failure a negative value will be
+ *   returned, and 0 on success.
+ **/
 int
 gnutls_x509_crq_export (gnutls_x509_crq_t crq,
 			gnutls_x509_crt_fmt_t format, void *output_data,
@@ -1130,21 +1125,20 @@ gnutls_x509_crq_export (gnutls_x509_crq_t crq,
 }
 
 /**
-  * gnutls_x509_crq_get_pk_algorithm - This function returns the certificate request's PublicKey algorithm
-  * @crq: should contain a gnutls_x509_crq_t structure
-  * @bits: if bits is non null it will hold the size of the parameters' in bits
-  *
-  * This function will return the public key algorithm of a PKCS \#10 
-  * certificate request.
-  *
-  * If bits is non null, it should have enough size to hold the parameters
-  * size in bits. For RSA the bits returned is the modulus. 
-  * For DSA the bits returned are of the public
-  * exponent.
-  *
-  * Returns: a member of the #gnutls_pk_algorithm_t enumeration on
-  *   success, or a negative value on error.
-  **/
+ * gnutls_x509_crq_get_pk_algorithm - get certificate request public key algorithm
+ * @crq: should contain a #gnutls_x509_crq_t structure
+ * @bits: if bits is non-%NULL it will hold the size of the parameters' in bits
+ *
+ * This function will return the public key algorithm of a PKCS#10
+ * certificate request.
+ *
+ * If bits is non-%NULL, it should have enough size to hold the
+ * parameters size in bits.  For RSA the bits returned is the modulus.
+ * For DSA the bits returned are of the public exponent.
+ *
+ * Returns: a member of the #gnutls_pk_algorithm_t enumeration on
+ *   success, or a negative value on error.
+ **/
 int
 gnutls_x509_crq_get_pk_algorithm (gnutls_x509_crq_t crq, unsigned int *bits)
 {
@@ -1156,10 +1150,8 @@ gnutls_x509_crq_get_pk_algorithm (gnutls_x509_crq_t crq, unsigned int *bits)
       return GNUTLS_E_INVALID_REQUEST;
     }
 
-  result =
-    _gnutls_x509_get_pk_algorithm (crq->crq,
-				   "certificationRequestInfo.subjectPKInfo",
-				   bits);
+  result = _gnutls_x509_get_pk_algorithm
+    (crq->crq, "certificationRequestInfo.subjectPKInfo", bits);
   if (result < 0)
     {
       gnutls_assert ();
@@ -1833,7 +1825,7 @@ gnutls_x509_crq_get_extension_by_oid (gnutls_x509_crq_t crq,
 
 /**
  * gnutls_x509_crq_set_subject_alt_name - Set the subject Alternative Name
- * @crq: a certificate of type #gnutls_x509_crq_t
+ * @crq: a certificate request of type #gnutls_x509_crq_t
  * @nt: is one of the #gnutls_x509_subject_alt_name_t enumerations
  * @data: The data to be set
  * @data_size: The size of data to be set
@@ -1841,7 +1833,7 @@ gnutls_x509_crq_get_extension_by_oid (gnutls_x509_crq_t crq,
  *   %GNUTLS_FSAN_APPEND to append.
  *
  * This function will set the subject alternative name certificate
- * extension. It can set the following types:
+ * extension.  It can set the following types:
  *
  * &GNUTLS_SAN_DNSNAME: as a text string
  *
@@ -1945,8 +1937,8 @@ finish:
 
 /**
  * gnutls_x509_crq_set_basic_constraints - Set the basicConstraints extension
- * @crq: a certificate of type #gnutls_x509_crq_t
- * @ca: true(1) or false(0). Depending on the Certificate authority status.
+ * @crq: a certificate request of type #gnutls_x509_crq_t
+ * @ca: true(1) or false(0) depending on the Certificate authority status.
  * @pathLenConstraint: non-negative values indicate maximum length of path,
  *   and negative values indicate that the pathLenConstraints field should
  *   not be present.
@@ -1996,7 +1988,7 @@ gnutls_x509_crq_set_basic_constraints (gnutls_x509_crq_t crq,
 
 /**
  * gnutls_x509_crq_set_key_usage - Set the keyUsage extension
- * @crq: a certificate of type #gnutls_x509_crq_t
+ * @crq: a certificate request of type #gnutls_x509_crq_t
  * @usage: an ORed sequence of the GNUTLS_KEY_* elements.
  *
  * This function will set the keyUsage certificate extension.
@@ -2043,20 +2035,18 @@ gnutls_x509_crq_set_key_usage (gnutls_x509_crq_t crq, unsigned int usage)
 /**
  * gnutls_x509_crq_get_key_purpose_oid - get Certificate's key purpose OIDs
  * @crq: should contain a #gnutls_x509_crq_t structure
- * @indx: This specifies which OID to return. Use zero to get the first one.
- * @oid: a pointer to a buffer to hold the OID (may be null)
+ * @indx: This specifies which OID to return, use zero to get the first one
+ * @oid: a pointer to a buffer to hold the OID (may be %NULL)
  * @sizeof_oid: initially holds the size of @oid
- * @critical: output variable with critical flag, may be NULL.
+ * @critical: output variable with critical flag, may be %NULL.
  *
  * This function will extract the key purpose OIDs of the Certificate
- * specified by the given index.  These are stored in the Extended
- * Key Usage extension (2.5.29.37).  See the GNUTLS_KP_* definitions
- * for human readable names.
- *
- * If @oid is null then only the size will be filled.
+ * specified by the given index.  These are stored in the Extended Key
+ * Usage extension (2.5.29.37).  See the GNUTLS_KP_* definitions for
+ * human readable names.
  *
  * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is
- *   not long enough, and in that case the *sizeof_oid will be
+ *   not long enough, and in that case the *@sizeof_oid will be
  *   updated with the required size.  On success 0 is returned.
  *
  * Since: 2.8.0
@@ -2151,7 +2141,7 @@ gnutls_x509_crq_get_key_purpose_oid (gnutls_x509_crq_t crq,
 /**
  * gnutls_x509_crq_set_key_purpose_oid - Sets the Certificate's key purpose OIDs
  * @crq: a certificate of type #gnutls_x509_crq_t
- * @oid: a pointer to a null terminated string that holds the OID
+ * @oid: a pointer to a zero-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.
@@ -2173,7 +2163,7 @@ gnutls_x509_crq_set_key_purpose_oid (gnutls_x509_crq_t crq,
   gnutls_datum_t prev = { NULL, 0 }, der_data;
   ASN1_TYPE c2 = ASN1_TYPE_EMPTY;
 
-  /* Check if the extension already exists.
+  /* Read existing extension, if there is one.
    */
   result = gnutls_x509_crq_get_extension_by_oid (crq, "2.5.29.37", 0,
 						 NULL, &prev.size,
@@ -2181,7 +2171,7 @@ gnutls_x509_crq_set_key_purpose_oid (gnutls_x509_crq_t crq,
   switch (result)
     {
     case GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE:
-      /* Replacing non-existing data means the same as set data. */
+      /* No existing extension, that's fine. */
       break;
 
     case GNUTLS_E_SUCCESS:
@@ -2341,18 +2331,18 @@ cleanup:
 
 /**
  * gnutls_x509_crq_get_key_id - Return unique ID of public key's parameters
- * @crq: Holds the certificate signing request
+ * @crq: a certificate of type #gnutls_x509_crq_t
  * @flags: should be 0 for now
  * @output_data: will contain the key ID
  * @output_data_size: holds the size of output_data (and will be
  *   replaced by the actual size of parameters)
  *
- * This function will return a unique ID the depends on the public
- * key parameters. This ID can be used in checking whether a
- * certificate corresponds to the given private key.
+ * This function will return a unique ID the depends on the public key
+ * parameters.  This ID can be used in checking whether a certificate
+ * corresponds to the given private key.
  *
  * If the buffer provided is not long enough to hold the output, then
- * *output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
+ * *@output_data_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER will
  * be returned.  The output will normally be a SHA-1 hash output,
  * which is 20 bytes.
  *