Doc fixes.

6 files changed, 370 insertions, 368 deletions

diff --git a/lib/openpgp/extras.c b/lib/openpgp/extras.c
index 56ff449c19..1bbf6a1d92 100644
--- a/lib/openpgp/extras.c
+++ b/lib/openpgp/extras.c
@@ -37,13 +37,12 @@
  */
 
 /**
- * gnutls_openpgp_keyring_init - This function initializes a gnutls_openpgp_keyring_t structure
+ * gnutls_openpgp_keyring_init - initializes a #gnutls_openpgp_keyring_t structure
  * @keyring: The structure to be initialized
  *
- * This function will initialize an keyring structure. 
- *
- * Returns 0 on success.
+ * This function will initialize an keyring structure.
  *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t * keyring)
@@ -57,11 +56,10 @@ gnutls_openpgp_keyring_init (gnutls_openpgp_keyring_t * keyring)
 
 
 /**
- * gnutls_openpgp_keyring_deinit - This function deinitializes memory used by a gnutls_openpgp_keyring_t structure
+ * gnutls_openpgp_keyring_deinit - deinitializes memory used by a #gnutls_openpgp_keyring_t structure
  * @keyring: The structure to be initialized
  *
- * This function will deinitialize a keyring structure. 
- *
+ * This function will deinitialize a keyring structure.
  **/
 void
 gnutls_openpgp_keyring_deinit (gnutls_openpgp_keyring_t keyring)
@@ -86,8 +84,8 @@ gnutls_openpgp_keyring_deinit (gnutls_openpgp_keyring_t keyring)
  *
  * Check if a given key ID exists in the keyring.
  *
