Doc fixes.

4 files changed, 231 insertions, 196 deletions

diff --git a/lib/gnutls_alert.c b/lib/gnutls_alert.c
index 200023482d..ce448b65d3 100644
--- a/lib/gnutls_alert.c
+++ b/lib/gnutls_alert.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation
+ * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -137,20 +137,21 @@ gnutls_alert_send (gnutls_session_t session, gnutls_alert_level_t level,
 }
 
 /**
-  * gnutls_error_to_alert - return an alert code based on the given error code
-  * @err: is a negative integer
-  * @level: the alert level will be stored there
-  *
-  * Returns an alert depending on the error code returned by a gnutls
-  * function. All alerts sent by this function should be considered fatal.
-  * The only exception is when err == GNUTLS_E_REHANDSHAKE, where a warning 
-  * alert should be sent to the peer indicating that no renegotiation will 
-  * be performed.
-  *
-  * If there is no mapping to a valid alert the alert to indicate internal error 
-  * is returned.
-  *
-  **/
+ * gnutls_error_to_alert - return an alert code based on the given error code
+ * @err: is a negative integer
+ * @level: the alert level will be stored there
+ *
+ * Get an alert depending on the error code returned by a gnutls
+ * function.  All alerts sent by this function should be considered
+ * fatal.  The only exception is when @err is %GNUTLS_E_REHANDSHAKE,
+ * where a warning alert should be sent to the peer indicating that no
+ * renegotiation will be performed.
+ *
+ * If there is no mapping to a valid alert the alert to indicate
+ * internal error is returned.
+ *
+ * Returns: the alert code to use for a particular error code.
+ **/
 int
 gnutls_error_to_alert (int err, int *level)
 {
diff --git a/lib/gnutls_algorithms.c b/lib/gnutls_algorithms.c
index 8866a18da0..39de351c06 100644
--- a/lib/gnutls_algorithms.c
+++ b/lib/gnutls_algorithms.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2000, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation
+ * Copyright (C) 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -667,12 +667,14 @@ _gnutls_mac_priority (gnutls_session_t session,
 }
 
 /**
-  * gnutls_mac_get_name - Returns a string with the name of the specified mac algorithm
-  * @algorithm: is a MAC algorithm
-  *
-  * Returns: a string that contains the name of the specified MAC
-  * algorithm, or %NULL.
-  **/
+ * gnutls_mac_get_name - Returns a string with the name of the specified mac algorithm
+ * @algorithm: is a MAC algorithm
+ *
+ * Convert a #gnutls_mac_algorithm_t value to a string.
+ *
+ * Returns: a string that contains the name of the specified MAC
+ *   algorithm, or %NULL.
+ **/
 const char *
 gnutls_mac_get_name (gnutls_mac_algorithm_t algorithm)
 {
@@ -685,13 +687,15 @@ gnutls_mac_get_name (gnutls_mac_algorithm_t algorithm)
 }
 
 /**
-  * gnutls_mac_get_id - Returns the gnutls id of the specified in string algorithm
-  * @algorithm: is a MAC algorithm name
-  *
-  * Returns: an %gnutls_mac_algorithm_tid of the specified in a string
-  * MAC algorithm, or %GNUTLS_MAC_UNKNOWN on failures.  The names are
-  * compared in a case insensitive way.
-  **/
+ * gnutls_mac_get_id - Returns the gnutls id of the specified in string algorithm
+ * @algorithm: is a MAC algorithm name
+ *
+ * Convert a string to a #gnutls_mac_algorithm_t value.  The names are
+ * compared in a case insensitive way.
+ *
+ * Returns: an %gnutls_mac_algorithm_tid of the specified in a string
+ *   MAC algorithm, or %GNUTLS_MAC_UNKNOWN on failures.
+ **/
 gnutls_mac_algorithm_t
 gnutls_mac_get_id (const char* name)
 {
@@ -703,13 +707,14 @@ gnutls_mac_get_id (const char* name)
 }
 
 /**
-  * gnutls_mac_get_key_size - Returns the length of the MAC's key size
-  * @algorithm: is an encryption algorithm
-  *
-  * Returns: length (in bytes) of the given MAC key size, or 0 if the
-  * given MAC algorithm is invalid.
-  *
-  **/
+ * gnutls_mac_get_key_size - Returns the length of the MAC's key size
+ * @algorithm: is an encryption algorithm
+ *
+ * Get size of MAC key.
+ *
+ * Returns: length (in bytes) of the given MAC key size, or 0 if the
+ *   given MAC algorithm is invalid.
+ **/
 size_t
 gnutls_mac_get_key_size (gnutls_mac_algorithm_t algorithm)
 {
@@ -794,12 +799,14 @@ _gnutls_compression_priority (gnutls_session_t session,
 }
 
 /**
-  * gnutls_compression_get_name - Returns a string with the name of the specified compression algorithm
-  * @algorithm: is a Compression algorithm
-  *
-  * Returns: a pointer to a string that contains the name of the
-  * specified compression algorithm, or %NULL.
-  **/
+ * gnutls_compression_get_name - Returns a string with the name of the specified compression algorithm
+ * @algorithm: is a Compression algorithm
+ *
+ * Convert a #gnutls_compression_method_t value to a string.
+ *
+ * Returns: a pointer to a string that contains the name of the
+ *   specified compression algorithm, or %NULL.
+ **/
 const char *
 gnutls_compression_get_name (gnutls_compression_method_t algorithm)
 {
@@ -812,15 +819,14 @@ gnutls_compression_get_name (gnutls_compression_method_t algorithm)
 }
 
 /**
-  * gnutls_compression_get_id - Returns the gnutls id of the specified in string algorithm
-  * @algorithm: is a compression method name
-  *
-  * The names are compared in a case insensitive way.
-  *
-  * Returns: an id of the specified in a string compression method, or
-  * %GNUTLS_COMP_UNKNOWN on error.
-  *
-  **/
+ * gnutls_compression_get_id - Returns the gnutls id of the specified in string algorithm
+ * @algorithm: is a compression method name
+ *
+ * The names are compared in a case insensitive way.
+ *
+ * Returns: an id of the specified in a string compression method, or
+ *   %GNUTLS_COMP_UNKNOWN on error.
+ **/
 gnutls_compression_method_t
 gnutls_compression_get_id (const char* name)
 {
@@ -952,12 +958,14 @@ _gnutls_cipher_is_block (gnutls_cipher_algorithm_t algorithm)
 }
 
 /**
-  * gnutls_cipher_get_key_size - Returns the length of the cipher's key size
-  * @algorithm: is an encryption algorithm
-  *
-  * Returns: length (in bytes) of the given cipher's key size, o 0 if
-  *   the given cipher is invalid.
-  **/
+ * gnutls_cipher_get_key_size - Returns the length of the cipher's key size
+ * @algorithm: is an encryption algorithm
+ *
+ * Get key size for cipher.
+ *
+ * Returns: length (in bytes) of the given cipher's key size, or 0 if
+ *   the given cipher is invalid.
+ **/
 size_t
 gnutls_cipher_get_key_size (gnutls_cipher_algorithm_t algorithm)
 {				/* In bytes */
@@ -986,12 +994,14 @@ _gnutls_cipher_get_export_flag (gnutls_cipher_algorithm_t algorithm)
 }
 
 /**
-  * gnutls_cipher_get_name - Returns a string with the name of the specified cipher algorithm
-  * @algorithm: is an encryption algorithm
-  *
-  * Returns: a pointer to a string that contains the name of the
-  *   specified cipher, or %NULL.
-  **/
+ * gnutls_cipher_get_name - Returns a string with the name of the specified cipher algorithm
+ * @algorithm: is an encryption algorithm
+ *
+ * Convert a #gnutls_cipher_algorithm_t type to a string.
+ *
+ * Returns: a pointer to a string that contains the name of the
+ *   specified cipher, or %NULL.
+ **/
 const char *
 gnutls_cipher_get_name (gnutls_cipher_algorithm_t algorithm)
 {
@@ -1004,15 +1014,14 @@ gnutls_cipher_get_name (gnutls_cipher_algorithm_t algorithm)
 }
 
 /**
-  * gnutls_cipher_get_id - Returns the gnutls id of the specified in string algorithm
-  * @algorithm: is a MAC algorithm name
-  *
-  * The names are compared in a case insensitive way.
-  *
-  * Returns: an id of the specified cipher, or %GNUTLS_CIPHER_UNKNOWN
-  * on error.
-  *
-  **/
+ * gnutls_cipher_get_id - Returns the gnutls id of the specified in string algorithm
+ * @algorithm: is a MAC algorithm name
+ *
+ * The names are compared in a case insensitive way.
+ *
+ * Returns: return a #gnutls_cipher_algorithm_t value corresponding to
+ *   the specified cipher, or %GNUTLS_CIPHER_UNKNOWN on error.
+ **/
 gnutls_cipher_algorithm_t
 gnutls_cipher_get_id (const char* name)
 {
@@ -1078,12 +1087,14 @@ _gnutls_kx_priority (gnutls_session_t session,
 }
 
 /**
-  * gnutls_kx_get_name - Returns a string with the name of the specified key exchange algorithm
-  * @algorithm: is a key exchange algorithm
-  *
-  * Returns: a pointer to a string that contains the name of the
-  * specified key exchange algorithm, or %NULL.
-  **/
+ * gnutls_kx_get_name - Returns a string with the name of the specified key exchange algorithm
+ * @algorithm: is a key exchange algorithm
+ *
+ * Convert a #gnutls_kx_algorithm_t value to a string.
+ *
+ * Returns: a pointer to a string that contains the name of the
+ *   specified key exchange algorithm, or %NULL.
+ **/
 const char *
 gnutls_kx_get_name (gnutls_kx_algorithm_t algorithm)
 {
@@ -1096,14 +1107,15 @@ gnutls_kx_get_name (gnutls_kx_algorithm_t algorithm)
 }
 
 /**
-  * gnutls_kx_get_id - Returns the gnutls id of the specified in string algorithm
-  * @algorithm: is a KX name
-  *
-  * The names are compared in a case insensitive way.
-  *
-  * Returns: an id of the specified KX algorithm, or
-  * %GNUTLS_KX_UNKNOWN on error.
-  **/
+ * gnutls_kx_get_id - Returns the gnutls id of the specified in string algorithm
+ * @algorithm: is a KX name
+ *
+ * Convert a string to a #gnutls_kx_algorithm_t value.  The names are
+ * compared in a case insensitive way.
+ *
+ * Returns: an id of the specified KX algorithm, or %GNUTLS_KX_UNKNOWN
+ *   on error.
+ **/
 gnutls_kx_algorithm_t
 gnutls_kx_get_id (const char* name)
 {
@@ -1223,12 +1235,14 @@ _gnutls_version_max (gnutls_session_t session)
 
 
 /**
-  * gnutls_protocol_get_name - Returns a string with the name of the specified SSL/TLS version
-  * @version: is a (gnutls) version number
-  *
-  * Returns: a string that contains the name of the specified TLS
-  * version (e.g., "TLS 1.0"), or %NULL.
-  **/
+ * gnutls_protocol_get_name - Returns a string with the name of the specified SSL/TLS version
+ * @version: is a (gnutls) version number
+ *
+ * Convert a #gnutls_protocol_t value to a string.
+ *
+ * Returns: a string that contains the name of the specified TLS
+ *   version (e.g., "TLS1.0"), or %NULL.
+ **/
 const char *
 gnutls_protocol_get_name (gnutls_protocol_t version)
 {
@@ -1815,12 +1829,14 @@ _gnutls_supported_compression_methods (gnutls_session_t session,
 }
 
 /**
-  * gnutls_certificate_type_get_name - Returns a string with the name of the specified certificate type
-  * @type: is a certificate type
-  *
-  * Returns: a string (or %NULL) that contains the name of the
-  * specified certificate type.
-  **/
+ * gnutls_certificate_type_get_name - Returns a string with the name of the specified certificate type
+ * @type: is a certificate type
+ *
+ * Convert a #gnutls_certificate_type_t type to a string.
+ *
+ * Returns: a string that contains the name of the specified
+ *   certificate type, or %NULL in case of unknown types.
+ **/
 const char *
 gnutls_certificate_type_get_name (gnutls_certificate_type_t type)
 {
@@ -2037,8 +2053,10 @@ static const gnutls_pk_entry pk_algorithms[] = {
   * gnutls_pk_algorithm_get_name - Returns a string with the name of the specified public key algorithm
   * @algorithm: is a pk algorithm
   *
+  * Convert a #gnutls_pk_algorithm_t value to a string.
+  *
   * Returns: a string that contains the name of the specified public
-  * key algorithm, or %NULL.
+  *   key algorithm, or %NULL.
   **/
 const char *
 gnutls_pk_algorithm_get_name (gnutls_pk_algorithm_t algorithm)
diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c
index 72b9ac30b4..ca4aea7420 100644
--- a/lib/gnutls_record.c
+++ b/lib/gnutls_record.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation
+ * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -45,11 +45,13 @@
 #include <gnutls_dh.h>
 
 /**
-  * gnutls_protocol_get_version - Returns the version of the currently used protocol
-  * @session: is a #gnutls_session_t structure.
-  *
-  * Returns: the version of the currently used protocol.
-  **/
+ * gnutls_protocol_get_version - Returns the version of the currently used protocol
+ * @session: is a #gnutls_session_t structure.
+ *
+ * Get TLS version, a #gnutls_protocol_t value.
+ *
+ * Returns: the version of the currently used protocol.
+ **/
 gnutls_protocol_t
 gnutls_protocol_get_version (gnutls_session_t session)
 {
diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c
index ab36e3bdb2..3d91ca641a 100644
--- a/lib/gnutls_state.c
+++ b/lib/gnutls_state.c
@@ -52,11 +52,14 @@ _gnutls_session_cert_type_set (gnutls_session_t session,
 }
 
 /**
-  * gnutls_cipher_get - Returns the currently used cipher.
-  * @session: is a #gnutls_session_t structure.
-  *
-  * Returns: the currently used cipher.
-  **/
+ * gnutls_cipher_get - Returns the currently used cipher.
+ * @session: is a #gnutls_session_t structure.
+ *
+ * Get currently used cipher.
+ *
+ * Returns: the currently used cipher, an #gnutls_cipher_algorithm_t
+ *   type.
+ **/
 gnutls_cipher_algorithm_t
 gnutls_cipher_get (gnutls_session_t session)
 {
@@ -64,15 +67,15 @@ gnutls_cipher_get (gnutls_session_t session)
 }
 
 /**
-  * gnutls_certificate_type_get - Returns the currently used certificate type.
-  * @session: is a #gnutls_session_t structure.
-  *
-  * The certificate type is by default X.509, unless it is negotiated
-  * as a TLS extension.
-  *
-  * Returns: the currently used %gnutls_certificate_type_t certificate
-  *   type.
-  **/
+ * gnutls_certificate_type_get - Returns the currently used certificate type.
+ * @session: is a #gnutls_session_t structure.
+ *
+ * The certificate type is by default X.509, unless it is negotiated
+ * as a TLS extension.
+ *
+ * Returns: the currently used #gnutls_certificate_type_t certificate
+ *   type.
+ **/
 gnutls_certificate_type_t
 gnutls_certificate_type_get (gnutls_session_t session)
 {
@@ -80,11 +83,14 @@ gnutls_certificate_type_get (gnutls_session_t session)
 }
 
 /**
-  * gnutls_kx_get - Returns the key exchange algorithm.
-  * @session: is a #gnutls_session_t structure.
-  *
-  * Returns: the key exchange algorithm used in the last handshake.
-  **/
+ * gnutls_kx_get - Returns the key exchange algorithm.
+ * @session: is a #gnutls_session_t structure.
+ *
+ * Get currently used key exchange algorithm.
+ *
+ * Returns: the key exchange algorithm used in the last handshake, a
+ *   #gnutls_kx_algorithm_t value.
+ **/
 gnutls_kx_algorithm_t
 gnutls_kx_get (gnutls_session_t session)
 {
@@ -92,11 +98,14 @@ gnutls_kx_get (gnutls_session_t session)
 }
 
 /**
-  * gnutls_mac_get - Returns the currently used mac algorithm.
-  * @session: is a #gnutls_session_t structure.
-  *
-  * Returns: the currently used mac algorithm.
-  **/
+ * gnutls_mac_get - Returns the currently used mac algorithm.
+ * @session: is a #gnutls_session_t structure.
+ *
+ * Get currently used MAC algorithm.
+ *
+ * Returns: the currently used mac algorithm, a
+ *   #gnutls_mac_algorithm_t value.
+ **/
 gnutls_mac_algorithm_t
 gnutls_mac_get (gnutls_session_t session)
 {
@@ -104,11 +113,14 @@ gnutls_mac_get (gnutls_session_t session)
 }
 
 /**
-  * gnutls_compression_get - Returns the currently used compression algorithm.
-  * @session: is a #gnutls_session_t structure.
-  *
-  * Returns: the currently used compression method.
-  **/
+ * gnutls_compression_get - Returns the currently used compression algorithm.
+ * @session: is a #gnutls_session_t structure.
+ *
+ * Get currently used compression algorithm.
+ *
+ * Returns: the currently used compression method, a
+ *   #gnutls_compression_method_t value.
+ **/
 gnutls_compression_method_t
 gnutls_compression_get (gnutls_session_t session)
 {
@@ -1140,12 +1152,15 @@ _gnutls_session_is_export (gnutls_session_t session)
 }
 
 /**
-  * gnutls_session_get_ptr - Used to get the user pointer from the session structure
-  * @session: is a #gnutls_session_t structure.
-  *
-  * Returns: the user given pointer from the session structure.  This
-  * is the pointer set with gnutls_session_set_ptr().
-  **/
+ * gnutls_session_get_ptr - Get the user pointer from the session structure
+ * @session: is a #gnutls_session_t structure.
+ *
+ * Get user pointer for session.  Useful in callbacks.  This is the
+ *   pointer set with gnutls_session_set_ptr().
+ *
+ * Returns: the user given pointer from the session structure, or
+ *   %NULL if it was never set.
+ **/
 void *
 gnutls_session_get_ptr (gnutls_session_t session)
 {
@@ -1153,14 +1168,14 @@ gnutls_session_get_ptr (gnutls_session_t session)
 }
 
 /**
-  * gnutls_session_set_ptr - Used to set the user pointer to the session structure
-  * @session: is a #gnutls_session_t structure.
-  * @ptr: is the user pointer
-  *
-  * This function will set (associate) the user given pointer to the
-  * session structure.  This is pointer can be accessed with
-  * gnutls_session_get_ptr().
-  **/
+ * gnutls_session_set_ptr - Used to set the user pointer to the session structure
+ * @session: is a #gnutls_session_t structure.
+ * @ptr: is the user pointer
+ *
+ * This function will set (associate) the user given pointer @ptr to
+ * the session structure.  This is pointer can be accessed with
+ * gnutls_session_get_ptr().
+ **/
 void
 gnutls_session_set_ptr (gnutls_session_t session, void *ptr)
 {
@@ -1169,22 +1184,22 @@ gnutls_session_set_ptr (gnutls_session_t session, void *ptr)
 
 
 /**
-  * gnutls_record_get_direction - return the direction of the last interrupted function call
-  * @session: is a #gnutls_session_t structure.
-  *
-  * This function provides information about the internals of the
-  * record protocol and is only useful if a prior gnutls function call
-  * (e.g.  gnutls_handshake()) was interrupted for some reason, that
-  * is, if a function returned %GNUTLS_E_INTERRUPTED or
-  * %GNUTLS_E_AGAIN.  In such a case, you might want to call select()
-  * or poll() before calling the interrupted gnutls function again.
-  * To tell you whether a file descriptor should be selected for
-  * either reading or writing, gnutls_record_get_direction() returns 0
-  * if the interrupted function was trying to read data, and 1 if it
-  * was trying to write data.
-  *
-  * Returns: 0 if trying to read data, 1 if trying to write data.
-  **/
+ * gnutls_record_get_direction - return the direction of the last interrupted function call
+ * @session: is a #gnutls_session_t structure.
+ *
+ * This function provides information about the internals of the
+ * record protocol and is only useful if a prior gnutls function call
+ * (e.g.  gnutls_handshake()) was interrupted for some reason, that
+ * is, if a function returned %GNUTLS_E_INTERRUPTED or
+ * %GNUTLS_E_AGAIN.  In such a case, you might want to call select()
+ * or poll() before calling the interrupted gnutls function again.  To
+ * tell you whether a file descriptor should be selected for either
+ * reading or writing, gnutls_record_get_direction() returns 0 if the
+ * interrupted function was trying to read data, and 1 if it was
+ * trying to write data.
+ *
+ * Returns: 0 if trying to read data, 1 if trying to write data.
+ **/
 int
 gnutls_record_get_direction (gnutls_session_t session)
 {
@@ -1211,27 +1226,26 @@ _gnutls_rsa_pms_set_version (gnutls_session_t session,
 }
 
 /**
-  * gnutls_handshake_set_post_client_hello_function - set callback to be called after the client hello is received
-  * @res: is a gnutls_anon_server_credentials_t structure
-  * @func: is the function to be called
-  *
-  * This function will set a callback to be called after the client
-  * hello has been received (callback valid in server side only). This
-  * allows the server to adjust settings based on received extensions.
-  *
-  * Those settings could be ciphersuites, requesting certificate, or
-  * anything else except for version negotiation (this is done before
-  * the hello message is parsed).
-  *
-  * This callback must return 0 on success or a gnutls error code to
-  * terminate the handshake.
-  *
-  * NOTE: You should not use this function to terminate the handshake
-  * based on client input unless you know what you are doing. Before
-  * the handshake is finished there is no way to know if there is a
-  * man-in-the-middle attack being performed.
-  *
-  **/
+ * gnutls_handshake_set_post_client_hello_function - set callback to be called after the client hello is received
+ * @res: is a gnutls_anon_server_credentials_t structure
+ * @func: is the function to be called
+ *
+ * This function will set a callback to be called after the client
+ * hello has been received (callback valid in server side only). This
+ * allows the server to adjust settings based on received extensions.
+ *
+ * Those settings could be ciphersuites, requesting certificate, or
+ * anything else except for version negotiation (this is done before
+ * the hello message is parsed).
+ *
+ * This callback must return 0 on success or a gnutls error code to
+ * terminate the handshake.
+ *
+ * NOTE: You should not use this function to terminate the handshake
+ * based on client input unless you know what you are doing. Before
+ * the handshake is finished there is no way to know if there is a
+ * man-in-the-middle attack being performed.
+ **/
 void
 gnutls_handshake_set_post_client_hello_function (gnutls_session_t session,
 						 gnutls_handshake_post_client_hello_func func)
@@ -1240,17 +1254,17 @@ gnutls_handshake_set_post_client_hello_function (gnutls_session_t session,
 }
 
 /**
-  * gnutls_session_enable_compatibility_mode - Used to disable certain features in TLS in order to honour compatibility
-  * @session: is a #gnutls_session_t structure.
-  *
-  * This function can be used to disable certain (security) features
-  * in TLS in order to maintain maximum compatibility with buggy
-  * clients. It is equivalent to calling:
-  * gnutls_record_disable_padding()
-  *
-  * Normally only servers that require maximum compatibility with
-  * everything out there, need to call this function.
-  **/
+ * gnutls_session_enable_compatibility_mode - disable certain features in TLS in order to honour compatibility
+ * @session: is a #gnutls_session_t structure.
+ *
+ * This function can be used to disable certain (security) features in
+ * TLS in order to maintain maximum compatibility with buggy
+ * clients. It is equivalent to calling:
+ * gnutls_record_disable_padding()
+ *
+ * Normally only servers that require maximum compatibility with
+ * everything out there, need to call this function.
+ **/
 void
 gnutls_session_enable_compatibility_mode (gnutls_session_t session)
 {