From: Simon Josefsson <simon@josefsson.org>
Date: Thu, 6 Mar 2008 15:13:57 +0000 (+0100)
Subject: Doc fixes.
X-Git-Tag: gnutls_2_3_3~6^2~23
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d35108335cf1536e660108e025edf8a10c67993d;p=thirdparty%2Fgnutls.git

Doc fixes.
---

diff --git a/lib/gnutls_auth.c b/lib/gnutls_auth.c
index fada7f3d4a..dc20149566 100644
--- a/lib/gnutls_auth.c
+++ b/lib/gnutls_auth.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation
+ * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -156,9 +156,13 @@ gnutls_credentials_set (gnutls_session_t session,
   * Returns type of credentials for the current authentication schema.
   * The returned information is to be used to distinguish the function used
   * to access authentication data.
-  * 
-  * Eg. for CERTIFICATE ciphersuites (key exchange algorithms: KX_RSA, KX_DHE_RSA),
-  * the same function are to be used to access the authentication data.
+  *
+  * Eg. for CERTIFICATE ciphersuites (key exchange algorithms: KX_RSA,
+  * KX_DHE_RSA), the same function are to be used to access the
+  * authentication data.
+  *
+  * Returns: The type of credentials for the current authentication
+  *   schema, an #gnutls_credentials_type_t type.
   **/
 gnutls_credentials_type_t
 gnutls_auth_get_type (gnutls_session_t session)
@@ -181,7 +185,9 @@ gnutls_auth_get_type (gnutls_session_t session)
   * Returns the type of credentials that were used for server authentication.
   * The returned information is to be used to distinguish the function used
   * to access authentication data.
-  * 
+  *
+  * Returns: The type of credentials for the server authentication
+  *   schema, an #gnutls_credentials_type_t type.
   **/
 gnutls_credentials_type_t
 gnutls_auth_server_get_type (gnutls_session_t session)
@@ -199,7 +205,9 @@ gnutls_auth_server_get_type (gnutls_session_t session)
   * Returns the type of credentials that were used for client authentication.
   * The returned information is to be used to distinguish the function used
   * to access authentication data.
-  * 
+  *
+  * Returns: The type of credentials for the client authentication
+  *   schema, an #gnutls_credentials_type_t type.
   **/
 gnutls_credentials_type_t
 gnutls_auth_client_get_type (gnutls_session_t session)
diff --git a/lib/gnutls_openpgp.c b/lib/gnutls_openpgp.c
index 97f90cef5d..51a99a1d50 100644
--- a/lib/gnutls_openpgp.c
+++ b/lib/gnutls_openpgp.c
@@ -323,8 +323,8 @@ stream_to_datum (cdk_stream_t inp, gnutls_datum_t * raw)
  * This funtion is used to load OpenPGP keys into the GnuTLS credential 
  * structure. The files should contain non encrypted keys.
  *
- * Returns a negative error value on error.
- *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t
@@ -332,7 +332,8 @@ gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t
 					const gnutls_datum_t * ikey,
 					gnutls_openpgp_crt_fmt_t format)
 {
-  return gnutls_certificate_set_openpgp_key_mem2( res, icert, ikey, NULL, format);
+  return gnutls_certificate_set_openpgp_key_mem2 (res, icert, ikey,
+						  NULL, format);
 }
 
 
@@ -343,11 +344,12 @@ gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t
  * @keyfile: the file that contains the secret key.
  * @format: the format of the keys
  *
- * This funtion is used to load OpenPGP keys into the GnuTLS credentials structure.
- * The files should only contain one key which is not encrypted.
- *
- * Returns a negative error value on error.
+ * This funtion is used to load OpenPGP keys into the GnuTLS
+ * credentials structure.  The files should only contain one key which
+ * is not encrypted.
  *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t
@@ -355,7 +357,8 @@ gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t
 					 const char *keyfile,
 					 gnutls_openpgp_crt_fmt_t format)
 {
-  return gnutls_certificate_set_openpgp_key_file2( res, certfile, keyfile, NULL, format);
+  return gnutls_certificate_set_openpgp_key_file2 (res, certfile,
+						   keyfile, NULL, format);
 }
 
 static int get_keyid( gnutls_openpgp_keyid_t keyid, const char* str)
@@ -385,14 +388,16 @@ static int get_keyid( gnutls_openpgp_keyid_t keyid, const char* str)
  * @subkey_id: a hex encoded subkey id
  * @format: the format of the keys
  *
- * This funtion is used to load OpenPGP keys into the GnuTLS credentials structure.
- * The files should only contain one key which is not encrypted.
- *
- * The special keyword "auto" is also accepted as &subkey_id. In that case
- * the gnutls_openpgp_crt_get_auth_subkey() will be used to retrieve the subkey.
+ * This funtion is used to load OpenPGP keys into the GnuTLS
+ * credentials structure.  The files should only contain one key which
+ * is not encrypted.
  *