- * Returns 0 on success (if keyid exists) and a negative error code
- * on failure.
+ * Returns: %GNUTLS_E_SUCCESS on success (if keyid exists) and a
+ *   negative error code on failure.
  **/
 int
 gnutls_openpgp_keyring_check_id (gnutls_openpgp_keyring_t ring,
@@ -116,12 +114,11 @@ gnutls_openpgp_keyring_check_id (gnutls_openpgp_keyring_t ring,
  * @data: The RAW or BASE64 encoded keyring.
  * @format: One of #gnutls_openpgp_keyring_fmt elements.
  *
- * This function will convert the given RAW or Base64 encoded keyring to the
- * native #gnutls_openpgp_keyring_t format.  The output will be stored in
- * 'keyring'.
- *
- * Returns 0 on success.
+ * This function will convert the given RAW or Base64 encoded keyring
+ * to the native #gnutls_openpgp_keyring_t format.  The output will be
+ * stored in 'keyring'.
  *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_keyring_import (gnutls_openpgp_keyring_t keyring,
@@ -219,15 +216,14 @@ error:
   cdk_kbnode_find_packet (node, CDK_PKT_PUBLIC_KEY)!=NULL
 
 /**
-  * gnutls_openpgp_keyring_get_crt_count - This function returns the number of certificates
-  * @ring: is an OpenPGP key ring
-  *
-  * This function will return the number of OpenPGP certificates present in the given 
-  * keyring.
-  *
-  * Returns then number of subkeys or a negative value on error.
-  *
-  **/
+ * gnutls_openpgp_keyring_get_crt_count - return the number of certificates
+ * @ring: is an OpenPGP key ring
+ *
+ * This function will return the number of OpenPGP certificates
+ * present in the given keyring.
+ *
+ * Returns: the number of subkeys, or a negative value on error.
+ **/
 int
 gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring)
 {
@@ -266,18 +262,18 @@ gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring)
 }
 
 /**
-  * gnutls_openpgp_keyring_get_crt - This function will export an openpgp certificate from a keyring
-  * @key: Holds the key.
-  * @idx: the index of the certificate to export
-  * @crt: An uninitialized &gnutls_openpgp_crt_t structure
-  *
-  * This function will extract an OpenPGP certificate from the given keyring.
-  * If the index given is out of range GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be
-  * returned. The returned structure needs to be deinited.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_openpgp_keyring_get_crt - export an openpgp certificate from a keyring
+ * @key: Holds the key.
+ * @idx: the index of the certificate to export
+ * @crt: An uninitialized &gnutls_openpgp_crt_t structure
+ *
+ * This function will extract an OpenPGP certificate from the given
+ * keyring.  If the index given is out of range
+ * %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned. The
+ * returned structure needs to be deinited.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ **/
 int
 gnutls_openpgp_keyring_get_crt (gnutls_openpgp_keyring_t ring,
 				unsigned int idx,
diff --git a/lib/openpgp/output.c b/lib/openpgp/output.c
index c5b3276c67..485cf7598f 100644
--- a/lib/openpgp/output.c
+++ b/lib/openpgp/output.c
@@ -325,15 +325,17 @@ size_t dn_size;
       dn_size = sizeof(dn);
       err = gnutls_openpgp_crt_get_name (cert, i++, dn, &dn_size);
 
-      if (err < 0 && err != GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE && err != GNUTLS_E_OPENPGP_UID_REVOKED) {
-	addf (str, "error: get_name: %s %d\n", gnutls_strerror (err), err);
-	break;
-      }
+      if (err < 0 && err != GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE &&
+	  err != GNUTLS_E_OPENPGP_UID_REVOKED)
+	{
+	  addf (str, "error: get_name: %s %d\n", gnutls_strerror (err), err);
+	  break;
+	}
 
       if (err >= 0)
 	addf (str, _("\tName[%d]: %s\n"), i-1, dn);
       else if (err == GNUTLS_E_OPENPGP_UID_REVOKED) {
-        addf (str, _("\tRevoked Name[%d]: %s\n"), i-1, dn);
+	addf (str, _("\tRevoked Name[%d]: %s\n"), i-1, dn);
       }
 
   } while( err >= 0);
@@ -346,10 +348,10 @@ size_t dn_size;
   subkeys = gnutls_openpgp_crt_get_subkey_count( cert);
   if (subkeys < 0)
     return;
-    
+
   for (i=0;i<subkeys;i++) {
     addf( str, _("\n\tSubkey[%d]:\n"), i);
-    
+
     print_key_revoked( str, cert, i);
     print_key_id( str, cert, i);
     print_key_times( str, cert, i);
@@ -365,14 +367,14 @@ size_t dn_size;
  * @format: Indicate the format to use
  * @out: Newly allocated datum with zero terminated string.
  *
- * This function will pretty print an OpenPGP certificate, suitable for
- * display to a human.
+ * This function will pretty print an OpenPGP certificate, suitable
+ * for display to a human.
  *
  * The format should be zero for future compatibility.
  *
  * The output @out needs to be deallocate using gnutls_free().
  *
- * Returns 0 on success.
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_crt_print (gnutls_openpgp_crt_t cert,
diff --git a/lib/openpgp/pgp.c b/lib/openpgp/pgp.c
index 55a88b35e5..50609e406e 100644
--- a/lib/openpgp/pgp.c
+++ b/lib/openpgp/pgp.c
@@ -34,13 +34,12 @@
 #include <gnutls_num.h>
 
 /**
- * gnutls_openpgp_crt_init - This function initializes a gnutls_openpgp_crt_t structure
+ * gnutls_openpgp_crt_init - initialize a #gnutls_openpgp_crt_t structure
  * @key: The structure to be initialized
  *
- * This function will initialize an OpenPGP key structure. 
- *
- * Returns 0 on success.
+ * This function will initialize an OpenPGP key structure.
  *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * key)
@@ -53,10 +52,10 @@ gnutls_openpgp_crt_init (gnutls_openpgp_crt_t * key)
 }
 
 /**
- * gnutls_openpgp_crt_deinit - This function deinitializes memory used by a gnutls_openpgp_crt_t structure
+ * gnutls_openpgp_crt_deinit - deinitialize memory used by a #gnutls_openpgp_crt_t structure
  * @key: The structure to be initialized
  *
- * This function will deinitialize a key structure. 
+ * This function will deinitialize a key structure.
  **/
 void
 gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t key)
@@ -69,21 +68,22 @@ gnutls_openpgp_crt_deinit (gnutls_openpgp_crt_t key)
       cdk_kbnode_release (key->knode);
       key->knode = NULL;
     }
-  
+
   gnutls_free (key);
 }
 
 /**
-  * gnutls_openpgp_crt_import - This function will import a RAW or BASE64 encoded key
-  * @key: The structure to store the parsed key.
-  * @data: The RAW or BASE64 encoded key.
-  * @format: One of gnutls_openpgp_crt_fmt_t elements.
-  *
-  * This function will convert the given RAW or Base64 encoded key
-  * to the native gnutls_openpgp_crt_t format. The output will be stored in 'key'.
-  *
-  * Returns 0 on success.
-  **/
+ * gnutls_openpgp_crt_import - import a RAW or BASE64 encoded key
+ * @key: The structure to store the parsed key.
+ * @data: The RAW or BASE64 encoded key.
+ * @format: One of gnutls_openpgp_crt_fmt_t elements.
+ *
+ * This function will convert the given RAW or Base64 encoded key to
+ * the native #gnutls_openpgp_crt_t format. The output will be stored
+ * in 'key'.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ **/
 int
 gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key,
 			   const gnutls_datum_t * data,
@@ -109,7 +109,7 @@ gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key,
 	  rc = _gnutls_map_cdk_rc (rc);
 	  gnutls_assert ();
 	  return rc;
-	}      
+	}
       if (cdk_armor_filter_use (inp))
 	rc = cdk_stream_set_armor_flag (inp, 0);
       if (!rc)
