Doc fixes (silence gtk-doc warnings).

11 files changed, 154 insertions, 77 deletions

diff --git a/lib/x509/crl.c b/lib/x509/crl.c
index 5f130c1ec0..34fa53d4f2 100644
--- a/lib/x509/crl.c
+++ b/lib/x509/crl.c
@@ -44,7 +44,8 @@
   * by an Authority. The revocation lists are always signed with
   * the authority's private key.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -98,7 +99,8 @@ gnutls_x509_crl_deinit (gnutls_x509_crl_t crl)
   *
   * If the CRL is PEM encoded it should have a header of "X509 CRL".
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -319,7 +321,8 @@ gnutls_x509_crl_get_signature_algorithm (gnutls_x509_crl_t crl)
  *
  * This function will extract the signature field of a CRL.
  *
- * Returns 0 on success, and a negative value on error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. and a negative value on error.
  **/
 int
 gnutls_x509_crl_get_signature (gnutls_x509_crl_t crl,
@@ -625,7 +628,8 @@ cleanup:
   * If the structure is PEM encoded, it will have a header
   * of "BEGIN X509 CRL".
   *
-  * Returns 0 on success, and a negative value on failure.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. and a negative value on failure.
   *
   **/
 int
@@ -651,7 +655,8 @@ gnutls_x509_crl_export (gnutls_x509_crl_t crl,
   *
   * This function will copy an X.509 certificate structure. 
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   -*/
 int
diff --git a/lib/x509/crl_write.c b/lib/x509/crl_write.c
index 6834fc858c..db462631f2 100644
--- a/lib/x509/crl_write.c
+++ b/lib/x509/crl_write.c
@@ -49,7 +49,8 @@ static void disable_optional_stuff (gnutls_x509_crl_t crl);
   * must be one for CRL version 1, and so on. The CRLs generated
   * by gnutls should have a version number of 2.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -92,7 +93,8 @@ gnutls_x509_crl_set_version (gnutls_x509_crl_t crl, unsigned int version)
   * This must be the last step in a certificate CRL since all
   * the previously set parameters are now signed.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -132,7 +134,8 @@ gnutls_x509_crl_sign2 (gnutls_x509_crl_t crl, gnutls_x509_crt_t issuer,
   * This function is the same a gnutls_x509_crl_sign2() with no flags, and
   * SHA1 as the hash algorithm.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -149,7 +152,8 @@ gnutls_x509_crl_sign (gnutls_x509_crl_t crl, gnutls_x509_crt_t issuer,
   *
   * This function will set the time this CRL was issued.
   *
-  * Returns 0 on success, or a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value in case of an error.
   *
   **/
 int
@@ -171,7 +175,8 @@ gnutls_x509_crl_set_this_update (gnutls_x509_crl_t crl, time_t act_time)
   *
   * This function will set the time this CRL will be updated.
   *
-  * Returns 0 on success, or a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value in case of an error.
   *
   **/
 int
@@ -194,7 +199,8 @@ gnutls_x509_crl_set_next_update (gnutls_x509_crl_t crl, time_t exp_time)
   *
   * This function will set a revoked certificate's serial number to the CRL. 
   *
-  * Returns 0 on success, or a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value in case of an error.
   *
   **/
 int
@@ -259,7 +265,8 @@ gnutls_x509_crl_set_crt_serial (gnutls_x509_crl_t crl,
   *
   * This function will set a revoked certificate's serial number to the CRL. 
   *
-  * Returns 0 on success, or a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value in case of an error.
   *
   **/
 int
diff --git a/lib/x509/crq.c b/lib/x509/crq.c
index 9201709ca4..7ad60e1fa8 100644
--- a/lib/x509/crq.c
+++ b/lib/x509/crq.c
@@ -44,7 +44,8 @@
   *
   * This function will initialize a PKCS10 certificate request structure. 
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -101,7 +102,8 @@ gnutls_x509_crq_deinit (gnutls_x509_crq_t crq)
   *
   * If the Certificate is PEM encoded it should have a header of "NEW CERTIFICATE REQUEST".
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -424,7 +426,8 @@ cleanup:
   * This function will return the challenge password in the
   * request.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -451,7 +454,8 @@ gnutls_x509_crq_get_challenge_password (gnutls_x509_crq_t crq,
   * This function will set the attribute in the certificate request specified
   * by the given Object ID. The attribute must be be DER encoded.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -505,7 +509,8 @@ gnutls_x509_crq_set_attribute_by_oid (gnutls_x509_crq_t crq,
   * This function will return the attribute in the certificate request specified
   * by the given Object ID. The attribute will be DER encoded.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -540,7 +545,8 @@ gnutls_x509_crq_get_attribute_by_oid (gnutls_x509_crq_t crq,
   * not known (by gnutls) you should properly DER encode your data, and
   * call this function with raw_flag set.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -566,7 +572,8 @@ gnutls_x509_crq_set_dn_by_oid (gnutls_x509_crq_t crq, const char *oid,
   * This function will set the version of the certificate request. For
   * version 1 requests this must be one.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -639,7 +646,8 @@ gnutls_x509_crq_get_version (gnutls_x509_crq_t crq)
   * This function will set the public parameters from the given private key to the
   * request. Only RSA keys are currently supported.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -675,7 +683,8 @@ gnutls_x509_crq_set_key (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key)
   *
   * This function will set a challenge password to be used when revoking the request.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -809,7 +818,8 @@ gnutls_x509_crq_sign2 (gnutls_x509_crq_t crq, gnutls_x509_privkey_t key,
   * This function is the same a gnutls_x509_crq_sign2() with no flags, and
   * SHA1 as the hash algorithm.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
diff --git a/lib/x509/pkcs12.c b/lib/x509/pkcs12.c
index 15e13c36fb..060cc2e3b3 100644
--- a/lib/x509/pkcs12.c
+++ b/lib/x509/pkcs12.c
@@ -131,7 +131,8 @@ cleanup:
   * usually contain lists of X.509 Certificates and X.509 Certificate
   * revocation lists.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -186,7 +187,8 @@ gnutls_pkcs12_deinit (gnutls_pkcs12_t pkcs12)
   *
   * If the PKCS12 is PEM encoded it should have a header of "PKCS12".
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -570,7 +572,8 @@ cleanup:
   * @bag: An initialized bag, where the contents of the bag will be copied
   *
   * This function will return a Bag from the PKCS12 structure.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   * After the last Bag has been read GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
   * will be returned.
@@ -717,7 +720,8 @@ cleanup:
   * @bag: An initialized bag
   *
   * This function will insert a Bag into the PKCS12 structure.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -848,7 +852,8 @@ cleanup:
   * @pass: The password for the MAC
   *
   * This function will generate a MAC for the PKCS12 structure.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -980,7 +985,8 @@ cleanup:
   * @pass: The password for the MAC
   *
   * This function will verify the MAC for the PKCS12 structure.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
diff --git a/lib/x509/pkcs12_bag.c b/lib/x509/pkcs12_bag.c
index 0c613f1f56..c1c9885cfe 100644
--- a/lib/x509/pkcs12_bag.c
+++ b/lib/x509/pkcs12_bag.c
@@ -43,7 +43,8 @@
   * usually contain private keys, lists of X.509 Certificates and X.509 Certificate
   * revocation lists.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -145,7 +146,8 @@ gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t bag)
   * that is stored into the bag. Should not be accessed after the bag
   * is deleted.
   *
-  * Returns 0 on success and a negative error code on error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative error code on error.
   *
   **/
 int
@@ -475,7 +477,8 @@ gnutls_pkcs12_bag_set_crl (gnutls_pkcs12_bag_t bag, gnutls_x509_crl_t crl)
   * element. The key ID will be encoded as a 'Local key identifier' bag attribute,
   * which is usually used to distinguish the local private key and the certificate pair.
   * 
-  * Returns 0 on success, or a negative value on error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value on error.
   *
   **/
 int
@@ -518,7 +521,8 @@ gnutls_pkcs12_bag_set_key_id (gnutls_pkcs12_bag_t bag, int indx,
   * This function will return the key ID, of the specified bag element.
   * The key ID is usually used to distinguish the local private key and the certificate pair.
   * 
-  * Returns 0 on success, or a negative value on error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value on error.
   *
   **/
 int
@@ -552,7 +556,8 @@ gnutls_pkcs12_bag_get_key_id (gnutls_pkcs12_bag_t bag, int indx,
   * This function will return the friendly name, of the specified bag element.
   * The key ID is usually used to distinguish the local private key and the certificate pair.
   * 
-  * Returns 0 on success, or a negative value on error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value on error.
   *
   **/
 int
@@ -587,7 +592,8 @@ gnutls_pkcs12_bag_get_friendly_name (gnutls_pkcs12_bag_t bag, int indx,
   * element. The name will be encoded as a 'Friendly name' bag attribute,
   * which is usually used to set a user name to the local private key and the certificate pair.
   * 
-  * Returns 0 on success, or a negative value on error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value. or a negative value on error.
   *
   **/
 int
diff --git a/lib/x509/pkcs7.c b/lib/x509/pkcs7.c
index 399d93280d..a9acb63c1c 100644
--- a/lib/x509/pkcs7.c
+++ b/lib/x509/pkcs7.c
@@ -145,7 +145,8 @@ cleanup:
   * usually contain lists of X.509 Certificates and X.509 Certificate
   * revocation lists.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -199,7 +200,8 @@ gnutls_pkcs7_deinit (gnutls_pkcs7_t pkcs7)
   *
   * If the PKCS7 is PEM encoded it should have a header of "PKCS7".
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -266,7 +268,8 @@ cleanup:
   * @certificate_size: should hold the size of the certificate
   *
   * This function will return a certificate of the PKCS7 or RFC2630 certificate set.
-  * Returns 0 on success. If the provided buffer is not long enough,
+  * 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
@@ -526,7 +529,8 @@ cleanup:
   * @crt: the DER encoded certificate to be added
   *
   * This function will add a certificate to the PKCS7 or RFC2630 certificate set.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -620,7 +624,8 @@ cleanup:
   * 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 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -725,7 +730,8 @@ cleanup:
   * @crl_size: should hold the size of the crl
   *
   * This function will return a crl of the PKCS7 or RFC2630 crl set.
-  * Returns 0 on success. If the provided buffer is not long enough,
+  * 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
@@ -844,7 +850,8 @@ gnutls_pkcs7_get_crl_count (gnutls_pkcs7_t pkcs7)
   * @crl: the DER encoded crl to be added
   *
   * This function will add a crl to the PKCS7 or RFC2630 crl set.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -926,7 +933,8 @@ cleanup:
   * @crl: the DER encoded crl to be added
   *
   * This function will add a parsed crl to the PKCS7 or RFC2630 crl set.
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
diff --git a/lib/x509/privkey_pkcs8.c b/lib/x509/privkey_pkcs8.c
index 0f5989d47a..84fce06d78 100644
--- a/lib/x509/privkey_pkcs8.c
+++ b/lib/x509/privkey_pkcs8.c
@@ -1045,7 +1045,8 @@ error:
   * or "PRIVATE KEY". You only need to specify the flags if the key is DER encoded, since
   * in that case the encryption status cannot be auto-detected.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
diff --git a/lib/x509/sign.c b/lib/x509/sign.c
index 0337ffdb2b..cd94be8aee 100644
--- a/lib/x509/sign.c
+++ b/lib/x509/sign.c
@@ -302,7 +302,8 @@ _gnutls_x509_sign_tbs (ASN1_TYPE cert, const char *tbs_name,
   * This function will sign a CRL or a certificate with the issuer's private key, and
   * will copy the issuer's information into the CRL or certificate.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   -*/
 int
diff --git a/lib/x509/verify.c b/lib/x509/verify.c
index c2217fa2cc..ecca86a2d2 100644
--- a/lib/x509/verify.c
+++ b/lib/x509/verify.c
@@ -761,7 +761,8 @@ _gnutls_x509_privkey_verify_signature (const gnutls_datum_t * tbs,
   *
   * GNUTLS_CERT_REVOKED: a certificate in the chain has been revoked.
   *
-  * Returns 0 on success and a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative value in case of an error.
   *
   **/
 int
@@ -797,7 +798,8 @@ gnutls_x509_crt_list_verify (const gnutls_x509_crt_t * cert_list,
   * This function will try to verify the given certificate and return its status. 
   * The verification output in this functions cannot be GNUTLS_CERT_NOT_VALID.
   *
-  * Returns 0 on success and a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative value in case of an error.
   *
   **/
 int
@@ -856,7 +858,8 @@ gnutls_x509_crl_check_issuer (gnutls_x509_crl_t cert,
   * See gnutls_x509_crt_list_verify() for a detailed description of
   * return values.
   *
-  * Returns 0 on success and a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative value in case of an error.
   *
   **/
 int
diff --git a/lib/x509/x509.c b/lib/x509/x509.c
index 919c21591e..ca3278df92 100644
--- a/lib/x509/x509.c
+++ b/lib/x509/x509.c
@@ -40,7 +40,8 @@
   *
   * This function will initialize an X.509 certificate structure.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -74,7 +75,8 @@ gnutls_x509_crt_init (gnutls_x509_crt_t * cert)
   *
   * This function will copy an X.509 certificate structure. 
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   -*/
 int
@@ -154,7 +156,8 @@ gnutls_x509_crt_deinit (gnutls_x509_crt_t cert)
   * If the Certificate is PEM encoded it should have a header of "X509 CERTIFICATE", or
   * "CERTIFICATE".
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -498,7 +501,8 @@ gnutls_x509_crt_get_signature_algorithm (gnutls_x509_crt_t cert)
  *
  * This function will extract the signature field of a certificate.
  *
- * Returns 0 on success, and a negative value on error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. and a negative value on error.
  **/
 int
 gnutls_x509_crt_get_signature (gnutls_x509_crt_t cert,
@@ -637,7 +641,8 @@ gnutls_x509_crt_get_expiration_time (gnutls_x509_crt_t cert)
   * large serial numbers, thus it may be wise to handle it as something
   * opaque. 
   *
-  * Returns 0 on success and a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative value in case of an error.
   *
   **/
 int
@@ -677,7 +682,8 @@ gnutls_x509_crt_get_serial (gnutls_x509_crt_t cert, void *result,
   * This is obtained by the X.509 Subject Key identifier extension
   * field (2.5.29.14). 
   *
-  * Returns 0 on success and a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative value in case of an error.
   *
   **/
 int
@@ -764,7 +770,8 @@ gnutls_x509_crt_get_subject_key_id (gnutls_x509_crt_t cert, void *ret,
   * field (2.5.29.35). Note that this function only returns the keyIdentifier
   * field of the extension.
   *
-  * Returns 0 on success and a negative value in case of an error.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.and a negative value in case of an error.
   *
   **/
 int
@@ -1752,7 +1759,8 @@ cleanup:
  * This function will return a pointer to the DER encoded DN structure
  * and the length.
  *
- * Returns 0 on success or a negative value on error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.or a negative value on error.
  *
  **/
 int
@@ -1770,7 +1778,8 @@ gnutls_x509_crt_get_raw_issuer_dn (gnutls_x509_crt_t cert,
  * This function will return a pointer to the DER encoded DN structure and
  * the length.
  *
- * Returns 0 on success, or a negative value on error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. or a negative value on error.
  *
  **/
 int
diff --git a/lib/x509/x509_write.c b/lib/x509/x509_write.c
index dda29d5987..76d76eaaaa 100644
--- a/lib/x509/x509_write.c
+++ b/lib/x509/x509_write.c
@@ -58,7 +58,8 @@ static void disable_optional_stuff (gnutls_x509_crt_t cert);
  * not known (by gnutls) you should properly DER encode your data,
  * and call this function with @raw_flag set.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t crt, const char *oid,
@@ -96,7 +97,8 @@ gnutls_x509_crt_set_dn_by_oid (gnutls_x509_crt_t crt, const char *oid,
  * operation will copy the signer's name as the issuer of the
  * certificate.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_issuer_dn_by_oid (gnutls_x509_crt_t crt,
@@ -128,7 +130,8 @@ gnutls_x509_crt_set_issuer_dn_by_oid (gnutls_x509_crt_t crt,
  * certificate naming style.  Note that if @name is %NULL, you MUST
  * set it later by using gnutls_x509_crt_set_dn_by_oid() or similar.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t crt,gnutls_x509_crt_t eecrt,
@@ -174,7 +177,8 @@ gnutls_x509_crt_set_proxy_dn (gnutls_x509_crt_t crt,gnutls_x509_crt_t eecrt,
  * functions such as gnutls_x509_crt_set_subject_alternative_name()
  * or gnutls_x509_crt_set_key_usage().
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_version (gnutls_x509_crt_t crt, unsigned int version)
@@ -210,7 +214,8 @@ gnutls_x509_crt_set_version (gnutls_x509_crt_t crt, unsigned int version)
   * private key to the certificate. Only RSA keys are currently
   * supported.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+  *   negative error value.
   *
   **/
 int
@@ -248,7 +253,8 @@ gnutls_x509_crt_set_key (gnutls_x509_crt_t crt, gnutls_x509_privkey_t key)
  * given certificate request to the certificate. Only RSA keys are
  * currently supported.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_crq (gnutls_x509_crt_t crt, gnutls_x509_crq_t crq)
@@ -296,7 +302,8 @@ gnutls_x509_crt_set_crq (gnutls_x509_crt_t crt, gnutls_x509_crq_t crq)
  * the certificate.  The extension data should be binary data DER
  * encoded.
  *
- * Returns 0 on success and a negative value in case of an error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.and a negative value in case of an error.
  **/
 int
 gnutls_x509_crt_set_extension_by_oid (gnutls_x509_crt_t crt,
@@ -339,7 +346,8 @@ gnutls_x509_crt_set_extension_by_oid (gnutls_x509_crt_t crt,
  *
  * This function will set the basicConstraints certificate extension.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t crt,
@@ -389,7 +397,8 @@ gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t crt,
  * Use gnutls_x509_crt_set_basic_constraints() if you want to control
  * the pathLenConstraint field too.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t crt, unsigned int ca)
@@ -404,7 +413,8 @@ gnutls_x509_crt_set_ca_status (gnutls_x509_crt_t crt, unsigned int ca)
  *
  * This function will set the keyUsage certificate extension.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t crt, unsigned int usage)
@@ -451,7 +461,8 @@ gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t crt, unsigned int usage)
  * This function will set the subject alternative name certificate
  * extension.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_subject_alternative_name (gnutls_x509_crt_t crt,
@@ -519,7 +530,8 @@ gnutls_x509_crt_set_subject_alternative_name (gnutls_x509_crt_t crt,
  *
  * This function will set the proxyCertInfo extension.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_proxy (gnutls_x509_crt_t crt,
@@ -579,7 +591,8 @@ gnutls_x509_crt_set_proxy (gnutls_x509_crt_t crt,
  * This must be the last step in a certificate generation since all
  * the previously set parameters are now signed.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
@@ -618,7 +631,8 @@ gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
  * This function is the same a gnutls_x509_crt_sign2() with no flags,
  * and SHA1 as the hash algorithm.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_sign (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
@@ -635,7 +649,8 @@ gnutls_x509_crt_sign (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
  * This function will set the time this Certificate was or will be
  * activated.
  *
- * Returns 0 on success, or a negative value in case of an error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. or a negative value in case of an error.
  **/
 int
 gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t cert, time_t act_time)
@@ -658,7 +673,8 @@ gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t cert, time_t act_time)
  *
  * This function will set the time this Certificate will expire.
  *
- * Returns 0 on success, or a negative value in case of an error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. or a negative value in case of an error.
  **/
 int
 gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t cert, time_t exp_time)
@@ -683,7 +699,8 @@ gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t cert, time_t exp_time)
  * serial numbers, thus it may be wise to handle it as something
  * opaque.
  *
- * Returns 0 on success, or a negative value in case of an error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. or a negative value in case of an error.
  **/
 int
 gnutls_x509_crt_set_serial (gnutls_x509_crt_t cert, const void *serial,
@@ -739,7 +756,8 @@ disable_optional_stuff (gnutls_x509_crt_t cert)
  *
  * This function will set the CRL distribution points certificate extension.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t crt,
@@ -806,7 +824,8 @@ gnutls_x509_crt_set_crl_dist_points (gnutls_x509_crt_t crt,
  * extension, from the source to the destination certificate.
  * This may be useful to copy from a CA certificate to issued ones.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t dst,
@@ -857,7 +876,8 @@ gnutls_x509_crt_cpy_crl_dist_points (gnutls_x509_crt_t dst,
  * This function will set the X.509 certificate's subject key ID
  * extension.
  *
- * Returns 0 on success, or a negative value in case of an error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. or a negative value in case of an error.
  **/
 int
 gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t cert,
@@ -919,7 +939,8 @@ gnutls_x509_crt_set_subject_key_id (gnutls_x509_crt_t cert,
  * This function will set the X.509 certificate's authority key ID extension.
  * Only the keyIdentifier field can be set with this function.
  *
- * Returns 0 on success, or a negative value in case of an error.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value. or a negative value in case of an error.
  **/
 int
 gnutls_x509_crt_set_authority_key_id (gnutls_x509_crt_t cert,