- * Returns a negative error value on error.
+ * The special keyword "auto" is also accepted as &subkey_id. In that
+ * case the gnutls_openpgp_crt_get_auth_subkey() will be used to
+ * retrieve the subkey.
  *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t
@@ -404,7 +409,7 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t
   gnutls_openpgp_privkey_t key;
   gnutls_openpgp_crt_t cert;
   int ret;
-  
+
   ret = gnutls_openpgp_privkey_init( &key);
   if (ret < 0) {
     gnutls_assert();
@@ -481,8 +486,8 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t
  * The special keyword "auto" is also accepted as &subkey_id. In that case
  * the gnutls_openpgp_crt_get_auth_subkey() will be used to retrieve the subkey.
  *
- * Returns a negative error value on error.
- *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_certificate_set_openpgp_key_file2 (gnutls_certificate_credentials_t
@@ -585,8 +590,8 @@ gnutls_openpgp_count_key_names (const gnutls_datum_t * cert)
  * is needed for an operations. The keyring will also be used at the
  * verification functions.
  *
- * Returns a negative error value on error.
- *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c,
@@ -629,8 +634,8 @@ gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c,
  * is needed for an operations. The keyring will also be used at the
  * verification functions.
  *
- * Returns a negative error value on error.
- *
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t
@@ -918,23 +923,23 @@ _gnutls_openpgp_crt_to_gcert (gnutls_cert * gcert, gnutls_openpgp_crt_t cert)
  * @hash: holds the data to be signed
  * @signature: will contain newly allocated signature
  *
- * This function will sign the given hash using the private key.
- * You should use gnutls_openpgp_privkey_set_subkey() before calling this function
- * to set the subkey to use.
+ * This function will sign the given hash using the private key.  You
+ * should use gnutls_openpgp_privkey_set_subkey() before calling this
+ * function to set the subkey to use.
  *
- * Return value: In case of failure a negative value will be returned,
- * and 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a
+ *   negative error value.
  **/
 int
 gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t key,
 				  const gnutls_datum_t * hash,
 				  gnutls_datum_t * signature)
 {
-int result, i;
-mpi_t params[MAX_PUBLIC_PARAMS_SIZE];
-int params_size = MAX_PUBLIC_PARAMS_SIZE;
-int pk_algorithm;
-gnutls_openpgp_keyid_t keyid;
+  int result, i;
+  mpi_t params[MAX_PUBLIC_PARAMS_SIZE];
+  int params_size = MAX_PUBLIC_PARAMS_SIZE;
+  int pk_algorithm;
+  gnutls_openpgp_keyid_t keyid;
 
   if (key == NULL)
     {
@@ -946,15 +951,17 @@ gnutls_openpgp_keyid_t keyid;
   if (result == 0)
     {
       uint32_t kid[2];
-      
+
       KEYID_IMPORT( kid, keyid);
-      result = _gnutls_openpgp_privkey_get_mpis( key, kid, params, &params_size);
+      result = _gnutls_openpgp_privkey_get_mpis (key, kid,
+						 params, &params_size);
     }
   else
     {
-      result = _gnutls_openpgp_privkey_get_mpis( key, NULL, params, &params_size);
+      result = _gnutls_openpgp_privkey_get_mpis (key, NULL,
+						 params, &params_size);
     }
-    
+
   if (result < 0)
     {
       gnutls_assert ();
@@ -968,7 +975,7 @@ gnutls_openpgp_keyid_t keyid;
 
   for (i=0;i<params_size;i++)
     _gnutls_mpi_release( &params[i]);
-			 
+
   if (result < 0)
     {
       gnutls_assert ();
diff --git a/lib/gnutls_srp.c b/lib/gnutls_srp.c
index 4c9cdef772..d2e6498e5b 100644
--- a/lib/gnutls_srp.c
+++ b/lib/gnutls_srp.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation
+ * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -422,7 +422,8 @@ gnutls_srp_free_client_credentials (gnutls_srp_client_credentials_t sc)
   * This structure is complex enough to manipulate directly thus
   * this helper function is provided in order to allocate it.
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an
+  *   error code.
   **/
 int
 gnutls_srp_allocate_client_credentials (gnutls_srp_client_credentials_t * sc)
@@ -441,11 +442,14 @@ gnutls_srp_allocate_client_credentials (gnutls_srp_client_credentials_t * sc)
   * @username: is the user's userid
   * @password: is the user's password
   *
-  * This function sets the username and password, in a gnutls_srp_client_credentials_t structure.
-  * Those will be used in SRP authentication. @username and @password should be ASCII
-  * strings or UTF-8 strings prepared using the "SASLprep" profile of "stringprep".
+  * This function sets the username and password, in a
+  * #gnutls_srp_client_credentials_t structure.  Those will be used in
+  * SRP authentication.  @username and @password should be ASCII
+  * strings or UTF-8 strings prepared using the "SASLprep" profile of
+  * "stringprep".
   *
-  * Returns 0 on success.
+  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an
+  *   error code.
   **/
 int
 gnutls_srp_set_client_credentials (gnutls_srp_client_credentials_t res,
@@ -493,10 +497,11 @@ gnutls_srp_free_server_credentials (gnutls_srp_server_credentials_t sc)
   * gnutls_srp_allocate_server_credentials - Used to allocate an gnutls_srp_server_credentials_t structure
   * @sc: is a pointer to an #gnutls_srp_server_credentials_t structure.
   *
-  * This structure is complex enough to manipulate directly thus
-  * this helper function is provided in order to allocate it.
-  * 
-  * Returns 0 on success.
+  * This structure is complex enough to manipulate directly thus this
+  * helper function is provided in order to allocate it.
+  *
+  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an
+  *   error code.
   **/
 int
 gnutls_srp_allocate_server_credentials (gnutls_srp_server_credentials_t * sc)
@@ -515,11 +520,13 @@ gnutls_srp_allocate_server_credentials (gnutls_srp_server_credentials_t * sc)
   * @password_file: is the SRP password file (tpasswd)
   * @password_conf_file: is the SRP password conf file (tpasswd.conf)
   *
-  * This function sets the password files, in a gnutls_srp_server_credentials_t structure.
-  * Those password files hold usernames and verifiers and will be used for SRP authentication.
-  *
-  * Returns 0 on success.
+  * This function sets the password files, in a
+  * #gnutls_srp_server_credentials_t structure.  Those password files
+  * hold usernames and verifiers and will be used for SRP
+  * authentication.
   *
+  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an
+  *   error code.
   **/
 int
 gnutls_srp_set_server_credentials_file (gnutls_srp_server_credentials_t
@@ -643,10 +650,11 @@ gnutls_srp_set_client_credentials_function (gnutls_srp_client_credentials_t
   * gnutls_srp_server_get_username - return the username of the peer
   * @session: is a gnutls session
   *
-  * This function will return the username of the peer. This should only be
-  * called in case of SRP authentication and in case of a server.
-  * Returns NULL in case of an error.
+  * This function will return the username of the peer.  This should
+  * only be called in case of SRP authentication and in case of a
+  * server.  Returns NULL in case of an error.
   *
+  * Returns: SRP username of the peer, or NULL in case of error.
   **/
 const char *
 gnutls_srp_server_get_username (gnutls_session_t session)
diff --git a/libextra/gnutls_ia.c b/libextra/gnutls_ia.c
index df45511bd0..ee23648d72 100644
--- a/libextra/gnutls_ia.c
+++ b/libextra/gnutls_ia.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005, 2006 Free Software Foundation
+ * Copyright (C) 2005, 2006, 2008 Free Software Foundation
  *
  * Author: Simon Josefsson
  *
@@ -390,7 +390,7 @@ gnutls_ia_verify_endphase (gnutls_session_t session, const char *checksum)
  * this function again, with the same parameters; alternatively you
  * could provide a %NULL pointer for data, and 0 for size.
  *
- * Returns the number of bytes sent, or a negative error code.
+ * Returns: The number of bytes sent, or a negative error code.
  **/
 ssize_t
 gnutls_ia_send (gnutls_session_t session, const char *data, size_t sizeofdata)
@@ -426,7 +426,7 @@ gnutls_ia_send (gnutls_session_t session, const char *data, size_t sizeofdata)
  * this function again, with the same parameters; alternatively you
  * could provide a NULL pointer for data, and 0 for size.
  *
- * Returns the number of bytes received.  A negative error code is
+ * Returns: The number of bytes received.  A negative error code is
  * returned in case of an error.  The
  * %GNUTLS_E_WARNING_IA_IPHF_RECEIVED and
  * %GNUTLS_E_WARNING_IA_FPHF_RECEIVED errors are returned when an
@@ -658,7 +658,8 @@ gnutls_ia_handshake (gnutls_session_t session)
  * support TLS/IA).  Use gnutls_ia_require_inner_phase() to toggle the
  * TLS/IA mode.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  **/
 int
 gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t * sc)
@@ -733,7 +734,6 @@ gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t cred,
  *
  * Sets the pointer that will be provided to the TLS/IA callback
  * function as the first argument.
- *
  **/
 void
 gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void *ptr)
@@ -748,6 +748,7 @@ gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void *ptr)
  * Returns the pointer that will be provided to the TLS/IA callback
  * function as the first argument.
  *
+ * Returns: The client callback data pointer.
  **/
 void *
 gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t cred)
@@ -767,7 +768,8 @@ gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t cred)
  * support TLS/IA).  Use gnutls_ia_require_inner_phase() to toggle the
  * TLS/IA mode.
  *
- * Returns 0 on success.
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
  **/
 int
 gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t * sc)
@@ -849,7 +851,6 @@ gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t cred,
  *
  * Sets the pointer that will be provided to the TLS/IA callback
  * function as the first argument.
- *
  **/
 void
 gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void *ptr)
@@ -864,6 +865,7 @@ gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void *ptr)
  * Returns the pointer that will be provided to the TLS/IA callback
  * function as the first argument.
  *
+ * Returns: The server callback data pointer.
  **/
 void *
 gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_t cred)