@@ -140,8 +140,10 @@ gnutls_openpgp_crt_import (gnutls_openpgp_crt_t key,
 /* internal version of export
  */
 int _gnutls_openpgp_export (cdk_kbnode_t node,
-			       gnutls_openpgp_crt_fmt_t format,
-			       void *output_data, size_t * output_data_size, int private)
+			    gnutls_openpgp_crt_fmt_t format,
+			    void *output_data,
+			    size_t * output_data_size,
+			    int private)
 {
   size_t input_data_size = *output_data_size;
   size_t calc_size;
@@ -154,10 +156,10 @@ int _gnutls_openpgp_export (cdk_kbnode_t node,
       gnutls_assert ();
       return rc;
     }
-  
+
   /* If the caller uses output_data == NULL then return what he expects.
    */
-  if (!output_data) 
+  if (!output_data)
     {
       gnutls_assert();
       return GNUTLS_E_SHORT_MEMORY_BUFFER;
@@ -167,7 +169,7 @@ int _gnutls_openpgp_export (cdk_kbnode_t node,
     {
       unsigned char *in = cdk_calloc (1, *output_data_size);
       memcpy (in, output_data, *output_data_size);
-      
+
       /* Calculate the size of the encoded data and check if the provided
          buffer is large enough. */
       rc = cdk_armor_encode_buffer (in, *output_data_size,
@@ -179,7 +181,7 @@ int _gnutls_openpgp_export (cdk_kbnode_t node,
 	  gnutls_assert ();
 	  return GNUTLS_E_SHORT_MEMORY_BUFFER;
 	}
-      
+
       rc = cdk_armor_encode_buffer (in, *output_data_size,
 				    output_data, input_data_size, &calc_size,
 				    private?CDK_ARMOR_SECKEY:CDK_ARMOR_PUBKEY);
@@ -192,25 +194,26 @@ int _gnutls_openpgp_export (cdk_kbnode_t node,
 }
 
 /**
-  * gnutls_openpgp_crt_export - This function will export a RAW or BASE64 encoded key
-  * @key: Holds the key.
-  * @format: One of gnutls_openpgp_crt_fmt_t elements.
-  * @output_data: will contain the key base64 encoded or raw
-  * @output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters)
-  *
-  * This function will convert the given key to RAW or Base64 format.
-  * If the buffer provided is not long enough to hold the output, then
-  * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_openpgp_crt_export - export a RAW or BASE64 encoded key
+ * @key: Holds the key.
+ * @format: One of gnutls_openpgp_crt_fmt_t elements.
+ * @output_data: will contain the key base64 encoded or raw
+ * @output_data_size: holds the size of output_data (and will
+ *   be replaced by the actual size of parameters)
+ *
+ * This function will convert the given key to RAW or Base64 format.
+ * If the buffer provided is not long enough to hold the output, then
+ * %GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ **/
 int
 gnutls_openpgp_crt_export (gnutls_openpgp_crt_t key,
 			   gnutls_openpgp_crt_fmt_t format,
 			   void *output_data, size_t * output_data_size)
 {
-  return _gnutls_openpgp_export( key->knode, format, output_data, output_data_size, 0);
+  return _gnutls_openpgp_export( key->knode, format, output_data,
+				 output_data_size, 0);
 }
 
 
@@ -246,7 +249,7 @@ gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t key,
 
   pk = pkt->pkt.public_key;
   *fprlen = 20;
-  
+
   /* FIXME: Check if the draft allows old PGP keys. */
   if (is_RSA (pk->pubkey_algo) && pk->version < 4)
     *fprlen = 16;
@@ -267,7 +270,7 @@ _gnutls_openpgp_count_key_names (gnutls_openpgp_crt_t key)
       gnutls_assert ();
       return 0;
     }
-  
+
   ctx = NULL;
   nuids = 0;
   while ((p = cdk_kbnode_walk (key->knode, &ctx, 0)))
@@ -291,9 +294,9 @@ _gnutls_openpgp_count_key_names (gnutls_openpgp_crt_t key)
  *
  * Extracts the userID from the parsed OpenPGP key.
  *
- * Returns 0 on success, and GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
- * if the index of the ID does not exist.
- *
+ * Returns: %GNUTLS_E_SUCCESS on success, and if the index of the ID
+ *   does not exist %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE, or an
+ *   error code.
  **/
 int
 gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key,
@@ -330,7 +333,7 @@ gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key,
     {
       gnutls_assert ();
       return GNUTLS_E_INTERNAL_ERROR;
-    }  
+    }
 
   uid = pkt->pkt.user_id;
   if (uid->len >= *sizeof_buf)
@@ -351,21 +354,20 @@ gnutls_openpgp_crt_get_name (gnutls_openpgp_crt_t key,
 }
 
 /**
-  * gnutls_openpgp_crt_get_pk_algorithm - This function returns the key's PublicKey algorithm
-  * @key: is an OpenPGP key
-  * @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 OpenPGP
-  * certificate.
-  *
-  * 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_PKAlgorithm enumeration on success,
-  * or a negative value on error.
-  *
-  **/
+ * gnutls_openpgp_crt_get_pk_algorithm - return the key's PublicKey algorithm
+ * @key: is an OpenPGP key
+ * @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 OpenPGP
+ * certificate.
+ *
+ * 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_pk_algorithm_t
 gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key,
 				     unsigned int *bits)
@@ -377,7 +379,7 @@ gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key,
     {
       gnutls_assert();
       return GNUTLS_PK_UNKNOWN;
-    }  
+    }
 
   algo = 0;
   pkt = cdk_kbnode_find_packet (key->knode, CDK_PKT_PUBLIC_KEY);
@@ -387,7 +389,7 @@ gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key,
 	*bits = cdk_pk_get_nbits (pkt->pkt.public_key);
       algo = _gnutls_openpgp_get_algo(pkt->pkt.public_key->pubkey_algo);
     }
