Doc fixes.

diff --git a/lib/openpgp/pgp.c b/lib/openpgp/pgp.c
index 43f11b84a5aec9e989a89aef0b6e98668a0c48fc..61ced76f8f093cd4542cfd4b043a0f81192b1a36 100644 (file)
--- a/lib/openpgp/pgp.c
+++ b/lib/openpgp/pgp.c
@@ -199,8 +199,10 @@ gnutls_openpgp_crt_export (gnutls_openpgp_crt_t key,
  * @fpr: the buffer to save the fingerprint, must hold at least 20 bytes.
  * @fprlen: the integer to save the length of the fingerprint.
  *
- * Returns the fingerprint of the OpenPGP key. Depends on the algorithm,
- * the fingerprint can be 16 or 20 bytes.
+ * Get key fingerprint.  Depending on the algorithm, the fingerprint
+ * can be 16 or 20 bytes.
+ *
+ * Returns: the fingerprint of the OpenPGP key.
  **/
 int
 gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t key,
@@ -395,7 +397,9 @@ gnutls_openpgp_crt_get_version (gnutls_openpgp_crt_t key)
  * gnutls_openpgp_crt_get_creation_time - Extract the timestamp
  * @key: the structure that contains the OpenPGP public key.
  *
- * Returns the timestamp when the OpenPGP key was created.
+ * Get key creation time.
+ *
+ * Returns: the timestamp when the OpenPGP key was created.
  **/
 time_t
 gnutls_openpgp_crt_get_creation_time (gnutls_openpgp_crt_t key)
@@ -420,8 +424,10 @@ gnutls_openpgp_crt_get_creation_time (gnutls_openpgp_crt_t key)
  * gnutls_openpgp_crt_get_expiration_time - Extract the expire date
  * @key: the structure that contains the OpenPGP public key.
  *
- * Returns the time when the OpenPGP key expires. A value of '0' means
- * that the key doesn't expire at all.
+ * Get key expiration time.  A value of '0' means that the key doesn't
+ * expire at all.
+ *
+ * Returns: the time when the OpenPGP key expires.
  **/
 time_t
 gnutls_openpgp_crt_get_expiration_time (gnutls_openpgp_crt_t key)
@@ -446,10 +452,13 @@ gnutls_openpgp_crt_get_expiration_time (gnutls_openpgp_crt_t key)
  * @key: the structure that contains the OpenPGP public key.
  * @keyid: the buffer to save the keyid.
  *
- * Returns the 64-bit keyID of the OpenPGP key.
+ * Get key id string.
+ *
+ * Returns: the 64-bit keyID of the OpenPGP key.
  **/
 int
-gnutls_openpgp_crt_get_key_id (gnutls_openpgp_crt_t key, gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_crt_get_key_id (gnutls_openpgp_crt_t key,
+                              gnutls_openpgp_keyid_t keyid)
 {
   cdk_packet_t pkt;
   uint32_t kid[2];
@@ -475,9 +484,10 @@ gnutls_openpgp_crt_get_key_id (gnutls_openpgp_crt_t key, gnutls_openpgp_keyid_t
  * gnutls_openpgp_crt_get_revoked_status - Gets the revoked status of the key
  * @key: the structure that contains the OpenPGP public key.
  *
- * Returns the true (1) or false (0) based on whether this key has been revoked
- * or not.
+ * Get revocation status of key.
  *
+ * Returns: true (1) if the key has been revoked, or false (0) if it
+ *   has not.
  **/
 int
 gnutls_openpgp_crt_get_revoked_status (gnutls_openpgp_crt_t key)
@@ -728,12 +738,14 @@ int _gnutls_openpgp_find_subkey_idx( cdk_kbnode_t knode, uint32_t keyid[2],
  * @key: the structure that contains the OpenPGP public key.
  * @idx: is the subkey index
  *
- * Returns the true (1) or false (0) based on whether this key has been revoked
- * or not. A negative value indicates an error.
+ * Get subkey revocation status.  A negative value indicates an error.
  *
+ * Returns: true (1) if the key has been revoked, or false (0) if it
+ *   has not.
  **/
 int
-gnutls_openpgp_crt_get_subkey_revoked_status (gnutls_openpgp_crt_t key, unsigned int idx)
+gnutls_openpgp_crt_get_subkey_revoked_status (gnutls_openpgp_crt_t key,
+                                             unsigned int idx)
 {
   cdk_packet_t pkt;
 
@@ -802,17 +814,20 @@ gnutls_openpgp_crt_get_subkey_pk_algorithm (gnutls_openpgp_crt_t key,
  * @key: the structure that contains the OpenPGP public key.
  * @idx: the subkey index
  *
- * Returns the timestamp when the OpenPGP key was created.
+ * Get subkey creation time.
+ *
+ * Returns: the timestamp when the OpenPGP sub-key was created.
  **/
 time_t
-gnutls_openpgp_crt_get_subkey_creation_time (gnutls_openpgp_crt_t key, unsigned int idx)
+gnutls_openpgp_crt_get_subkey_creation_time (gnutls_openpgp_crt_t key,
+                                            unsigned int idx)
 {
   cdk_packet_t pkt;
   time_t timestamp;
 
   if (!key)
     return (time_t) - 1;
-    
+
   pkt = _get_public_subkey( key, idx);
   if (pkt)
     timestamp = pkt->pkt.public_key->timestamp;
@@ -828,11 +843,14 @@ gnutls_openpgp_crt_get_subkey_creation_time (gnutls_openpgp_crt_t key, unsigned
  * @key: the structure that contains the OpenPGP public key.
  * @idx: the subkey index
  *
- * Returns the time when the OpenPGP key expires. A value of '0' means
- * that the key doesn't expire at all.
+ * Get subkey expiration time.  A value of '0' means that the key
+ * doesn't expire at all.
+ *
+ * Returns: the time when the OpenPGP key expires.
  **/
 time_t
-gnutls_openpgp_crt_get_subkey_expiration_time (gnutls_openpgp_crt_t key, unsigned int idx)
+gnutls_openpgp_crt_get_subkey_expiration_time (gnutls_openpgp_crt_t key,
+                                              unsigned int idx)
 {
   cdk_packet_t pkt;
   time_t expiredate;
@@ -855,10 +873,14 @@ gnutls_openpgp_crt_get_subkey_expiration_time (gnutls_openpgp_crt_t key, unsigne
  * @idx: the subkey index
  * @keyid: the buffer to save the keyid.
  *
- * Returns the 64-bit keyID of the OpenPGP key.
+ * Get the subkey's key-id.
+ *
+ * Returns: the 64-bit keyID of the OpenPGP key.
  **/
 int
-gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t key, unsigned int idx, gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t key,
+                                 unsigned int idx,
+                                 gnutls_openpgp_keyid_t keyid)
 {
   cdk_packet_t pkt;
   uint32_t kid[2];
@@ -868,7 +890,7 @@ gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t key, unsigned int idx, gn
       gnutls_assert ();
       return GNUTLS_E_INVALID_REQUEST;
     }
- 
+
   pkt = _get_public_subkey( key, idx);
   if (!pkt)
     return GNUTLS_E_OPENPGP_GETKEY_FAILED;
@@ -885,11 +907,13 @@ gnutls_openpgp_crt_get_subkey_id (gnutls_openpgp_crt_t key, unsigned int idx, gn
  * @key: the structure that contains the OpenPGP public key.
  * @keyid: the keyid.
  *
- * Returns the index of the subkey or a negative error value.
+ * Get subkey's index.
  *
+ * Returns: the index of the subkey or a negative error value.
  **/
 int
-gnutls_openpgp_crt_get_subkey_idx (gnutls_openpgp_crt_t key, const gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_crt_get_subkey_idx (gnutls_openpgp_crt_t key,
+                                  const gnutls_openpgp_keyid_t keyid)
 {
   cdk_packet_t pkt;
   int ret;
@@ -902,7 +926,7 @@ gnutls_openpgp_crt_get_subkey_idx (gnutls_openpgp_crt_t key, const gnutls_openpg
     }
 
   KEYID_IMPORT( kid, keyid);
-  ret = _gnutls_openpgp_find_subkey_idx( key->knode, kid, 0); 
+  ret = _gnutls_openpgp_find_subkey_idx( key->knode, kid, 0);
 
   if (ret < 0)
     {
@@ -913,21 +937,23 @@ gnutls_openpgp_crt_get_subkey_idx (gnutls_openpgp_crt_t key, const gnutls_openpg
 }
 
 /**
- * gnutls_openpgp_crt_get_subkey_usage - This function returns the key's usage
+ * gnutls_openpgp_crt_get_subkey_usage - returns the key's usage
  * @key: should contain a gnutls_openpgp_crt_t structure
  * @idx: the subkey index
  * @key_usage: where the key usage bits will be stored
  *
  * 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.
+ * key algorithm.  The key usage value will ORed values of
+ * %GNUTLS_KEY_DIGITAL_SIGNATURE or %GNUTLS_KEY_KEY_ENCIPHERMENT.
  *
  * A negative value may be returned in case of parsing error.
  *
+ * Returns: key usage value.
  */
 int
-gnutls_openpgp_crt_get_subkey_usage (gnutls_openpgp_crt_t key, unsigned int idx,
-                                 unsigned int *key_usage)
+gnutls_openpgp_crt_get_subkey_usage (gnutls_openpgp_crt_t key,
+                                    unsigned int idx,
+                                    unsigned int *key_usage)
 {
   cdk_packet_t pkt;
 
@@ -1372,11 +1398,14 @@ int ret;
  * @key: the structure that contains the OpenPGP public key.
  * @keyid: the struct to save the keyid.
  *
- * Returns the 64-bit preferred keyID of the OpenPGP key. If it hasn't
- * been set it returns GNUTLS_E_INVALID_REQUEST.
+ * Get preferred key id.  If it hasn't been set it returns
+ * %GNUTLS_E_INVALID_REQUEST.
+ *
+ * Returns: the 64-bit preferred keyID of the OpenPGP key.
  **/
 int
-gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key, gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key,
+                                        gnutls_openpgp_keyid_t keyid)
 {
   if (!key || !keyid || !key->preferred_set)
     {

diff --git a/lib/openpgp/privkey.c b/lib/openpgp/privkey.c
index 48837177b6c7ed1278862c84d51da6e3b1b383d8..5db295fc1bcce74eb7a86b79a3f05ed5de6b26b9 100644 (file)
--- a/lib/openpgp/privkey.c
+++ b/lib/openpgp/privkey.c
@@ -202,11 +202,13 @@ int algo;
 }
 
 /**
- * gnutls_openpgp_privkey_get_revoked_ status - Gets the revoked status of the key
+ * gnutls_openpgp_privkey_get_revoked_ status - Get the revoked status of the key
  * @key: the structure that contains the OpenPGP private key.
  *
- * Returns the true (1) or false (0) based on whether this key has been revoked
- * or not. A negative value indicates an error.
+ * Get revocation status of key.
+ *
+ * Returns: true (1) if the key has been revoked, or false (0) if it
+ *   has not, or a negative value indicates an error.
  *
  **/
 int
@@ -234,8 +236,10 @@ gnutls_openpgp_privkey_get_revoked_status (gnutls_openpgp_privkey_t key)
  * @fpr: the buffer to save the fingerprint, must hold at least 20 bytes.
  * @fprlen: the integer to save the length of the fingerprint.
  *
- * Returns the fingerprint of the OpenPGP key. Depends on the algorithm,
- * the fingerprint can be 16 or 20 bytes.
+ * Get the fingerprint of the OpenPGP key. Depends on the
+ * algorithm, the fingerprint can be 16 or 20 bytes.
+ *
+ * Returns: On success, 0 is returned, or an error code.
  **/
 int
 gnutls_openpgp_privkey_get_fingerprint (gnutls_openpgp_privkey_t key,
@@ -275,10 +279,13 @@ gnutls_openpgp_privkey_get_fingerprint (gnutls_openpgp_privkey_t key,
  * @key: the structure that contains the OpenPGP secret key.
  * @keyid: the buffer to save the keyid.
  *
- * Returns the 64-bit keyID of the OpenPGP key.
+ * Get key-id.
+ *
+ * Returns: the 64-bit keyID of the OpenPGP key.
  **/
 int
-gnutls_openpgp_privkey_get_key_id (gnutls_openpgp_privkey_t key, gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_privkey_get_key_id (gnutls_openpgp_privkey_t key,
+                                  gnutls_openpgp_keyid_t keyid)
 {
   cdk_packet_t pkt;
   uint32_t kid[2];
@@ -288,7 +295,7 @@ gnutls_openpgp_privkey_get_key_id (gnutls_openpgp_privkey_t key, gnutls_openpgp_
       gnutls_assert ();
       return GNUTLS_E_INVALID_REQUEST;
     }
- 
+
   pkt = cdk_kbnode_find_packet (key->knode, CDK_PKT_SECRET_KEY);
   if (!pkt)
     return GNUTLS_E_OPENPGP_GETKEY_FAILED;
@@ -302,15 +309,14 @@ gnutls_openpgp_privkey_get_key_id (gnutls_openpgp_privkey_t key, gnutls_openpgp_
 
 
 /**
-  * gnutls_openpgp_privkey_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_privkey_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_privkey_get_subkey_count (gnutls_openpgp_privkey_t key)
 {
@@ -323,7 +329,7 @@ gnutls_openpgp_privkey_get_subkey_count (gnutls_openpgp_privkey_t key)
       gnutls_assert ();
       return 0;
     }
-  
+
   ctx = NULL;
   subkeys = 0;
   while ((p = cdk_kbnode_walk (key->knode, &ctx, 0)))
@@ -356,13 +362,14 @@ static cdk_packet_t _get_secret_subkey(gnutls_openpgp_privkey_t key, unsigned in
 }
 
 /**
- * gnutls_openpgp_privkey_get_subkey_revoked_ status - Gets the revoked status of the key
+ * gnutls_openpgp_privkey_get_subkey_revoked_ status - Get the revoked status of the key
  * @key: the structure that contains the OpenPGP private key.
  * @idx: is the subkey index
  *
- * Returns the true (1) or false (0) based on whether this key has been revoked
- * or not. A negative value indicates an error.
+ * Get revocation status of key.
  *
+ * 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_subkey_revoked_status (gnutls_openpgp_privkey_t key, unsigned int idx)
@@ -425,7 +432,7 @@ gnutls_openpgp_privkey_get_subkey_pk_algorithm (gnutls_openpgp_privkey_t key,
       else
        algo = GNUTLS_E_UNKNOWN_PK_ALGORITHM;
     }
-  
+
   return algo;
 }
 
@@ -434,11 +441,13 @@ gnutls_openpgp_privkey_get_subkey_pk_algorithm (gnutls_openpgp_privkey_t key,
  * @key: the structure that contains the OpenPGP private key.
  * @keyid: the keyid.
  *
- * Returns the index of the subkey or a negative error value.
+ * Get index of subkey.
  *
+ * Returns: the index of the subkey or a negative error value.
  **/
 int
-gnutls_openpgp_privkey_get_subkey_idx (gnutls_openpgp_privkey_t key, const gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_privkey_get_subkey_idx (gnutls_openpgp_privkey_t key,
+                                      const gnutls_openpgp_keyid_t keyid)
 {
   cdk_packet_t pkt;
   int ret;
@@ -466,17 +475,20 @@ gnutls_openpgp_privkey_get_subkey_idx (gnutls_openpgp_privkey_t key, const gnutl
  * @key: the structure that contains the OpenPGP private key.
  * @idx: the subkey index
  *
- * Returns the timestamp when the OpenPGP key was created.
+ * Get subkey creation time.
+ *
+ * Returns: the timestamp when the OpenPGP key was created.
  **/
 time_t
-gnutls_openpgp_privkey_get_subkey_creation_time (gnutls_openpgp_privkey_t key, unsigned int idx)
+gnutls_openpgp_privkey_get_subkey_creation_time (gnutls_openpgp_privkey_t key,
+                                                unsigned int idx)
 {
   cdk_packet_t pkt;
   time_t timestamp;
 
   if (!key)
     return (time_t) - 1;
-    
+
   pkt = _get_secret_subkey( key, idx);
   if (pkt)
     timestamp = pkt->pkt.secret_key->pk->timestamp;
@@ -491,11 +503,14 @@ gnutls_openpgp_privkey_get_subkey_creation_time (gnutls_openpgp_privkey_t key, u
  * @key: the structure that contains the OpenPGP private key.
  * @idx: the subkey index
  *
- * Returns the time when the OpenPGP key expires. A value of '0' means
- * that the key doesn't expire at all.
+ * Get subkey expiration time.  A value of '0' means that the key
+ * doesn't expire at all.
+ *
+ * Returns: the time when the OpenPGP key expires.
  **/
 time_t
-gnutls_openpgp_privkey_get_subkey_expiration_time (gnutls_openpgp_privkey_t key, unsigned int idx)
+gnutls_openpgp_privkey_get_subkey_expiration_time (gnutls_openpgp_privkey_t key,
+                                                  unsigned int idx)
 {
   cdk_packet_t pkt;
   time_t expiredate;
@@ -518,10 +533,14 @@ gnutls_openpgp_privkey_get_subkey_expiration_time (gnutls_openpgp_privkey_t key,
  * @idx: the subkey index
  * @keyid: the buffer to save the keyid.
  *
- * Returns the 64-bit keyID of the OpenPGP key.
+ * Get the key-id for the subkey.
+ *
+ * Returns: the 64-bit keyID of the OpenPGP key.
  **/
 int
-gnutls_openpgp_privkey_get_subkey_id (gnutls_openpgp_privkey_t key, unsigned int idx, gnutls_openpgp_keyid_t keyid)
+gnutls_openpgp_privkey_get_subkey_id (gnutls_openpgp_privkey_t key,
+                                     unsigned int idx,
+                                     gnutls_openpgp_keyid_t keyid)
 {
   cdk_packet_t pkt;
   uint32_t kid[2];
@@ -531,7 +550,7 @@ gnutls_openpgp_privkey_get_subkey_id (gnutls_openpgp_privkey_t key, unsigned int
       gnutls_assert ();
       return GNUTLS_E_INVALID_REQUEST;
     }
- 
+
   pkt = _get_secret_subkey( key, idx);
   if (!pkt)
     return GNUTLS_E_OPENPGP_GETKEY_FAILED;