Doc fixes (silence gtk-doc warnings).

5 files changed, 428 insertions, 434 deletions

diff --git a/lib/x509/crl.c b/lib/x509/crl.c
index 34fa53d4f2..10677cb137 100644
--- a/lib/x509/crl.c
+++ b/lib/x509/crl.c
@@ -35,19 +35,18 @@
 #include <x509_int.h>
 
 /**
-  * gnutls_x509_crl_init - This function initializes a gnutls_x509_crl_t structure
-  * @crl: The structure to be initialized
-  *
-  * This function will initialize a CRL structure. CRL stands for
-  * Certificate Revocation List. A revocation list usually contains
-  * lists of certificate serial numbers that have been revoked
-  * by an Authority. The revocation lists are always signed with
-  * the authority's private key.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crl_init - initializes a #gnutls_x509_crl_t structure
+ * @crl: The structure to be initialized
+ *
+ * This function will initialize a CRL structure. CRL stands for
+ * Certificate Revocation List. A revocation list usually contains
+ * lists of certificate serial numbers that have been revoked by an
+ * Authority. The revocation lists are always signed with the
+ * authority's private key.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crl_init (gnutls_x509_crl_t * crl)
 {
@@ -70,12 +69,11 @@ gnutls_x509_crl_init (gnutls_x509_crl_t * crl)
 }
 
 /**
-  * gnutls_x509_crl_deinit - This function deinitializes memory used by a gnutls_x509_crl_t structure
-  * @crl: The structure to be initialized
-  *
-  * This function will deinitialize a CRL structure. 
-  *
-  **/
+ * gnutls_x509_crl_deinit - deinitializes a #gnutls_x509_crl_t structure
+ * @crl: The structure to be initialized
+ *
+ * This function will deinitialize a CRL structure.
+ **/
 void
 gnutls_x509_crl_deinit (gnutls_x509_crl_t crl)
 {
@@ -89,20 +87,19 @@ gnutls_x509_crl_deinit (gnutls_x509_crl_t crl)
 }
 
 /**
-  * gnutls_x509_crl_import - This function will import a DER or PEM encoded CRL
-  * @crl: The structure to store the parsed CRL.
-  * @data: The DER or PEM encoded CRL.
-  * @format: One of DER or PEM
-  *
-  * This function will convert the given DER or PEM encoded CRL
-  * to the native gnutls_x509_crl_t format. The output will be stored in 'crl'.
-  *
-  * If the CRL is PEM encoded it should have a header of "X509 CRL".
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_x509_crl_import - import a DER or PEM encoded CRL
+ * @crl: The structure to store the parsed CRL.
+ * @data: The DER or PEM encoded CRL.
+ * @format: One of DER or PEM
+ *
+ * This function will convert the given DER or PEM encoded CRL
+ * to the native #gnutls_x509_crl_t format. The output will be stored in 'crl'.
+ *
+ * If the CRL is PEM encoded it should have a header of "X509 CRL".
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crl_import (gnutls_x509_crl_t crl,
 			const gnutls_datum_t * data,
@@ -164,22 +161,23 @@ cleanup:
 
 
 /**
-  * gnutls_x509_crl_get_issuer_dn - This function returns the CRL's issuer distinguished name
-  * @crl: should contain a gnutls_x509_crl_t structure
-  * @buf: a pointer to a structure to hold the peer's name (may be null)
-  * @sizeof_buf: initially holds the size of @buf
-  *
-  * This function will copy the name of the CRL issuer 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, and
-  * 0 on success.
-  *
-  **/
+ * gnutls_x509_crl_get_issuer_dn - returns the CRL's issuer distinguished name
+ * @crl: should contain a gnutls_x509_crl_t structure
+ * @buf: a pointer to a structure to hold the peer's name (may be null)
+ * @sizeof_buf: initially holds the size of @buf
+ *
+ * This function will copy the name of the CRL issuer 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, and 0 on success.
+ *
+ **/
 int
 gnutls_x509_crl_get_issuer_dn (const gnutls_x509_crl_t crl, char *buf,
 			       size_t * sizeof_buf)