-  
+
   return algo;
 }
 
@@ -397,6 +399,8 @@ gnutls_openpgp_crt_get_pk_algorithm (gnutls_openpgp_crt_t key,
  * @key: the structure that contains the OpenPGP public key.
  *
  * Extract the version of the OpenPGP key.
+ *
+ * Returns: the version number is returned, or a negative value on errors.
  **/
 int
 gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t key)
@@ -533,17 +537,16 @@ gnutls_openpgp_crt_get_revoked_status (gnutls_openpgp_crt_t key)
 }
 
 /**
-  * gnutls_openpgp_crt_check_hostname - This function compares the given hostname with the hostname in the key
-  * @key: should contain an gnutls_openpgp_crt_t structure
-  * @hostname: A null terminated string that contains a DNS name
-  *
-  * This function will check if the given key's owner matches
-  * the given hostname. This is a basic implementation of the matching 
-  * described in RFC2818 (HTTPS), which takes into account wildcards.
-  *
-  * Returns non zero on success, and zero on failure.
-  *
-  **/
+ * gnutls_openpgp_crt_check_hostname - compare hostname with the key's hostname
+ * @key: should contain an #gnutls_openpgp_crt_t structure
+ * @hostname: A null terminated string that contains a DNS name
+ *
+ * This function will check if the given key's owner matches the
+ * given hostname. This is a basic implementation of the matching
+ * described in RFC2818 (HTTPS), which takes into account wildcards.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ **/
 int
 gnutls_openpgp_crt_check_hostname (gnutls_openpgp_crt_t key,
 				   const char *hostname)
@@ -595,10 +598,9 @@ unsigned int usage = 0;
  *
  * This function will return certificate's key usage, by checking the
  * key algorithm. The key usage value will ORed values of the:
- * GNUTLS_KEY_DIGITAL_SIGNATURE, GNUTLS_KEY_KEY_ENCIPHERMENT.
- *
- * A negative value may be returned in case of parsing error.
+ * %GNUTLS_KEY_DIGITAL_SIGNATURE, %GNUTLS_KEY_KEY_ENCIPHERMENT.
  *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  */
 int
 gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key,
@@ -622,15 +624,14 @@ gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key,
 }
 
 /**
-  * gnutls_openpgp_crt_get_subkey_count - This function returns the number of subkeys
-  * @key: is an OpenPGP key
-  *
-  * This function will return the number of subkeys present in the given 
-  * OpenPGP certificate.
-  *
-  * Returns then number of subkeys or a negative value on error.
-  *
-  **/
+ * gnutls_openpgp_crt_get_subkey_count - return the number of subkeys
+ * @key: is an OpenPGP key
+ *
+ * This function will return the number of subkeys present in the
+ * given OpenPGP certificate.
+ *
+ * Returns: the number of subkeys, or a negative value on error.
+ **/
 int
 gnutls_openpgp_crt_get_subkey_count (gnutls_openpgp_crt_t key)
 {
@@ -643,7 +644,7 @@ gnutls_openpgp_crt_get_subkey_count (gnutls_openpgp_crt_t key)
       gnutls_assert ();
       return 0;
     }
-  
+
   ctx = NULL;
   subkeys = 0;
   while ((p = cdk_kbnode_walk (key->knode, &ctx, 0)))
