Doc fix.

1 files changed, 210 insertions, 206 deletions

diff --git a/lib/gnutls_ui.c b/lib/gnutls_ui.c
index e90af7eae8..84046b09cb 100644
--- a/lib/gnutls_ui.c
+++ b/lib/gnutls_ui.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
  *
@@ -39,21 +39,19 @@
 /* ANON & DHE */
 
 /**
-  * gnutls_dh_set_prime_bits - Used to set the bits for a DH ciphersuite
-  * @session: is a #gnutls_session_t structure.
-  * @bits: is the number of bits
-  *
-  * This function sets the number of bits, for use in an 
-  * Diffie Hellman key exchange. This is used both in DH ephemeral and
-  * DH anonymous cipher suites. This will set the
-  * minimum size of the prime that will be used for the handshake.
-  *
-  * In the client side it sets the minimum accepted number of bits.
-  * If a server sends a prime with less bits than that 
-  * GNUTLS_E_DH_PRIME_UNACCEPTABLE will be returned by the
-  * handshake.
-  *
-  **/
+ * gnutls_dh_set_prime_bits - Used to set the bits for a DH ciphersuite
+ * @session: is a #gnutls_session_t structure.
+ * @bits: is the number of bits
+ *
+ * This function sets the number of bits, for use in an Diffie Hellman
+ * key exchange.  This is used both in DH ephemeral and DH anonymous
+ * cipher suites.  This will set the minimum size of the prime that
+ * will be used for the handshake.
+ *
+ * In the client side it sets the minimum accepted number of bits.  If
+ * a server sends a prime with less bits than that
+ * %GNUTLS_E_DH_PRIME_UNACCEPTABLE will be returned by the handshake.
+ **/
 void
 gnutls_dh_set_prime_bits (gnutls_session_t session, unsigned int bits)
 {
@@ -62,19 +60,20 @@ gnutls_dh_set_prime_bits (gnutls_session_t session, unsigned int bits)
 
 
 /**
-  * gnutls_dh_get_group - return the group of the DH authentication
-  * @session: is a gnutls session
-  * @raw_gen: will hold the generator.
-  * @raw_prime: will hold the prime.
-  *
-  * This function will return the group parameters used in the last Diffie Hellman 
-  * authentication with the peer. These are the prime and the generator used.
-  * This function should be used for both anonymous and ephemeral diffie Hellman.
-  * The output parameters must be freed with gnutls_free().
-  *
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_dh_get_group - return the group of the DH authentication
+ * @session: is a gnutls session
+ * @raw_gen: will hold the generator.
+ * @raw_prime: will hold the prime.
+ *
+ * This function will return the group parameters used in the last
+ * Diffie Hellman authentication with the peer.  These are the prime
+ * and the generator used.  This function should be used for both
+ * anonymous and ephemeral diffie Hellman.  The output parameters must
+ * be freed with gnutls_free().
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_dh_get_group (gnutls_session_t session,
 		     gnutls_datum_t * raw_gen, gnutls_datum_t * raw_prime)
@@ -129,17 +128,18 @@ gnutls_dh_get_group (gnutls_session_t session,
 }
 
 /**
-  * gnutls_dh_get_pubkey - return the peer's public key used in DH authentication
-  * @session: is a gnutls session
-  * @raw_key: will hold the public key.
-  *
-  * This function will return the peer's public key used in the last Diffie Hellman authentication.
-  * This function should be used for both anonymous and ephemeral diffie Hellman.
-  * The output parameters must be freed with gnutls_free().
-  *
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_dh_get_pubkey - return the peer's public key used in DH authentication
+ * @session: is a gnutls session
+ * @raw_key: will hold the public key.
+ *
+ * This function will return the peer's public key used in the last
+ * Diffie Hellman authentication.  This function should be used for
+ * both anonymous and ephemeral diffie Hellman.  The output
+ * parameters must be freed with gnutls_free().
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_dh_get_pubkey (gnutls_session_t session, gnutls_datum_t * raw_key)
 {
@@ -185,18 +185,18 @@ gnutls_dh_get_pubkey (gnutls_session_t session, gnutls_datum_t * raw_key)
 }
 
 /**
-  * gnutls_rsa_export_get_pubkey - return the peer's public key used in RSA-EXPORT authentication
-  * @session: is a gnutls session
-  * @exponent: will hold the exponent.
-  * @modulus: will hold the modulus.
-  *
-  * This function will return the peer's public key exponent and
-  * modulus used in the last RSA-EXPORT authentication.  The output
-  * parameters must be freed with gnutls_free().
-  *
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_rsa_export_get_pubkey - return the peer's public key used in RSA-EXPORT authentication
+ * @session: is a gnutls session
+ * @exponent: will hold the exponent.
+ * @modulus: will hold the modulus.
+ *
+ * This function will return the peer's public key exponent and
+ * modulus used in the last RSA-EXPORT authentication.  The output
+ * parameters must be freed with gnutls_free().
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_rsa_export_get_pubkey (gnutls_session_t session,
 			      gnutls_datum_t * exponent,
@@ -236,14 +236,16 @@ gnutls_rsa_export_get_pubkey (gnutls_session_t session,
 
 
 /**
-  * gnutls_dh_get_secret_bits - return the bits used in DH authentication
-  * @session: is a gnutls session
-  *
-  * This function will return the bits used in the last Diffie Hellman authentication
-  * with the peer. Should be used for both anonymous and ephemeral diffie Hellman.
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_dh_get_secret_bits - return the bits used in DH authentication
+ * @session: is a gnutls session
+ *
+ * This function will return the bits used in the last Diffie Hellman
+ * authentication with the peer.  Should be used for both anonymous
+ * and ephemeral diffie Hellman.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_dh_get_secret_bits (gnutls_session_t session)
 {
@@ -285,14 +287,16 @@ gnutls_dh_get_secret_bits (gnutls_session_t session)
 
 
 /**
-  * gnutls_dh_get_prime_bits - return the bits used in DH authentication
-  * @session: is a gnutls session
-  *
-  * This function will return the bits of the prime used in the last Diffie Hellman authentication
-  * with the peer. Should be used for both anonymous and ephemeral diffie Hellman.
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_dh_get_prime_bits - return the bits used in DH authentication
+ * @session: is a gnutls session
+ *
+ * This function will return the bits of the prime used in the last
+ * Diffie Hellman authentication with the peer.  Should be used for
+ * both anonymous and ephemeral diffie Hellman.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_dh_get_prime_bits (gnutls_session_t session)
 {
@@ -341,14 +345,14 @@ gnutls_dh_get_prime_bits (gnutls_session_t session)
 }
 
 /**
-  * gnutls_rsa_export_get_modulus_bits - return the bits used in RSA-export key exchange
-  * @session: is a gnutls session
-  *
-  * This function will return the bits used in the last RSA-EXPORT key exchange
-  * with the peer. 
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_rsa_export_get_modulus_bits - return the bits used in RSA-export key exchange
+ * @session: is a gnutls session
+ *
+ * Get the export RSA parameter's modulus size.
+ *
+ * Returns: the bits used in the last RSA-EXPORT key exchange with the
+ *   peer, or a negative value in case of error.
+ **/
 int
 gnutls_rsa_export_get_modulus_bits (gnutls_session_t session)
 {
@@ -362,14 +366,16 @@ gnutls_rsa_export_get_modulus_bits (gnutls_session_t session)
 }
 
 /**
-  * gnutls_dh_get_peers_public_bits - return the bits used in DH authentication
-  * @session: is a gnutls session
-  *
-  * This function will return the bits used in the last Diffie Hellman authentication
-  * with the peer. Should be used for both anonymous and ephemeral diffie Hellman.
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_dh_get_peers_public_bits - return the bits used in DH authentication
+ * @session: is a gnutls session
+ *
+ * Get the Diffie-Hellman public key bit size.  Can be used for both
+ * anonymous and ephemeral diffie Hellman.
+ *
+ * Returns: the public key bit size used in the last Diffie Hellman
+ * authentication with the peer, or a negative value in case of
+ * error.
+ **/
 int
 gnutls_dh_get_peers_public_bits (gnutls_session_t session)
 {
@@ -422,16 +428,17 @@ gnutls_dh_get_peers_public_bits (gnutls_session_t session)
 /* CERTIFICATE STUFF */
 
 /**
-  * gnutls_certificate_get_ours - return the raw certificate sent in the last handshake
-  * @session: is a gnutls session
-  *
-  * This function will return the certificate as sent to the peer,
-  * in the last handshake. These certificates are in raw format. 
-  * In X.509 this is a certificate list. In OpenPGP this is a single
-  * certificate.
-  * Returns NULL in case of an error, or if no certificate was used.
-  *
-  **/
+ * gnutls_certificate_get_ours - return the raw certificate sent in the last handshake
+ * @session: is a gnutls session
+ *
+ * Get the certificate as sent to the peer, in the last handshake.
+ * These certificates are in raw format.  In X.509 this is a
+ * certificate list. In OpenPGP this is a single certificate.
+ *
+ * Returns: return a pointer to a #gnutls_datum_t containing our
+ *   certificates, or %NULL in case of an error or if no certificate
+ *   was used.
+ **/
 const gnutls_datum_t *
 gnutls_certificate_get_ours (gnutls_session_t session)
 {
@@ -454,22 +461,23 @@ gnutls_certificate_get_ours (gnutls_session_t session)
 }
 
 /**
-  * gnutls_certificate_get_peers - return the peer's raw certificate
-  * @session: is a gnutls session
-  * @list_size: is the length of the certificate list
-  *
-  * This function will return the peer's raw certificate (chain) as 
-  * sent by the peer. These certificates are in raw format (DER encoded 
-  * for X.509). In case of a X.509 then a certificate list may be present. 
-  * The first certificate in the list is the peer's certificate,
-  * following the issuer's certificate, then the issuer's issuer etc.
-  *
-  * In case of OpenPGP keys a single key will be returned
-  * in raw format.
-  *
-  * Returns NULL in case of an error, or if no certificate was sent.
-  *
-  **/
+ * gnutls_certificate_get_peers - return the peer's raw certificate
+ * @session: is a gnutls session
+ * @list_size: is the length of the certificate list
+ *
+ * Get the peer's raw certificate (chain) as sent by the peer.  These
+ * certificates are in raw format (DER encoded for X.509).  In case of
+ * a X.509 then a certificate list may be present.  The first
+ * certificate in the list is the peer's certificate, following the
+ * issuer's certificate, then the issuer's issuer etc.
+ *
+ * In case of OpenPGP keys a single key will be returned in raw
+ * format.
+ *
+ * Returns: return a pointer to a #gnutls_datum_t containing our
+ *   certificates, or %NULL in case of an error or if no certificate
+ *   was used.
+ **/
 const gnutls_datum_t *
 gnutls_certificate_get_peers (gnutls_session_t
 			      session, unsigned int *list_size)
@@ -488,14 +496,15 @@ gnutls_certificate_get_peers (gnutls_session_t
 
 
 /**
-  * gnutls_certificate_client_get_request_status - return the certificate request status
-  * @session: is a gnutls session
-  *
-  * This function will return 0 if the peer (server) did not request client
-  * authentication or 1 otherwise.
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_certificate_client_get_request_status - return the certificate request status
+ * @session: is a gnutls session
+ *
+ * Get whether client certificate is requested or not.
+ *
+ * Returns: 0 if the peer (server) did not request client
+ * authentication or 1 otherwise, or a negative value in case of
+ * error.
+ **/
 int
 gnutls_certificate_client_get_request_status (gnutls_session_t session)
 {
@@ -510,25 +519,25 @@ gnutls_certificate_client_get_request_status (gnutls_session_t session)
 }
 
 /**
-  * gnutls_fingerprint - calculate the fingerprint of the given data
-  * @algo: is a digest algorithm
-  * @data: is the data
-  * @result: is the place where the result will be copied (may be null). 
-  * @result_size: should hold the size of the result. The actual size
-  * of the returned result will also be copied there.
-  *
-  * This function will calculate a fingerprint (actually a hash), of the
-  * given data. The result is not printable data. You should convert it
-  * to hex, or to something else printable.
-  *
-  * This is the usual way to calculate a fingerprint of an X.509 
-  * DER encoded certificate. Note however that the fingerprint 
-  * of an OpenPGP is not just a hash and cannot be calculated with
-  * this function.
-  *
-  * Returns a negative value in case of an error.
-  *
-  **/
+ * gnutls_fingerprint - calculate the fingerprint of the given data
+ * @algo: is a digest algorithm
+ * @data: is the data
+ * @result: is the place where the result will be copied (may be null).
+ * @result_size: should hold the size of the result. The actual size
+ * of the returned result will also be copied there.
+ *
+ * This function will calculate a fingerprint (actually a hash), of
+ * the given data.  The result is not printable data.  You should
+ * convert it to hex, or to something else printable.
+ *
+ * This is the usual way to calculate a fingerprint of an X.509 DER
+ * encoded certificate.  Note however that the fingerprint of an
+ * OpenPGP is not just a hash and cannot be calculated with this
+ * function.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_fingerprint (gnutls_digest_algorithm_t algo,
 		    const gnutls_datum_t * data, void *result,
@@ -560,18 +569,18 @@ gnutls_fingerprint (gnutls_digest_algorithm_t algo,
 
 
 /**
-  * gnutls_certificate_set_dh_params - set the DH parameters for a server to use
-  * @res: is a gnutls_certificate_credentials_t structure
-  * @dh_params: is a structure that holds diffie hellman parameters.
-  *
-  * This function will set the diffie hellman parameters for a
-  * certificate server to use. These parameters will be used in
-  * Ephemeral Diffie Hellman cipher suites.  Note that only a pointer
-  * to the parameters are stored in the certificate handle, so if you
-  * deallocate the parameters before the certificate is deallocated,
-  * you must change the parameters stored in the certificate first.
-  *
-  **/
+ * gnutls_certificate_set_dh_params - set the DH parameters for a server to use
+ * @res: is a gnutls_certificate_credentials_t structure
+ * @dh_params: is a structure that holds diffie hellman parameters.
+ *
+ * This function will set the diffie hellman parameters for a
+ * certificate server to use. These parameters will be used in
+ * Ephemeral Diffie Hellman cipher suites.  Note that only a pointer
+ * to the parameters are stored in the certificate handle, so if you
+ * deallocate the parameters before the certificate is deallocated,
+ * you must change the parameters stored in the certificate first.
+ *
+ **/
 void
 gnutls_certificate_set_dh_params (gnutls_certificate_credentials_t res,
 				  gnutls_dh_params_t dh_params)
@@ -580,15 +589,15 @@ gnutls_certificate_set_dh_params (gnutls_certificate_credentials_t res,
 }
 
 /**
-  * gnutls_certificate_set_params_function - set the DH or RSA parameters callback
-  * @res: is a gnutls_certificate_credentials_t structure
-  * @func: is the function to be called
-  *
-  * This function will set a callback in order for the server to get the 
-  * diffie hellman or RSA parameters for certificate authentication. The callback
-  * should return zero on success.
-  *
-  **/
+ * gnutls_certificate_set_params_function - set the DH or RSA parameters callback
+ * @res: is a gnutls_certificate_credentials_t structure
+ * @func: is the function to be called
+ *
+ * This function will set a callback in order for the server to get
+ * the diffie hellman or RSA parameters for certificate
+ * authentication.  The callback should return zero on success.
+ *
+ **/
 void
 gnutls_certificate_set_params_function (gnutls_certificate_credentials_t res,
 					gnutls_params_function * func)
@@ -598,15 +607,15 @@ gnutls_certificate_set_params_function (gnutls_certificate_credentials_t res,
 
 
 /**
-  * gnutls_certificate_set_verify_flags - set the flags to be used at certificate verification
-  * @res: is a gnutls_certificate_credentials_t structure
-  * @flags: are the flags
-  *
-  * This function will set the flags to be used at verification of the
-  * certificates.  Flags must be OR of the
-  * #gnutls_certificate_verify_flags enumerations.
-  *
-  **/
+ * gnutls_certificate_set_verify_flags - set the flags to be used at certificate verification
+ * @res: is a gnutls_certificate_credentials_t structure
+ * @flags: are the flags
+ *
+ * This function will set the flags to be used at verification of the
+ * certificates.  Flags must be OR of the
+ * #gnutls_certificate_verify_flags enumerations.
+ *
+ **/
 void
 gnutls_certificate_set_verify_flags (gnutls_certificate_credentials_t
 				     res, unsigned int flags)
@@ -615,16 +624,16 @@ gnutls_certificate_set_verify_flags (gnutls_certificate_credentials_t
 }
 
 /**
-  * gnutls_certificate_set_verify_limits - set the upper limits to be used at certificate verification
-  * @res: is a gnutls_certificate_credentials structure
-  * @max_bits: is the number of bits of an acceptable certificate (default 8200)
-  * @max_depth: is maximum depth of the verification of a certificate chain (default 5)
-  *
-  * This function will set some upper limits for the default verification function,
-  * gnutls_certificate_verify_peers2(), to avoid denial of service attacks.
-  * You can set them to zero to disable limits.
-  *
-  **/
+ * gnutls_certificate_set_verify_limits - set the upper limits to be used at certificate verification
+ * @res: is a gnutls_certificate_credentials structure
+ * @max_bits: is the number of bits of an acceptable certificate (default 8200)
+ * @max_depth: is maximum depth of the verification of a certificate chain (default 5)
+ *
+ * This function will set some upper limits for the default
+ * verification function, gnutls_certificate_verify_peers2(), to avoid
+ * denial of service attacks.  You can set them to zero to disable
+ * limits.
+ **/
 void
 gnutls_certificate_set_verify_limits (gnutls_certificate_credentials_t
 				      res, unsigned int max_bits,
@@ -635,15 +644,14 @@ gnutls_certificate_set_verify_limits (gnutls_certificate_credentials_t
 }
 
 /**
-  * gnutls_certificate_set_rsa_export_params - set the RSA parameters for a server to use
-  * @res: is a gnutls_certificate_credentials_t structure
-  * @rsa_params: is a structure that holds temporary RSA parameters.
-  *
-  * This function will set the temporary RSA parameters for a certificate
-  * server to use. These parameters will be used in RSA-EXPORT
-  * cipher suites.
-  *
-  **/
+ * gnutls_certificate_set_rsa_export_params - set the RSA parameters for a server to use
+ * @res: is a gnutls_certificate_credentials_t structure
+ * @rsa_params: is a structure that holds temporary RSA parameters.
+ *
+ * This function will set the temporary RSA parameters for a
+ * certificate server to use.  These parameters will be used in
+ * RSA-EXPORT cipher suites.
+ **/
 void
 gnutls_certificate_set_rsa_export_params (gnutls_certificate_credentials_t
 					  res, gnutls_rsa_params_t rsa_params)
@@ -652,15 +660,14 @@ gnutls_certificate_set_rsa_export_params (gnutls_certificate_credentials_t
 }
 
 /**
-  * gnutls_psk_set_params_function - set the DH or RSA parameters callback
-  * @res: is a gnutls_psk_server_credentials_t structure
-  * @func: is the function to be called
-  *
-  * This function will set a callback in order for the server to get the 
-  * diffie hellman or RSA parameters for psk authentication. The callback
-  * should return zero on success.
-  *
-  **/
+ * gnutls_psk_set_params_function - set the DH or RSA parameters callback
+ * @res: is a gnutls_psk_server_credentials_t structure
+ * @func: is the function to be called
+ *
+ * This function will set a callback in order for the server to get
+ * the diffie hellman or RSA parameters for psk authentication.  The
+ * callback should return zero on success.
+ **/
 void
 gnutls_psk_set_params_function (gnutls_psk_server_credentials_t res,
 				gnutls_params_function * func)
@@ -668,18 +675,15 @@ gnutls_psk_set_params_function (gnutls_psk_server_credentials_t res,
   res->params_func = func;
 }
 
-
-
 /**
-  * gnutls_anon_set_params_function - set the DH or RSA parameters callback
-  * @res: is a gnutls_anon_server_credentials_t structure
-  * @func: is the function to be called
-  *
-  * This function will set a callback in order for the server to get the 
-  * diffie hellman or RSA parameters for anonymous authentication. The callback
-  * should return zero on success.
-  *
-  **/
+ * gnutls_anon_set_params_function - set the DH or RSA parameters callback
+ * @res: is a gnutls_anon_server_credentials_t structure
+ * @func: is the function to be called
+ *
+ * This function will set a callback in order for the server to get
+ * the diffie hellman or RSA parameters for anonymous authentication.
+ * The callback should return zero on success.
+ **/
 void
 gnutls_anon_set_params_function (gnutls_anon_server_credentials_t res,
 				 gnutls_params_function * func)