@@ -196,30 +194,31 @@ gnutls_x509_crl_get_issuer_dn (const gnutls_x509_crl_t crl, char *buf,
 }
 
 /**
-  * gnutls_x509_crl_get_issuer_dn_by_oid - This function returns the CRL's issuer distinguished name
-  * @crl: should contain a gnutls_x509_crl_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 peer's name (may be null)
-  * @sizeof_buf: initially holds the size of @buf
-  *
-  * This function will extract the part of the name of the CRL issuer 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,
-  * and 0 on success.
-  *
-  **/
+ * gnutls_x509_crl_get_issuer_dn_by_oid - return the CRL's issuer distinguished name
+ * @crl: should contain a gnutls_x509_crl_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 peer's name (may be null)
+ * @sizeof_buf: initially holds the size of @buf
+ *
+ * This function will extract the part of the name of the CRL issuer
+ * 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, and 0 on success.
+ **/
 int
 gnutls_x509_crl_get_issuer_dn_by_oid (gnutls_x509_crl_t crl,
 				      const char *oid, int indx,
@@ -238,22 +237,21 @@ gnutls_x509_crl_get_issuer_dn_by_oid (gnutls_x509_crl_t crl,
 }
 
 /**
-  * gnutls_x509_crl_get_dn_oid - This function returns the Certificate request issuer's distinguished name OIDs
-  * @crl: should contain a gnutls_x509_crl_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 CRL issuer, 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_crl_get_dn_oid - returns the Certificate request issuer's distinguished name OIDs
+ * @crl: should contain a gnutls_x509_crl_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 CRL
+ * issuer, 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.
+ **/
 int
 gnutls_x509_crl_get_dn_oid (gnutls_x509_crl_t crl,
 			    int indx, void *oid, size_t * sizeof_oid)
@@ -271,15 +269,15 @@ gnutls_x509_crl_get_dn_oid (gnutls_x509_crl_t crl,
 
 
 /**
-  * gnutls_x509_crl_get_signature_algorithm - This function returns the CRL's signature algorithm
-  * @crl: should contain a gnutls_x509_crl_t structure
-  *
-  * This function will return a value of the gnutls_sign_algorithm_t enumeration that 
-  * is the signature algorithm. 
-  *
-  * Returns a negative value on error.
-  *
-  **/
+ * gnutls_x509_crl_get_signature_algorithm - returns the CRL's signature algorithm
+ * @crl: should contain a #gnutls_x509_crl_t structure
+ *
+ * This function will return a value of the #gnutls_sign_algorithm_t
+ * enumeration that is the signature algorithm.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_x509_crl_get_signature_algorithm (gnutls_x509_crl_t crl)
 {
@@ -370,14 +368,13 @@ gnutls_x509_crl_get_signature (gnutls_x509_crl_t crl,
 }
 
 /**
-  * gnutls_x509_crl_get_version - This function returns the CRL's version number
-  * @crl: should contain a gnutls_x509_crl_t structure
-  *
-  * This function will return the version of the specified CRL.
-  *
-  * Returns a negative value on error.
-  *
-  **/
+ * gnutls_x509_crl_get_version - returns the CRL's version number
+ * @crl: should contain a #gnutls_x509_crl_t structure
+ *
+ * This function will return the version of the specified CRL.
+ *
+ * Returns: The version number, or a negative value on error.
+ **/
 int
 gnutls_x509_crl_get_version (gnutls_x509_crl_t crl)
 {
@@ -403,14 +400,13 @@ gnutls_x509_crl_get_version (gnutls_x509_crl_t crl)
 }
 
 /**
-  * gnutls_x509_crl_get_this_update - This function returns the CRL's thisUpdate time
-  * @crl: should contain a gnutls_x509_crl_t structure
-  *
-  * This function will return the time this CRL was issued.
-  *
-  * Returns (time_t)-1 on error.
-  *
-  **/
+ * gnutls_x509_crl_get_this_update - return the CRL's thisUpdate time
+ * @crl: should contain a #gnutls_x509_crl_t structure
+ *
+ * This function will return the time this CRL was issued.
+ *
+ * Returns: when the CRL was issued, or (time_t)-1 on error.
+ **/
 time_t
 gnutls_x509_crl_get_this_update (gnutls_x509_crl_t crl)
 {
@@ -424,16 +420,15 @@ gnutls_x509_crl_get_this_update (gnutls_x509_crl_t crl)
 }
 
 /**
-  * gnutls_x509_crl_get_next_update - This function returns the CRL's nextUpdate time
-  * @crl: should contain a gnutls_x509_crl_t structure
-  *
-  * This function will return the time the next CRL will be issued.
-  * This field is optional in a CRL so it might be normal to get
-  * an error instead.
-  *
-  * Returns (time_t)-1 on error.
-  *
-  **/
+ * gnutls_x509_crl_get_next_update - return the CRL's nextUpdate time
+ * @crl: should contain a #gnutls_x509_crl_t structure
+ *
+ * This function will return the time the next CRL will be issued.
+ * This field is optional in a CRL so it might be normal to get an
+ * error instead.
+ *
+ * Returns: when the next CRL will be issued, or (time_t)-1 on error.
+ **/
 time_t
 gnutls_x509_crl_get_next_update (gnutls_x509_crl_t crl)
 {
@@ -447,15 +442,14 @@ gnutls_x509_crl_get_next_update (gnutls_x509_crl_t crl)
 }
 
 /**
-  * gnutls_x509_crl_get_crt_count - This function returns the number of revoked certificates in a CRL
-  * @crl: should contain a gnutls_x509_crl_t structure
-  *
-  * This function will return the number of revoked certificates in the
-  * given CRL.
-  *
-  * Returns a negative value on failure.
-  *
-  **/
+ * gnutls_x509_crl_get_crt_count - get number of revoked certificates in a CRL
+ * @crl: should contain a #gnutls_x509_crl_t structure
+ *
+ * This function will return the number of revoked certificates in the
+ * given CRL.
+ *
+ * Returns: number of certificates, a negative value on failure.
+ **/
 int
 gnutls_x509_crl_get_crt_count (gnutls_x509_crl_t crl)
 {
@@ -482,19 +476,19 @@ gnutls_x509_crl_get_crt_count (gnutls_x509_crl_t crl)
 }
 
 /**
-  * gnutls_x509_crl_get_crt_serial - This function returns the serial number of a revoked certificate
-  * @crl: should contain a gnutls_x509_crl_t structure
-  * @indx: the index of the certificate to extract (starting from 0)
-  * @serial: where the serial number will be copied
-  * @serial_size: initially holds the size of serial
-  * @t: if non null, will hold the time this certificate was revoked
-  *
-  * This function will return the serial number of the specified, by
-  * the index, revoked certificate.
-  *
-  * Returns a negative value on failure.
-  *
-  **/
+ * gnutls_x509_crl_get_crt_serial - get the serial number of a revoked certificate
+ * @crl: should contain a #gnutls_x509_crl_t structure
+ * @indx: the index of the certificate to extract (starting from 0)
+ * @serial: where the serial number will be copied
+ * @serial_size: initially holds the size of serial
+ * @t: if non null, will hold the time this certificate was revoked
+ *
+ * This function will retrieve the serial number of the specified, by
+ * the index, revoked certificate.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. and a negative value on error.
+ **/
 int
 gnutls_x509_crl_get_crt_serial (gnutls_x509_crl_t crl, int indx,
 				unsigned char *serial,
@@ -614,24 +608,24 @@ cleanup:
 }
 
 /**
-  * gnutls_x509_crl_export - This function will export the CRL
-  * @crl: Holds the revocation list
-  * @format: the format of output params. One of PEM or DER.
-  * @output_data: will contain a private key 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 revocation list to DER or PEM format.
-  *
-  * If the buffer provided is not long enough to hold the output, then
-  * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
-  *
-  * If the structure is PEM encoded, it will have a header
-  * of "BEGIN X509 CRL".
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value. and a negative value on failure.
-  *
-  **/
+ * gnutls_x509_crl_export - export the CRL
+ * @crl: Holds the revocation list
+ * @format: the format of output params. One of PEM or DER.
+ * @output_data: will contain a private key 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 revocation list to DER or PEM format.
+ *
+ * If the buffer provided is not long enough to hold the output, then
+ * ¤GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
+ *
+ * If the structure is PEM encoded, it will have a header
+ * of "BEGIN X509 CRL".
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. and a negative value on failure.
+ **/
 int
 gnutls_x509_crl_export (gnutls_x509_crl_t crl,
 			gnutls_x509_crt_fmt_t format, void *output_data,
diff --git a/lib/x509/crq.c b/lib/x509/crq.c
index 7ad60e1fa8..6aaaf83f4c 100644
--- a/lib/x509/crq.c
+++ b/lib/x509/crq.c
@@ -181,7 +181,7 @@ cleanup:
   *
   * If @buf is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -223,7 +223,7 @@ gnutls_x509_crq_get_dn (gnutls_x509_crq_t crq, char *buf, size_t * sizeof_buf)
   *
   * If @buf is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -256,7 +256,7 @@ gnutls_x509_crq_get_dn_by_oid (gnutls_x509_crq_t crq, const char *oid,
   *
   * If oid is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -608,8 +608,8 @@ gnutls_x509_crq_set_version (gnutls_x509_crq_t crq, unsigned int version)
   *
   * This function will return the version of the specified Certificate request.
   *
-  * Returns a negative value on error.
-  *
+  * Returns: version of certificate request, or a negative value on
+  *   error.
   **/
 int
 gnutls_x509_crq_get_version (gnutls_x509_crq_t crq)
@@ -878,9 +878,8 @@ gnutls_x509_crq_export (gnutls_x509_crq_t crq,
   * 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.
-  *
+  * 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)
diff --git a/lib/x509/pkcs12_bag.c b/lib/x509/pkcs12_bag.c
index c1c9885cfe..42bc8f2075 100644
--- a/lib/x509/pkcs12_bag.c
+++ b/lib/x509/pkcs12_bag.c
@@ -327,18 +327,17 @@ cleanup:
 
 
 /**
-  * gnutls_pkcs12_bag_set_data - This function inserts data into the bag
-  * @bag: The bag
-  * @type: The data's type
-  * @data: the data to be copied.
-  *
-  * This function will insert the given data of the given type into the
-  * bag. 
-  *
-  * Returns the index of the added bag on success, or a negative
-  * value on error.
-  *
-  **/
+ * gnutls_pkcs12_bag_set_data - This function inserts data into the bag
+ * @bag: The bag
+ * @type: The data's type
+ * @data: the data to be copied.
+ *
+ * This function will insert the given data of the given type into
+ * the bag.
+ *
+ * Returns: the index of the added bag on success, or a negative
+ * value on error.
+ **/
 int
 gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t bag,
 			    gnutls_pkcs12_bag_type_t type,
@@ -391,17 +390,16 @@ gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t bag,
 }
 
 /**
-  * gnutls_pkcs12_bag_set_crt - This function inserts a certificate into the bag
-  * @bag: The bag
-  * @crt: the certificate to be copied.
-  *
-  * This function will insert the given certificate into the
-  * bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().
-  *
-  * Returns the index of the added bag on success, or a negative
-  * value on failure.
-  *
-  **/
+ * gnutls_pkcs12_bag_set_crt - This function inserts a certificate into the bag
+ * @bag: The bag
+ * @crt: the certificate to be copied.
+ *
+ * This function will insert the given certificate into the
+ * bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().
+ *
+ * Returns: the index of the added bag on success, or a negative
+ * value on failure.
+ **/
 int
 gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t bag, gnutls_x509_crt_t crt)
 {
@@ -429,17 +427,16 @@ gnutls_pkcs12_bag_set_crt (gnutls_pkcs12_bag_t bag, gnutls_x509_crt_t crt)
 }
 
 /**
-  * gnutls_pkcs12_bag_set_crl - This function inserts the CRL into the bag
-  * @bag: The bag
-  * @crl: the CRL to be copied.
-  *
-  * This function will insert the given CRL into the
-  * bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().
-  *
-  * Returns the index of the added bag on success, or a negative
-  * value on failure.
-  *
-  **/
+ * gnutls_pkcs12_bag_set_crl - insert the CRL into the bag
+ * @bag: The bag
+ * @crl: the CRL to be copied.
+ *
+ * This function will insert the given CRL into the
+ * bag. This is just a wrapper over gnutls_pkcs12_bag_set_data().
+ *
+ * Returns: the index of the added bag on success, or a negative value
+ * on failure.
+ **/
 int
 gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t bag, gnutls_x509_crl_t crl)
 {
diff --git a/lib/x509/pkcs7.c b/lib/x509/pkcs7.c
index a9acb63c1c..02b7305e9b 100644
--- a/lib/x509/pkcs7.c
+++ b/lib/x509/pkcs7.c
@@ -138,17 +138,16 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_init - This function initializes a gnutls_pkcs7_t structure
-  * @pkcs7: The structure to be initialized
-  *
-  * This function will initialize a PKCS7 structure. PKCS7 structures
-  * usually contain lists of X.509 Certificates and X.509 Certificate
-  * revocation lists.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_pkcs7_init - initialize a #gnutls_pkcs7_t structure
+ * @pkcs7: The structure to be initialized
+ *
+ * This function will initialize a PKCS7 structure. PKCS7 structures
+ * usually contain lists of X.509 Certificates and X.509 Certificate
+ * revocation lists.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_init (gnutls_pkcs7_t * pkcs7)
 {
@@ -171,12 +170,11 @@ gnutls_pkcs7_init (gnutls_pkcs7_t * pkcs7)
 }
 
 /**
-  * gnutls_pkcs7_deinit - This function deinitializes memory used by a gnutls_pkcs7_t structure
-  * @pkcs7: The structure to be initialized
-  *
-  * This function will deinitialize a PKCS7 structure. 
-  *
-  **/
+ * gnutls_pkcs7_deinit - deinitializes a #gnutls_pkcs7_t structure
+ * @pkcs7: The structure to be initialized
+ *
+ * This function will deinitialize a PKCS7 structure.
+ **/
 void
 gnutls_pkcs7_deinit (gnutls_pkcs7_t pkcs7)
 {
@@ -190,20 +188,20 @@ gnutls_pkcs7_deinit (gnutls_pkcs7_t pkcs7)
 }
 
 /**
-  * gnutls_pkcs7_import - This function will import a DER or PEM encoded PKCS7
-  * @pkcs7: The structure to store the parsed PKCS7.
-  * @data: The DER or PEM encoded PKCS7.
-  * @format: One of DER or PEM
-  *
-  * This function will convert the given DER or PEM encoded PKCS7
-  * to the native gnutls_pkcs7_t format. The output will be stored in 'pkcs7'.
-  *
-  * If the PKCS7 is PEM encoded it should have a header of "PKCS7".
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_pkcs7_import - import a DER or PEM encoded PKCS7
+ * @pkcs7: The structure to store the parsed PKCS7.
+ * @data: The DER or PEM encoded PKCS7.
+ * @format: One of DER or PEM
+ *
+ * This function will convert the given DER or PEM encoded PKCS7 to
+ * the native #gnutls_pkcs7_t format.  The output will be stored in
+ * 'pkcs7'.
+ *
+ * If the PKCS7 is PEM encoded it should have a header of "PKCS7".
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_import (gnutls_pkcs7_t pkcs7, const gnutls_datum_t * data,
 		     gnutls_x509_crt_fmt_t format)
@@ -261,21 +259,24 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_get_crt_raw - This function returns a certificate in a PKCS7 certificate set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @indx: contains the index of the certificate to extract
-  * @certificate: the contents of the certificate will be copied there (may be null)
-  * @certificate_size: should hold the size of the certificate
-  *
-  * This function will return a certificate of the PKCS7 or RFC2630 certificate set.
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value. If the provided buffer is not long enough,
-  * then @certificate_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER is returned.
-  *
-  * After the last certificate has been read GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
-  * will be returned.
-  *
-  **/
+ * gnutls_pkcs7_get_crt_raw - get a certificate from a PKCS7 certificate set
+ * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
+ * @indx: contains the index of the certificate to extract
+ * @certificate: the contents of the certificate will be copied
+ *   there (may be null)
+ * @certificate_size: should hold the size of the certificate
+ *
+ * This function will return a certificate of the PKCS7 or RFC2630
+ * certificate set.
+ *
+ * After the last certificate has been read
+ * %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.  If the provided buffer is not long enough,
+ *   then @certificate_size is updated and
+ *   %GNUTLS_E_SHORT_MEMORY_BUFFER is returned.
+ **/
 int
 gnutls_pkcs7_get_crt_raw (gnutls_pkcs7_t pkcs7,
 			  int indx, void *certificate,
@@ -367,15 +368,15 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_get_crt_count - This function returns the number of certificates in a PKCS7 certificate set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  *
-  * This function will return the number of certifcates in the PKCS7 or 
-  * RFC2630 certificate set.
-  *
-  * Returns a negative value on failure.
-  *
-  **/
+ * gnutls_pkcs7_get_crt_count - return the number of certificates in a PKCS7 certificate set
+ * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
+ *
+ * This function will return the number of certifcates in the PKCS7
+ * or RFC2630 certificate set.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t pkcs7)
 {
@@ -411,25 +412,24 @@ gnutls_pkcs7_get_crt_count (gnutls_pkcs7_t pkcs7)
 }
 
 /**
-  * gnutls_pkcs7_export - This function will export the pkcs7 structure
-  * @pkcs7: Holds the pkcs7 structure
-  * @format: the format of output params. One of PEM or DER.
-  * @output_data: will contain a structure 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 pkcs7 structure to DER or PEM format.
-  *
-  * 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
-  * be returned.
-  *
-  * If the structure is PEM encoded, it will have a header
-  * of "BEGIN PKCS7".
-  *
-  * Return value: In case of failure a negative value will be
-  *   returned, and 0 on success.
-  *
+ * gnutls_pkcs7_export - export the pkcs7 structure
+ * @pkcs7: Holds the pkcs7 structure
+ * @format: the format of output params. One of PEM or DER.
+ * @output_data: will contain a structure 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 pkcs7 structure to DER or PEM format.
+ *
+ * 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 be returned.
+ *
+ * If the structure is PEM encoded, it will have a header
+ * of "BEGIN PKCS7".
+ *
+ * Return value: In case of failure a negative value will be
+ *   returned, and 0 on success.
   **/
 int
 gnutls_pkcs7_export (gnutls_pkcs7_t pkcs7,
@@ -524,15 +524,16 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_set_crt_raw - This function adds a certificate in a PKCS7 certificate set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @crt: the DER encoded certificate to be added
-  *
-  * This function will add a certificate to the PKCS7 or RFC2630 certificate set.
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_pkcs7_set_crt_raw - add a certificate in a PKCS7 certificate set
+ * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
+ * @crt: the DER encoded certificate to be added
+ *
+ * This function will add a certificate to the PKCS7 or RFC2630
+ * certificate set.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_set_crt_raw (gnutls_pkcs7_t pkcs7, const gnutls_datum_t * crt)
 {
@@ -617,16 +618,16 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_set_crt - This function adds a parsed certificate in a PKCS7 certificate set
+  * gnutls_pkcs7_set_crt - add a parsed certificate in a PKCS7 certificate set
   * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
   * @crt: the certificate to be copied.
   *
-  * This function will add a parsed certificate to the PKCS7 or RFC2630 certificate set.
-  * This is a wrapper function over gnutls_pkcs7_set_crt_raw() .
+  * This function will add a parsed certificate to the PKCS7 or
+  * RFC2630 certificate set.  This is a wrapper function over
+  * gnutls_pkcs7_set_crt_raw() .
   *
   * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
   *   negative error value.
-  *
   **/
 int
 gnutls_pkcs7_set_crt (gnutls_pkcs7_t pkcs7, gnutls_x509_crt_t crt)
@@ -659,14 +660,16 @@ gnutls_pkcs7_set_crt (gnutls_pkcs7_t pkcs7, gnutls_x509_crt_t crt)
 
 
 /**
-  * gnutls_pkcs7_delete_crt - This function deletes a certificate from a PKCS7 certificate set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @indx: the index of the certificate to delete
-  *
-  * This function will delete a certificate from a PKCS7 or RFC2630 certificate set.
-  * Index starts from 0. Returns 0 on success.
-  *
-  **/
+ * gnutls_pkcs7_delete_crt - deletes a certificate from a PKCS7 certificate set
+ * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
+ * @indx: the index of the certificate to delete
+ *
+ * This function will delete a certificate from a PKCS7 or RFC2630
+ * certificate set.  Index starts from 0. Returns 0 on success.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_delete_crt (gnutls_pkcs7_t pkcs7, int indx)
 {
@@ -723,21 +726,20 @@ cleanup:
  */
 
 /**
-  * gnutls_pkcs7_get_crl_raw - This function returns a crl in a PKCS7 crl set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @indx: contains the index of the crl to extract
-  * @crl: the contents of the crl will be copied there (may be null)
-  * @crl_size: should hold the size of the crl
-  *
-  * This function will return a crl of the PKCS7 or RFC2630 crl set.
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value. If the provided buffer is not long enough,
-  * then @crl_size is updated and GNUTLS_E_SHORT_MEMORY_BUFFER is returned.
-  *
-  * After the last crl has been read GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
-  * will be returned.
-  *
-  **/
+ * gnutls_pkcs7_get_crl_raw - This function returns a crl in a PKCS7 crl set
+ * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
+ * @indx: contains the index of the crl to extract
+ * @crl: the contents of the crl will be copied there (may be null)
+ * @crl_size: should hold the size of the crl
+ *
+ * This function will return a crl of the PKCS7 or RFC2630 crl set.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.  If the provided buffer is not long enough,
+ *   then @crl_size is updated and %GNUTLS_E_SHORT_MEMORY_BUFFER is
+ *   returned.  After the last crl has been read
+ *   %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
+ **/
 int
 gnutls_pkcs7_get_crl_raw (gnutls_pkcs7_t pkcs7,
 			  int indx, void *crl, size_t * crl_size)
@@ -801,15 +803,15 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_get_crl_count - This function returns the number of crls in a PKCS7 crl set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  *
-  * This function will return the number of certifcates in the PKCS7 or 
-  * RFC2630 crl set.
-  *
-  * Returns a negative value on failure.
-  *
-  **/
+ * gnutls_pkcs7_get_crl_count - returns the number of CRLs in a PKCS7 crl set
+ * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
+ *
+ * This function will return the number of certifcates in the PKCS7
+ * or RFC2630 crl set.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t pkcs7)
 {
@@ -845,15 +847,15 @@ gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t pkcs7)
 }
 
 /**
-  * gnutls_pkcs7_set_crl_raw - This function adds a crl in a PKCS7 crl set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @crl: the DER encoded crl to be added
-  *
-  * This function will add a crl to the PKCS7 or RFC2630 crl set.
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_pkcs7_set_crl_raw - add a crl in a PKCS7 crl set
+ * @pkcs7_struct: should contain #a gnutls_pkcs7_t structure
+ * @crl: the DER encoded crl to be added
+ *
+ * This function will add a crl to the PKCS7 or RFC2630 crl set.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_set_crl_raw (gnutls_pkcs7_t pkcs7, const gnutls_datum_t * crl)
 {
@@ -928,15 +930,16 @@ cleanup:
 }
 
 /**
-  * gnutls_pkcs7_set_crl - This function adds a parsed crl in a PKCS7 crl set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @crl: the DER encoded crl to be added
-  *
-  * This function will add a parsed crl to the PKCS7 or RFC2630 crl set.
-  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
-  *   negative error value.
-  *
-  **/
+ * gnutls_pkcs7_set_crl - add a parsed crl in a PKCS7 crl set
+ * @pkcs7_struct: should contain a #gnutls_pkcs7_t structure
+ * @crl: the DER encoded crl to be added
+ *
+ * This function will add a parsed CRL to the PKCS7 or RFC2630 crl
+ * set.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_set_crl (gnutls_pkcs7_t pkcs7, gnutls_x509_crl_t crl)
 {
@@ -967,14 +970,16 @@ gnutls_pkcs7_set_crl (gnutls_pkcs7_t pkcs7, gnutls_x509_crl_t crl)
 }
 
 /**
-  * gnutls_pkcs7_delete_crl - This function deletes a crl from a PKCS7 crl set
-  * @pkcs7_struct: should contain a gnutls_pkcs7_t structure
-  * @indx: the index of the crl to delete
-  *
-  * This function will delete a crl from a PKCS7 or RFC2630 crl set.
-  * Index starts from 0. Returns 0 on success.
-  *
-  **/
+ * gnutls_pkcs7_delete_crl - deletes a CRL from a PKCS7 crl set
+ * @pkcs7_struct: should contain a #gnutls_pkcs7_t structure
+ * @indx: the index of the crl to delete
+ *
+ * This function will delete a crl from a PKCS7 or RFC2630 crl set.
+ * Index starts from 0. Returns 0 on success.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
+ **/
 int
 gnutls_pkcs7_delete_crl (gnutls_pkcs7_t pkcs7, int indx)
 {
diff --git a/lib/x509/x509.c b/lib/x509/x509.c
index ca3278df92..dc131d40f7 100644
--- a/lib/x509/x509.c
+++ b/lib/x509/x509.c
@@ -236,7 +236,7 @@ cleanup:
 
 /**
   * gnutls_x509_crt_get_issuer_dn - This function returns the Certificate's issuer distinguished name
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @buf: a pointer to a structure to hold the name (may be null)
   * @sizeof_buf: initially holds the size of @buf
   *
@@ -247,7 +247,7 @@ cleanup:
   *
   * If @buf is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -269,7 +269,7 @@ gnutls_x509_crt_get_issuer_dn (gnutls_x509_crt_t cert, char *buf,
 
 /**
   * gnutls_x509_crt_get_issuer_dn_by_oid - This function returns the Certificate's issuer distinguished name
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_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.
@@ -289,7 +289,7 @@ gnutls_x509_crt_get_issuer_dn (gnutls_x509_crt_t cert, char *buf,
   *
   * If @buf is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -313,7 +313,7 @@ gnutls_x509_crt_get_issuer_dn_by_oid (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_issuer_dn_oid - This function returns the Certificate's issuer distinguished name OIDs
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_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)
   * @sizeof_oid: initially holds the size of @oid
@@ -323,7 +323,7 @@ gnutls_x509_crt_get_issuer_dn_by_oid (gnutls_x509_crt_t cert,
   *
   * If @oid is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -345,7 +345,7 @@ gnutls_x509_crt_get_issuer_dn_oid (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_dn - This function returns the Certificate's distinguished name
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @buf: a pointer to a structure to hold the name (may be null)
   * @sizeof_buf: initially holds the size of @buf
   *
@@ -356,7 +356,7 @@ gnutls_x509_crt_get_issuer_dn_oid (gnutls_x509_crt_t cert,
   *
   * If @buf is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -378,7 +378,7 @@ gnutls_x509_crt_get_dn (gnutls_x509_crt_t cert, char *buf,
 
 /**
   * gnutls_x509_crt_get_dn_by_oid - This function returns the Certificate's distinguished name
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_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.
@@ -398,7 +398,7 @@ gnutls_x509_crt_get_dn (gnutls_x509_crt_t cert, char *buf,
   *
   * If @buf is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -421,7 +421,7 @@ gnutls_x509_crt_get_dn_by_oid (gnutls_x509_crt_t cert, const char *oid,
 
 /**
   * gnutls_x509_crt_get_dn_oid - This function returns the Certificate's subject distinguished name OIDs
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_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)
   * @sizeof_oid: initially holds the size of @oid
@@ -431,7 +431,7 @@ gnutls_x509_crt_get_dn_by_oid (gnutls_x509_crt_t cert, const char *oid,
   *
   * If oid is null then only the size will be filled.
   *
-  * Returns GNUTLS_E_SHORT_MEMORY_BUFFER if the provided buffer is not
+  * 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.
   *
@@ -453,13 +453,13 @@ gnutls_x509_crt_get_dn_oid (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_signature_algorithm - This function returns the Certificate's signature algorithm
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   *
-  * This function will return a value of the gnutls_sign_algorithm_t enumeration that 
-  * is the signature algorithm. 
-  *
-  * Returns a negative value on error.
+  * This function will return a value of the #gnutls_sign_algorithm_t
+  * enumeration that is the signature algorithm.
   *
+  * Returns: a #gnutls_sign_algorithm_t value, or a negative value on
+  *   error.
   **/
 int
 gnutls_x509_crt_get_signature_algorithm (gnutls_x509_crt_t cert)
@@ -495,7 +495,7 @@ gnutls_x509_crt_get_signature_algorithm (gnutls_x509_crt_t cert)
 
 /**
  * gnutls_x509_crt_get_signature - Returns the Certificate's signature
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @sig: a pointer where the signature part will be copied (may be null).
  * @sizeof_sig: initially holds the size of @sig
  *
@@ -550,14 +550,13 @@ gnutls_x509_crt_get_signature (gnutls_x509_crt_t cert,
 }
 
 /**
-  * gnutls_x509_crt_get_version - This function returns the Certificate's version number
-  * @cert: should contain a gnutls_x509_crt_t structure
-  *
-  * This function will return the version of the specified Certificate.
-  *
-  * Returns a negative value on error.
-  *
-  **/
+ * gnutls_x509_crt_get_version - return the Certificate's version number
+ * @cert: should contain a #gnutls_x509_crt_t structure
+ *
+ * This function will return the version of the specified Certificate.
+ *
+ * Returns: version of certificate, or a negative value on error.
+ **/
 int
 gnutls_x509_crt_get_version (gnutls_x509_crt_t cert)
 {
@@ -586,12 +585,13 @@ gnutls_x509_crt_get_version (gnutls_x509_crt_t cert)
 }
 
 /**
-  * gnutls_x509_crt_get_activation_time - This function returns the Certificate's activation time
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * gnutls_x509_crt_get_activation_time - returns the Certificate's activation time
+  * @cert: should contain a #gnutls_x509_crt_t structure
   *
-  * This function will return the time this Certificate was or will be activated.
+  * This function will return the time this Certificate was or will be
+  * activated.
   *
-  * Returns (time_t)-1 on error.
+  * Returns: activation time, or (time_t)-1 on error.
   *
   **/
 time_t
@@ -608,14 +608,15 @@ gnutls_x509_crt_get_activation_time (gnutls_x509_crt_t cert)
 }
 
 /**
-  * gnutls_x509_crt_get_expiration_time - This function returns the Certificate's expiration time
-  * @cert: should contain a gnutls_x509_crt_t structure
-  *
-  * This function will return the time this Certificate was or will be expired.
-  *
-  * Returns (time_t)-1 on error.
-  *
-  **/
+ * gnutls_x509_crt_get_expiration_time - returns the Certificate's expiration time
+ * @cert: should contain a #gnutls_x509_crt_t structure
+ *
+ * This function will return the time this Certificate was or will be
+ * expired.
+ *
+ * Returns: expiration time, or (time_t)-1 on error.
+ *
+ **/
 time_t
 gnutls_x509_crt_get_expiration_time (gnutls_x509_crt_t cert)
 {
@@ -631,7 +632,7 @@ gnutls_x509_crt_get_expiration_time (gnutls_x509_crt_t cert)
 
 /**
   * gnutls_x509_crt_get_serial - This function returns the certificate's serial number
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @result: The place where the serial number will be copied
   * @result_size: Holds the size of the result field.
   *
@@ -673,7 +674,7 @@ gnutls_x509_crt_get_serial (gnutls_x509_crt_t cert, void *result,
 
 /**
   * gnutls_x509_crt_get_subject_key_id - This function returns the certificate's key identifier
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @ret: The place where the identifier will be copied
   * @ret_size: Holds the size of the result field.
   * @critical: will be non zero if the extension is marked as critical (may be null)
@@ -760,7 +761,7 @@ gnutls_x509_crt_get_subject_key_id (gnutls_x509_crt_t cert, void *ret,
 
 /**
   * gnutls_x509_crt_get_authority_key_id - This function returns the certificate authority's identifier
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @result: The place where the identifier will be copied
   * @result_size: Holds the size of the result field.
   * @critical: will be non zero if the extension is marked as critical (may be null)
@@ -848,8 +849,8 @@ gnutls_x509_crt_get_authority_key_id (gnutls_x509_crt_t cert, void *ret,
 }
 
 /**
-  * gnutls_x509_crt_get_pk_algorithm - This function returns the certificate's PublicKey algorithm
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * gnutls_x509_crt_get_pk_algorithm - return the certificate's PublicKey algorithm
+  * @cert: should contain a #gnutls_x509_crt_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 an X.509 
@@ -860,9 +861,8 @@ gnutls_x509_crt_get_authority_key_id (gnutls_x509_crt_t cert, void *ret,
   * 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.
-  *
+  * Returns: a member of the #gnutls_pk_algorithm_t enumeration on
+  * success, or a negative value on error.
   **/
 int
 gnutls_x509_crt_get_pk_algorithm (gnutls_x509_crt_t cert, unsigned int *bits)
@@ -1146,7 +1146,7 @@ get_subject_alt_name (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_subject_alt_name - Get certificate's alternative name, if any
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @seq: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
   * @ret: is the place where the alternative name will be copied to
   * @ret_size: holds the size of ret.
@@ -1169,14 +1169,13 @@ get_subject_alt_name (gnutls_x509_crt_t cert,
   * it yourself.  Currently, only the RFC 3920 id-on-xmppAddr SAN is
   * recognized.
   *
-  * Returns the alternative subject name type on success.  The type is
-  * one of the enumerated gnutls_x509_subject_alt_name_t.  It will
-  * return %GNUTLS_E_SHORT_MEMORY_BUFFER if @ret_size is not large
-  * enough to hold the value.  In that case @ret_size will be updated
-  * with the required size.  If the certificate does not have an
-  * Alternative name with the specified sequence number then
+  * Returns: the alternative subject name type on success, one of the
+  * enumerated #gnutls_x509_subject_alt_name_t.  It will return
+  * %GNUTLS_E_SHORT_MEMORY_BUFFER if @ret_size is not large enough to
+  * hold the value.  In that case @ret_size will be updated with the
+  * required size.  If the certificate does not have an Alternative
+  * name with the specified sequence number then
   * %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.
-  *
   **/
 int
 gnutls_x509_crt_get_subject_alt_name (gnutls_x509_crt_t cert,
@@ -1189,7 +1188,7 @@ gnutls_x509_crt_get_subject_alt_name (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_subject_alt_name2 - Get certificate's alternative name, if any
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @seq: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
   * @ret: is the place where the alternative name will be copied to
   * @ret_size: holds the size of ret.
@@ -1217,7 +1216,7 @@ gnutls_x509_crt_get_subject_alt_name2 (gnutls_x509_crt_t cert,
 
 /**
  * gnutls_x509_crt_get_subject_alt_othername_oid - Get SAN otherName OID
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @seq: specifies the sequence number of the alt name (0 for the first one, 1 for the second etc.)
  * @ret: is the place where the otherName OID will be copied to
  * @ret_size: holds the size of ret.
@@ -1230,16 +1229,16 @@ gnutls_x509_crt_get_subject_alt_name2 (gnutls_x509_crt_t cert,
  * gnutls_x509_crt_get_subject_alt_name() returned
  * %GNUTLS_SAN_OTHERNAME.
  *
- * Returns the alternative subject name type on success.  The type is
- * one of the enumerated gnutls_x509_subject_alt_name_t.  For
- * supported OIDs, it will return one of the virtual
- * (GNUTLS_SAN_OTHERNAME_*) types, e.g. %GNUTLS_SAN_OTHERNAME_XMPP,
- * and %GNUTLS_SAN_OTHERNAME for unknown OIDs.  It will return
- * %GNUTLS_E_SHORT_MEMORY_BUFFER if @ret_size is not large enough to
- * hold the value.  In that case @ret_size will be updated with the
- * required size.  If the certificate does not have an Alternative
- * name with the specified sequence number and with the otherName type
- * then %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.
+ * Returns: the alternative subject name type on success, one of the
+ * enumerated gnutls_x509_subject_alt_name_t.  For supported OIDs, it
+ * will return one of the virtual (GNUTLS_SAN_OTHERNAME_*) types,
+ * e.g. %GNUTLS_SAN_OTHERNAME_XMPP, and %GNUTLS_SAN_OTHERNAME for
+ * unknown OIDs.  It will return %GNUTLS_E_SHORT_MEMORY_BUFFER if
+ * @ret_size is not large enough to hold the value.  In that case
+ * @ret_size will be updated with the required size.  If the
+ * certificate does not have an Alternative name with the specified
+ * sequence number and with the otherName type then
+ * %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE is returned.
  **/
 int
 gnutls_x509_crt_get_subject_alt_othername_oid (gnutls_x509_crt_t cert,
@@ -1252,7 +1251,7 @@ gnutls_x509_crt_get_subject_alt_othername_oid (gnutls_x509_crt_t cert,
 
 /**
  * gnutls_x509_crt_get_basic_constraints - This function returns the certificate basic constraints
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @critical: will be non zero if the extension is marked as critical
  * @ca: pointer to output integer indicating CA status, may be NULL,
  *   value is 1 if the certificate CA flag is set, 0 otherwise.
@@ -1319,7 +1318,7 @@ gnutls_x509_crt_get_basic_constraints (gnutls_x509_crt_t cert,
 
 /**
  * gnutls_x509_crt_get_ca_status - This function returns the certificate CA status
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @critical: will be non zero if the extension is marked as critical
  *
  * This function will return certificates CA status, by reading the
@@ -1344,7 +1343,7 @@ gnutls_x509_crt_get_ca_status (gnutls_x509_crt_t cert, unsigned int *critical)
 
 /**
   * gnutls_x509_crt_get_key_usage - return the certificate's key usage
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @key_usage: where the key usage bits will be stored
   * @critical: will be non zero if the extension is marked as critical
   *
@@ -1406,7 +1405,7 @@ gnutls_x509_crt_get_key_usage (gnutls_x509_crt_t cert,
 
 /**
  * gnutls_x509_crt_get_proxy - This function returns the proxy certificate info
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @critical: will be non zero if the extension is marked as critical
  * @pathlen: pointer to output integer indicating path length (may be
  *   NULL), non-negative values indicate a present pCPathLenConstraint
@@ -1470,7 +1469,7 @@ gnutls_x509_crt_get_proxy (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_extension_by_oid - This function returns the specified extension
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @oid: holds an Object Identified in null terminated string
   * @indx: In case multiple same OIDs exist in the extensions, this specifies which to send. Use zero to get the first one.
   * @buf: a pointer to a structure to hold the name (may be null)
@@ -1535,7 +1534,7 @@ gnutls_x509_crt_get_extension_by_oid (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_extension_oid - This function returns the specified extension OID
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @indx: Specifies which extension OID to send. Use zero to get the first one.
   * @oid: a pointer to a structure to hold the OID (may be null)
   * @sizeof_oid: initially holds the size of @oid
@@ -1572,7 +1571,7 @@ gnutls_x509_crt_get_extension_oid (gnutls_x509_crt_t cert, int indx,
 
 /**
  * gnutls_x509_crt_get_extension_info - Get extension id and criticality
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @indx: Specifies which extension OID to send. Use zero to get the first one.
  * @oid: a pointer to a structure to hold the OID
  * @sizeof_oid: initially holds the size of @oid
@@ -1643,7 +1642,7 @@ gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t cert, int indx,
 
 /**
  * gnutls_x509_crt_get_extension_data - Get the specified extension data
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @indx: Specifies which extension OID to send. Use zero to get the first one.
  * @data: a pointer to a structure to hold the data (may be null)
  * @sizeof_data: initially holds the size of @oid
@@ -1753,7 +1752,7 @@ cleanup:
 
 /**
  * gnutls_x509_crt_get_raw_issuer_dn - This function returns the issuer's DN DER encoded
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @start: will hold the starting point of the DN
  *
  * This function will return a pointer to the DER encoded DN structure
@@ -1772,7 +1771,7 @@ gnutls_x509_crt_get_raw_issuer_dn (gnutls_x509_crt_t cert,
 
 /**
  * gnutls_x509_crt_get_raw_dn - This function returns the subject's DN DER encoded
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @start: will hold the starting point of the DN
  *
  * This function will return a pointer to the DER encoded DN structure and
@@ -1799,7 +1798,7 @@ get_dn (gnutls_x509_crt_t cert, const char *whom, gnutls_x509_dn_t *dn)
 
 /**
  * gnutls_x509_crt_get_subject: get opaque subject DN pointer
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @dn: output variable with pointer to opaque DN.
  *
  * Return the Certificate's Subject DN as an opaque data type.  You
@@ -1820,7 +1819,7 @@ gnutls_x509_crt_get_subject (gnutls_x509_crt_t cert,
 
 /**
  * gnutls_x509_crt_get_issuer: get opaque issuer DN pointer
- * @cert: should contain a gnutls_x509_crt_t structure
+ * @cert: should contain a #gnutls_x509_crt_t structure
  * @dn: output variable with pointer to opaque DN
  *
  * Return the Certificate's Issuer DN as an opaque data type.  You may
@@ -1939,7 +1938,7 @@ gnutls_x509_dn_get_rdn_ava (gnutls_x509_dn_t dn,
 
 /**
   * gnutls_x509_crt_get_fingerprint - This function returns the Certificate's fingerprint
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @algo: is a digest algorithm
   * @buf: a pointer to a structure to hold the fingerprint (may be null)
   * @sizeof_buf: initially holds the size of @buf
@@ -2195,7 +2194,7 @@ gnutls_x509_crt_get_key_id (gnutls_x509_crt_t crt, unsigned int flags,
 
 /**
   * gnutls_x509_crt_check_revocation - This function checks if the given certificate is revoked
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @crl_list: should contain a list of gnutls_x509_crl_t structures
   * @crl_list_length: the length of the crl_list
   *
@@ -2338,7 +2337,7 @@ gnutls_x509_crt_verify_data (gnutls_x509_crt_t crt, unsigned int flags,
 
 /**
   * gnutls_x509_crt_get_crl_dist_points - This function returns the CRL distribution points
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_t structure
   * @seq: specifies the sequence number of the distribution point (0 for the first one, 1 for the second etc.)
   * @ret: is the place where the distribution point will be copied to
   * @ret_size: holds the size of ret.
@@ -2362,7 +2361,7 @@ gnutls_x509_crt_verify_data (gnutls_x509_crt_t crt, unsigned int flags,
   * return the distribution point type, or a negative error code on
   * error.
   *
-  * Returns %GNUTLS_E_SHORT_MEMORY_BUFFER and updates &@ret_size if
+  * Returns: %GNUTLS_E_SHORT_MEMORY_BUFFER and updates &@ret_size if
   * &@ret_size is not enough to hold the distribution point, or the
   * type of the distribution point if everything was ok. The type is
   * one of the enumerated %gnutls_x509_subject_alt_name_t.  If the
@@ -2473,7 +2472,7 @@ gnutls_x509_crt_get_crl_dist_points (gnutls_x509_crt_t cert,
 
 /**
   * gnutls_x509_crt_get_key_purpose_oid - This function returns the Certificate's key purpose OIDs
-  * @cert: should contain a gnutls_x509_crt_t structure
+  * @cert: should contain a #gnutls_x509_crt_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)
   * @sizeof_oid: initially holds the size of @oid