@@ -788,22 +789,21 @@ gnutls_openpgp_crt_get_subkey_revoked_status (gnutls_openpgp_crt_t key,
 }
 
 /**
-  * gnutls_openpgp_crt_get_subkey_pk_algorithm - This function returns the subkey's PublicKey algorithm
-  * @key: is an OpenPGP key
-  * @idx: is the subkey index
-  * @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 subkey of an OpenPGP
-  * certificate.
-  *
-  * 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_openpgp_crt_get_subkey_pk_algorithm - return the subkey's PublicKey algorithm
+ * @key: is an OpenPGP key
+ * @idx: is the subkey index
+ * @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 subkey of an OpenPGP
+ * certificate.
+ *
+ * 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_pk_algorithm_t
 gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key,
     unsigned int idx, unsigned int *bits)
@@ -816,7 +816,7 @@ gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key,
       gnutls_assert();
       return GNUTLS_PK_UNKNOWN;
     }
-  
+
   pkt = _get_public_subkey( key, idx);
 
   algo = 0;
@@ -826,7 +826,7 @@ gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key,
 	*bits = cdk_pk_get_nbits (pkt->pkt.public_key);
       algo = _gnutls_openpgp_get_algo(pkt->pkt.public_key->pubkey_algo);
     }
-  
+
   return algo;
 }
 
@@ -1290,17 +1290,17 @@ cleanup:
 
 
 /**
-  * gnutls_openpgp_crt_get_pk_rsa_raw - This function will export the RSA public key
-  * @crt: Holds the certificate
-  * @m: will hold the modulus
-  * @e: will hold the public exponent
-  *
-  * This function will export the RSA public key's parameters found in
-  * the given structure.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_crt_get_pk_rsa_raw - export the RSA public key
+ * @crt: Holds the certificate
+ * @m: will hold the modulus
+ * @e: will hold the public exponent
+ *
+ * This function will export the RSA public key's parameters found in
+ * the given structure.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_crt_get_pk_rsa_raw (gnutls_openpgp_crt_t crt, 
 				gnutls_datum_t * m, gnutls_datum_t * e)
@@ -1319,19 +1319,19 @@ int ret;
 }
 
 /**
-  * gnutls_openpgp_crt_get_pk_dsa_raw - This function will export the DSA public key
-  * @crt: Holds the certificate
-  * @p: will hold the p
-  * @q: will hold the q
-  * @g: will hold the g
-  * @y: will hold the y
-  *
-  * This function will export the DSA public key's parameters found in
-  * the given certificate.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_crt_get_pk_dsa_raw - export the DSA public key
+ * @crt: Holds the certificate
+ * @p: will hold the p
+ * @q: will hold the q
+ * @g: will hold the g
+ * @y: will hold the y
+ *
+ * This function will export the DSA public key's parameters found in
+ * the given certificate.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_crt_get_pk_dsa_raw (gnutls_openpgp_crt_t crt, 
 				gnutls_datum_t * p, gnutls_datum_t * q,
@@ -1346,23 +1346,23 @@ int ret;
       gnutls_assert ();
       return ret;
     }
-    
+
   return _get_pk_dsa_raw( crt, keyid, p, q, g, y);
 }
 
 /**
-  * gnutls_openpgp_crt_get_subkey_pk_rsa_raw - This function will export the RSA public key
-  * @crt: Holds the certificate
-  * @idx: Is the subkey index
-  * @m: will hold the modulus
-  * @e: will hold the public exponent
-  *
-  * This function will export the RSA public key's parameters found in
-  * the given structure.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_crt_get_subkey_pk_rsa_raw - export the RSA public key
+ * @crt: Holds the certificate
+ * @idx: Is the subkey index
+ * @m: will hold the modulus
+ * @e: will hold the public exponent
+ *
+ * This function will export the RSA public key's parameters found in
+ * the given structure.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_crt_get_subkey_pk_rsa_raw (gnutls_openpgp_crt_t crt, unsigned int idx,
 				gnutls_datum_t * m, gnutls_datum_t * e)
@@ -1376,40 +1376,43 @@ int ret;
       gnutls_assert ();
       return ret;
     }
-    
+
   return _get_pk_rsa_raw( crt, keyid, m, e);
 }
 
 /**
-  * gnutls_openpgp_crt_get_subkey_pk_dsa_raw - This function will export the DSA public key
-  * @crt: Holds the certificate
-  * @idx: Is the subkey index
-  * @p: will hold the p
-  * @q: will hold the q
-  * @g: will hold the g
-  * @y: will hold the y
-  *
-  * This function will export the DSA public key's parameters found in
-  * the given certificate.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_crt_get_subkey_pk_dsa_raw - export the DSA public key
+ * @crt: Holds the certificate
+ * @idx: Is the subkey index
+ * @p: will hold the p
+ * @q: will hold the q
+ * @g: will hold the g
+ * @y: will hold the y
+ *
+ * This function will export the DSA public key's parameters found in
+ * the given certificate.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
-gnutls_openpgp_crt_get_subkey_pk_dsa_raw (gnutls_openpgp_crt_t crt, unsigned int idx,
-				gnutls_datum_t * p, gnutls_datum_t * q,
-				gnutls_datum_t * g, gnutls_datum_t * y)
+gnutls_openpgp_crt_get_subkey_pk_dsa_raw (gnutls_openpgp_crt_t crt,
+					  unsigned int idx,
+					  gnutls_datum_t * p,
+					  gnutls_datum_t * q,
+					  gnutls_datum_t * g,
+					  gnutls_datum_t * y)
 {
-gnutls_openpgp_keyid_t keyid;
-int ret;
+  gnutls_openpgp_keyid_t keyid;
+  int ret;
 
-  ret = gnutls_openpgp_crt_get_subkey_id( crt, idx, keyid);  
+  ret = gnutls_openpgp_crt_get_subkey_id( crt, idx, keyid);
   if (ret < 0)
     {
       gnutls_assert ();
       return ret;
     }
-    
+
   return _get_pk_dsa_raw( crt, keyid, p, q, g, y);
 }
 
@@ -1448,7 +1451,8 @@ gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key,
  *
  **/
 int
-gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key, const gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key,
+					 const gnutls_openpgp_keyid_t keyid)
 {
 int ret;
 
@@ -1479,13 +1483,16 @@ int ret;
  * @keyid: the struct to save the keyid.
  * @flag: Non zero indicates that a valid subkey is always returned.
  *
- * Returns the 64-bit keyID of the first valid OpenPGP subkey marked for authentication. 
- * If flag is non zero and no authentication subkey exists, then a valid subkey will 
- * be returned even if it is not marked for authentication.
- * 
- * Returns zero on success.
+ * Returns the 64-bit keyID of the first valid OpenPGP subkey marked
+ * for authentication.  If flag is non zero and no authentication
+ * subkey exists, then a valid subkey will be returned even if it is
+ * not marked for authentication.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
-int gnutls_openpgp_crt_get_auth_subkey( gnutls_openpgp_crt_t crt, gnutls_openpgp_keyid_t keyid, unsigned int flag)
+int gnutls_openpgp_crt_get_auth_subkey( gnutls_openpgp_crt_t crt,
+					gnutls_openpgp_keyid_t keyid,
+					unsigned int flag)
 {
   int ret, subkeys, i;
   unsigned int usage;
@@ -1506,38 +1513,38 @@ int gnutls_openpgp_crt_get_auth_subkey( gnutls_openpgp_crt_t crt, gnutls_openpgp
 
       ret = gnutls_openpgp_crt_get_subkey_revoked_status(crt, i);
       if (ret != 0) /* it is revoked. ignore it */
-        continue;
+	continue;
 
       if (keyid_init == 0)
-        { /* keep the first valid subkey */
-          ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid);
-          if (ret < 0)
-            {
-              gnutls_assert();
-              return ret;
-            }
-          
-          keyid_init = 1;
-        }
-      
+	{ /* keep the first valid subkey */
+	  ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid);
+	  if (ret < 0)
+	    {
+	      gnutls_assert();
+	      return ret;
+	    }
+
+	  keyid_init = 1;
+	}
+
       ret = gnutls_openpgp_crt_get_subkey_usage( crt, i, &usage);
       if (ret < 0)
-        {
-          gnutls_assert();
-          return ret;
-        }
+	{
+	  gnutls_assert();
+	  return ret;
+	}
 
       if (usage & GNUTLS_KEY_KEY_AGREEMENT)
-        {
-          ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid);
-          if (ret < 0)
-            {
-              gnutls_assert();
-              return ret;
-            }
-
-          return 0;
-        }
+	{
+	  ret = gnutls_openpgp_crt_get_subkey_id( crt, i, keyid);
+	  if (ret < 0)
+	    {
+	      gnutls_assert();
+	      return ret;
+	    }
+
+	  return 0;
+	}
     }
 
   if (flag && keyid_init) return 0;
diff --git a/lib/openpgp/pgpverify.c b/lib/openpgp/pgpverify.c
index 34d15fb99c..6659a6f911 100644
--- a/lib/openpgp/pgpverify.c
+++ b/lib/openpgp/pgpverify.c
@@ -31,7 +31,6 @@
 #include <gnutls_openpgp.h>
 #include <gnutls_num.h>
 
-
 /**
  * gnutls_openpgp_crt_verify_ring - Verify all signatures in the key
  * @key: the structure that holds the key.
@@ -39,20 +38,22 @@
  * @flags: unused (should be 0)
  * @verify: will hold the certificate verification output.
  *
- * Verify all signatures in the key, using the given set of keys (keyring). 
+ * Verify all signatures in the key, using the given set of keys
+ * (keyring).
  *
- * The key verification output will be put in @verify and will be
- * one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd.
+ * The key verification output will be put in @verify and will be one
+ * or more of the #gnutls_certificate_status_t enumerated elements
+ * bitwise or'd.
  *
- * GNUTLS_CERT_INVALID: A signature on the key is invalid.
+ * %GNUTLS_CERT_INVALID: A signature on the key is invalid.
  *
- * GNUTLS_CERT_REVOKED: The key has been revoked.
+ * %GNUTLS_CERT_REVOKED: The key has been revoked.
  *
- * Note that this function does not verify using any "web of
- * trust". You may use GnuPG for that purpose, or any other external
- * PGP application.
+ * Note that this function does not verify using any "web of trust".
+ * You may use GnuPG for that purpose, or any other external PGP
+ * application.
  *
- * Returns 0 on success.
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key,
@@ -70,7 +71,7 @@ gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key,
     }
 
   *verify = 0;
-  
+
   rc = cdk_pk_check_sigs (key->knode, keyring->db, &status);
   if (rc == CDK_Error_No_Key)
     {
@@ -109,7 +110,7 @@ gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key,
       if (rc == 0 && *verify & GNUTLS_CERT_SIGNER_NOT_FOUND)
 	*verify ^= GNUTLS_CERT_SIGNER_NOT_FOUND;
     }
-  
+
   return 0;
 }
 
@@ -120,13 +121,13 @@ gnutls_openpgp_crt_verify_ring (gnutls_openpgp_crt_t key,
  * @flags: unused (should be 0)
  * @verify: will hold the key verification output.
  *
- * Verifies the self signature in the key.
- * The key verification output will be put in @verify and will be
- * one or more of the gnutls_certificate_status_t enumerated elements bitwise or'd.
+ * Verifies the self signature in the key.  The key verification
+ * output will be put in @verify and will be one or more of the
+ * gnutls_certificate_status_t enumerated elements bitwise or'd.
  *
- * GNUTLS_CERT_INVALID: The self signature on the key is invalid.
+ * %GNUTLS_CERT_INVALID: The self signature on the key is invalid.
  *
- * Returns 0 on success.
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_crt_verify_self (gnutls_openpgp_crt_t key,
diff --git a/lib/openpgp/privkey.c b/lib/openpgp/privkey.c
index 695346b25e..49208ff22d 100644
--- a/lib/openpgp/privkey.c
+++ b/lib/openpgp/privkey.c
@@ -40,7 +40,7 @@
  *
  * This function will initialize an OpenPGP key structure.
  *
- * Returns 0 on success.
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_privkey_init (gnutls_openpgp_privkey_t * key)
@@ -85,7 +85,7 @@ gnutls_openpgp_privkey_deinit (gnutls_openpgp_privkey_t key)
  * the native gnutls_openpgp_privkey_t format.  The output will be
  * stored in 'key'.
  *
- * Returns 0 on success.
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
  **/
 int
 gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key,
@@ -139,21 +139,21 @@ gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key,
 }
 
 /**
-  * gnutls_openpgp_privkey_export - This function will export a RAW or BASE64 encoded key
-  * @key: Holds the key.
-  * @format: One of gnutls_openpgp_crt_fmt_t elements.
-  * @password: the password that will be used to encrypt the key. 
-  * @flags: zero for future compatibility
-  * @output_data: will contain the key base64 encoded or raw
-  * @output_data_size: holds the size of output_data (and will be replaced by the actual size of parameters)
-  *
-  * This function will convert the given key to RAW or Base64 format.
-  * If the buffer provided is not long enough to hold the output, then
-  * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
-  *
-  * Returns 0 on success.
-  *
-  **/
+ * gnutls_openpgp_privkey_export - export a RAW or BASE64 encoded key
+ * @key: Holds the key.
+ * @format: One of gnutls_openpgp_crt_fmt_t elements.
+ * @password: the password that will be used to encrypt the key.
+ * @flags: zero for future compatibility
+ * @output_data: will contain the key base64 encoded or raw
+ * @output_data_size: holds the size of output_data (and will be
+ *   replaced by the actual size of parameters)
+ *
+ * This function will convert the given key to RAW or Base64 format.
+ * If the buffer provided is not long enough to hold the output, then
+ * GNUTLS_E_SHORT_MEMORY_BUFFER will be returned.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ **/
 int
 gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key,
 			   gnutls_openpgp_crt_fmt_t format,
@@ -166,7 +166,7 @@ gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key,
 
 
 /**
- * gnutls_openpgp_privkey_get_pk_algorithm - This function returns the key's PublicKey algorithm
+ * gnutls_openpgp_privkey_get_pk_algorithm - return the key's PublicKey algorithm
  * @key: is an OpenPGP key
  * @bits: if bits is non null it will hold the size of the parameters' in bits
  *
@@ -174,12 +174,11 @@ gnutls_openpgp_privkey_export (gnutls_openpgp_privkey_t key,
  * certificate.
  *
  * 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. 
+ * 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_PKAlgorithm 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.
  **/
 gnutls_pk_algorithm_t
 gnutls_openpgp_privkey_get_pk_algorithm (gnutls_openpgp_privkey_t key,
@@ -230,7 +229,6 @@ int algo;
  *
  * Returns: true (1) if the key has been revoked, or false (0) if it
  *   has not, or a negative value indicates an error.
- *
  **/
 int
 gnutls_openpgp_privkey_get_revoked_status (gnutls_openpgp_privkey_t key)
@@ -412,22 +410,21 @@ gnutls_openpgp_privkey_get_subkey_revoked_status (gnutls_openpgp_privkey_t key,
 }
 
 /**
-  * gnutls_openpgp_privkey_get_subkey_pk_algorithm - This function returns the subkey's PublicKey algorithm
-  * @key: is an OpenPGP key
-  * @idx: is the subkey index
-  * @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 subkey of an OpenPGP
-  * certificate.
-  *
-  * 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_openpgp_privkey_get_subkey_pk_algorithm - return the subkey's PublicKey algorithm
+ * @key: is an OpenPGP key
+ * @idx: is the subkey index
+ * @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 subkey of an OpenPGP
+ * certificate.
+ *
+ * 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_pk_algorithm_t
 gnutls_openpgp_privkey_get_subkey_pk_algorithm (gnutls_openpgp_privkey_t key,
     unsigned int idx, unsigned int *bits)
@@ -868,21 +865,21 @@ cleanup:
 
 
 /**
-  * gnutls_openpgp_privkey_export_rsa_raw - This function will export the RSA private key
-  * @pkey: Holds the certificate
-  * @m: will hold the modulus
-  * @e: will hold the public exponent
-  * @d: will hold the private exponent
-  * @p: will hold the first prime (p)
-  * @q: will hold the second prime (q)
-  * @u: will hold the coefficient
-  *
-  * This function will export the RSA private key's parameters found in
-  * the given structure.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_privkey_export_rsa_raw - This function will export the RSA private key
+ * @pkey: Holds the certificate
+ * @m: will hold the modulus
+ * @e: will hold the public exponent
+ * @d: will hold the private exponent
+ * @p: will hold the first prime (p)
+ * @q: will hold the second prime (q)
+ * @u: will hold the coefficient
+ *
+ * This function will export the RSA private key's parameters found in
+ * the given structure.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_privkey_export_rsa_raw (gnutls_openpgp_privkey_t pkey, 
 				    gnutls_datum_t * m, gnutls_datum_t * e,
@@ -903,20 +900,20 @@ int ret;
 }
 
 /**
-  * gnutls_openpgp_privkey_export_dsa_raw - This function will export the DSA private key
-  * @pkey: Holds the certificate
-  * @p: will hold the p
-  * @q: will hold the q
-  * @g: will hold the g
-  * @y: will hold the y
-  * @x: will hold the x
-  *
-  * This function will export the DSA private key's parameters found in
-  * the given certificate.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_privkey_export_dsa_raw - This function will export the DSA private key
+ * @pkey: Holds the certificate
+ * @p: will hold the p
+ * @q: will hold the q
+ * @g: will hold the g
+ * @y: will hold the y
+ * @x: will hold the x
+ *
+ * This function will export the DSA private key's parameters found in
+ * the given certificate.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_privkey_export_dsa_raw (gnutls_openpgp_privkey_t pkey, 
 				    gnutls_datum_t * p, gnutls_datum_t * q,
@@ -937,22 +934,22 @@ int ret;
 }
 
 /**
-  * gnutls_openpgp_privkey_export_subkey_rsa_raw - This function will export the RSA private key
-  * @pkey: Holds the certificate
-  * @idx: Is the subkey index
-  * @m: will hold the modulus
-  * @e: will hold the public exponent
-  * @d: will hold the private exponent
-  * @p: will hold the first prime (p)
-  * @q: will hold the second prime (q)
-  * @u: will hold the coefficient
-  *
-  * This function will export the RSA private key's parameters found in
-  * the given structure.  The new parameters will be allocated using
-  * gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_privkey_export_subkey_rsa_raw - export the RSA private key
+ * @pkey: Holds the certificate
+ * @idx: Is the subkey index
+ * @m: will hold the modulus
+ * @e: will hold the public exponent
+ * @d: will hold the private exponent
+ * @p: will hold the first prime (p)
+ * @q: will hold the second prime (q)
+ * @u: will hold the coefficient
+ *
+ * This function will export the RSA private key's parameters found in
+ * the given structure.  The new parameters will be allocated using
+ * gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_privkey_export_subkey_rsa_raw (gnutls_openpgp_privkey_t pkey, unsigned int idx,
 				    gnutls_datum_t * m, gnutls_datum_t * e,
@@ -973,21 +970,21 @@ int ret;
 }
 
 /**
-  * gnutls_openpgp_privkey_export_subkey_dsa_raw - export the DSA private key
-  * @pkey: Holds the certificate
-  * @idx: Is the subkey index
-  * @p: will hold the p
-  * @q: will hold the q
-  * @g: will hold the g
-  * @y: will hold the y
-  * @x: will hold the x
-  *
-  * This function will export the DSA private key's parameters found
-  * in the given certificate.  The new parameters will be allocated
-  * using gnutls_malloc() and will be stored in the appropriate datum.
-  *
-  * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
-  **/
+ * gnutls_openpgp_privkey_export_subkey_dsa_raw - export the DSA private key
+ * @pkey: Holds the certificate
+ * @idx: Is the subkey index
+ * @p: will hold the p
+ * @q: will hold the q
+ * @g: will hold the g
+ * @y: will hold the y
+ * @x: will hold the x
+ *
+ * This function will export the DSA private key's parameters found
+ * in the given certificate.  The new parameters will be allocated
+ * using gnutls_malloc() and will be stored in the appropriate datum.
+ *
+ * Returns: %GNUTLS_E_SUCCESS on success, otherwise an error.
+ **/
 int
 gnutls_openpgp_privkey_export_subkey_dsa_raw (gnutls_openpgp_privkey_t pkey,
 					      unsigned int idx,
diff --git a/lib/x509/rfc2818_hostname.c b/lib/x509/rfc2818_hostname.c
index eeac3454f8..ca066cd737 100644
--- a/lib/x509/rfc2818_hostname.c
+++ b/lib/x509/rfc2818_hostname.c
@@ -28,18 +28,17 @@
 #include <gnutls_errors.h>
 
 /**
-  * gnutls_x509_crt_check_hostname - This function compares the given hostname with the hostname in the certificate
-  * @cert: should contain an gnutls_x509_crt_t structure
-  * @hostname: A null terminated string that contains a DNS name
-  *
-  * This function will check if the given certificate's subject
-  * matches the given hostname.  This is a basic implementation of the
-  * matching described in RFC2818 (HTTPS), which takes into account
-  * wildcards, and the DNSName/IPAddress subject alternative name PKIX
-  * extension.
-  *
-  * Returns non zero for a successful match, and zero on failure.
-  **/
+ * gnutls_x509_crt_check_hostname - compares the hostname with certificate's hostname
+ * @cert: should contain an gnutls_x509_crt_t structure
+ * @hostname: A null terminated string that contains a DNS name
+ *
+ * This function will check if the given certificate's subject matches
+ * the given hostname.  This is a basic implementation of the matching
+ * described in RFC2818 (HTTPS), which takes into account wildcards,
+ * and the DNSName/IPAddress subject alternative name PKIX extension.
+ *
+ * Returns: non zero for a successful match, and zero on failure.
+ **/
 int
 gnutls_x509_crt_check_hostname (gnutls_x509_crt_t cert, const char *hostname)
 {