Doc fixes for GTK-DOC.

23 files changed, 268 insertions, 242 deletions

diff --git a/lib/gnutls_algorithms.c b/lib/gnutls_algorithms.c
index a8929edbf4..e45f4c1484 100644
--- a/lib/gnutls_algorithms.c
+++ b/lib/gnutls_algorithms.c
@@ -1262,17 +1262,17 @@ _gnutls_cipher_suite_get_name (cipher_suite_st * suite)
 }
 
 /**
-  * gnutls_cipher_suite_get_name - Returns a string with the name of the specified cipher suite
-  * @kx_algorithm: is a Key exchange algorithm
-  * @cipher_algorithm: is a cipher algorithm
-  * @mac_algorithm: is a MAC algorithm
-  *
-  * Note that the full cipher suite name must be prepended by TLS or
-  * SSL depending of the protocol in use.
-  *
-  * Returns: a string that contains the name of a TLS cipher suite,
-  * specified by the given algorithms, or %NULL.
-  **/
+ * gnutls_cipher_suite_get_name - get name of the specified cipher suite
+ * @kx_algorithm: is a Key exchange algorithm
+ * @cipher_algorithm: is a cipher algorithm
+ * @mac_algorithm: is a MAC algorithm
+ *
+ * Note that the full cipher suite name must be prepended by TLS or
+ * SSL depending of the protocol in use.
+ *
+ * Returns: a string that contains the name of a TLS cipher suite,
+ * specified by the given algorithms, or %NULL.
+ **/
 const char *
 gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t kx_algorithm,
 			      gnutls_cipher_algorithm_t cipher_algorithm,
@@ -1775,7 +1775,7 @@ static const gnutls_sign_algorithm_t supported_sign[] = {
 
 /**
  * gnutls_sign_algorithm_get_name - Returns a string with the name of the specified sign algorithm
- * @algorithm: is a sign algorithm
+ * @sign: is a sign algorithm
  *
  * Convert a #gnutls_sign_algorithm_t value to a string.
  *
diff --git a/lib/gnutls_auth.c b/lib/gnutls_auth.c
index 77af880807..ba15a483ae 100644
--- a/lib/gnutls_auth.c
+++ b/lib/gnutls_auth.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation
+ * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -66,30 +66,35 @@ gnutls_credentials_clear (gnutls_session_t session)
  * { algorithm, credentials, pointer to next }
  */
 /**
-  * gnutls_credentials_set - Sets the needed credentials for the specified authentication algorithm.
-  * @session: is a #gnutls_session_t structure.
-  * @type: is the type of the credentials
-  * @cred: is a pointer to a structure.
-  *
-  * Sets the needed credentials for the specified type.
-  * Eg username, password - or public and private keys etc.  
-  * The (void* cred) parameter is a structure that depends on the
-  * specified type and on the current session (client or server).
-  * [ In order to minimize memory usage, and share credentials between 
-  * several threads gnutls keeps a pointer to cred, and not the whole cred
-  * structure. Thus you will have to keep the structure allocated until   
-  * you call gnutls_deinit(). ]
-  *
-  * For GNUTLS_CRD_ANON cred should be gnutls_anon_client_credentials_t in case of a client.
-  * In case of a server it should be gnutls_anon_server_credentials_t.
-  * 
-  * For GNUTLS_CRD_SRP cred should be gnutls_srp_client_credentials_t
-  * in case of a client, and gnutls_srp_server_credentials_t, in case
-  * of a server.
-  *
-  * For GNUTLS_CRD_CERTIFICATE cred should be gnutls_certificate_credentials_t.
-  *
-  **/
+ * gnutls_credentials_set - Sets the needed credentials for the specified authentication algorithm.
+ * @session: is a #gnutls_session_t structure.
+ * @type: is the type of the credentials
+ * @cred: is a pointer to a structure.
+ *
+ * Sets the needed credentials for the specified type.  Eg username,
+ * password - or public and private keys etc.  The @cred parameter is
+ * a structure that depends on the specified type and on the current
+ * session (client or server).
+ *
+ * In order to minimize memory usage, and share credentials between
+ * several threads gnutls keeps a pointer to cred, and not the whole
+ * cred structure.  Thus you will have to keep the structure allocated
+ * until you call gnutls_deinit().
+ *
+ * For %GNUTLS_CRD_ANON, @cred should be
+ * #gnutls_anon_client_credentials_t in case of a client.  In case of
+ * a server it should be #gnutls_anon_server_credentials_t.
+ *
+ * For %GNUTLS_CRD_SRP, @cred should be #gnutls_srp_client_credentials_t
+ * in case of a client, and #gnutls_srp_server_credentials_t, in case
+ * of a server.
+ *
+ * For %GNUTLS_CRD_CERTIFICATE, @cred should be
+ * #gnutls_certificate_credentials_t.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
+ **/
 int
 gnutls_credentials_set (gnutls_session_t session,
 			gnutls_credentials_type_t type, void *cred)
diff --git a/lib/gnutls_buffers.c b/lib/gnutls_buffers.c
index b5fd10245f..0b94f6f173 100644
--- a/lib/gnutls_buffers.c
+++ b/lib/gnutls_buffers.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -187,16 +187,18 @@ _gnutls_record_buffer_get_size (content_type_t type, gnutls_session_t session)
 }
 
 /**
-  * gnutls_record_check_pending - checks if there are any data to receive in gnutls buffers.
-  * @session: is a #gnutls_session_t structure.
-  *
-  * This function checks if there are any data to receive
-  * in the gnutls buffers. Returns the size of that data or 0.
-  * Notice that you may also use select() to check for data in
-  * a TCP connection, instead of this function.
-  * (gnutls leaves some data in the tcp buffer in order for select
-  * to work).
-  **/
+ * gnutls_record_check_pending - checks if there are any data to receive in gnutls buffers.
+ * @session: is a #gnutls_session_t structure.
+ *
+ * This function checks if there are any data to receive in the gnutls
+ * buffers.
+ *
+ * Notice that you may also use select() to check for data in a TCP
+ * connection, instead of this function.  GnuTLS leaves some data in
+ * the tcp buffer in order for select to work.
+ *
+ * Returns: the size of that data or 0.
+ **/
 size_t
 gnutls_record_check_pending (gnutls_session_t session)
 {
diff --git a/lib/gnutls_cert.c b/lib/gnutls_cert.c
index 9d5b3f5ac7..40bcdf85ef 100644
--- a/lib/gnutls_cert.c
+++ b/lib/gnutls_cert.c
@@ -574,8 +574,8 @@ _gnutls_openpgp_crt_verify_peers (gnutls_session_t session,
   * Note that you must also check the peer's name in order to check if
   * the verified certificate belongs to the actual peer.
   *
-  * This is the same as gnutls_x509_crt_list_verify() and uses the
-  * loaded CAs in the credentials as trusted CAs.
+  * This function uses gnutls_x509_crt_list_verify() with the CAs in
+  * the credentials as trusted CAs.
   *
   * Note that some commonly used X.509 Certificate Authorities are
   * still using Version 1 certificates.  If you want to accept them,
@@ -623,11 +623,10 @@ gnutls_certificate_verify_peers2 (gnutls_session_t session,
   * the peer's name in order to check if the verified certificate
   * belongs to the actual peer.
   *
-  * The return value should be one or more of the
-  * gnutls_certificate_status_t enumerated elements bitwise or'd, or a
-  * negative value on error.
+  * This function uses gnutls_x509_crt_list_verify().
   *
-  * This is the same as gnutls_x509_crt_list_verify().
+  * Returns: one or more of the #gnutls_certificate_status_t
+  * enumerated elements bitwise or'd, or a negative value on error.
   *
   * Deprecated: Use gnutls_certificate_verify_peers2() instead.
   **/
diff --git a/lib/gnutls_global.c b/lib/gnutls_global.c
index ece100bd84..6b149cfbb0 100644
--- a/lib/gnutls_global.c
+++ b/lib/gnutls_global.c
@@ -104,10 +104,8 @@ gnutls_global_set_log_level (int level)
  **/
 void
 gnutls_global_set_mem_functions (gnutls_alloc_function alloc_func,
-				 gnutls_alloc_function
-				 secure_alloc_func,
-				 gnutls_is_secure_function
-				 is_secure_func,
+				 gnutls_alloc_function secure_alloc_func,
+				 gnutls_is_secure_function is_secure_func,
 				 gnutls_realloc_function realloc_func,
 				 gnutls_free_function free_func)
 {
diff --git a/lib/gnutls_priority.c b/lib/gnutls_priority.c
index a47b70acdc..314b51da8e 100644
--- a/lib/gnutls_priority.c
+++ b/lib/gnutls_priority.c
@@ -518,7 +518,8 @@ gnutls_priority_set (gnutls_session_t session, gnutls_priority_t priority)
  **/
 int
 gnutls_priority_init (gnutls_priority_t * priority_cache,
-		      const char *priorities, const char **err_pos)
+		      const char *priorities,
+		      const char **err_pos)
 {
   char *broken_list[MAX_ELEMENTS];
   int broken_list_size, i, j;
diff --git a/lib/gnutls_psk.c b/lib/gnutls_psk.c
index 6c66bbe2c6..f0a49dda72 100644
--- a/lib/gnutls_psk.c
+++ b/lib/gnutls_psk.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2005, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -438,14 +438,14 @@ gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res,
 }
 
 /**
-  * gnutls_psk_set_server_params_function - set the DH 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 parameters for PSK authentication. The callback
-  * should return zero on success.
-  **/
+ * gnutls_psk_set_server_params_function - set the DH 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 parameters for PSK authentication. The callback
+ * should return zero on success.
+ **/
 void
 gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t res,
 				       gnutls_params_function * func)
diff --git a/lib/gnutls_session.c b/lib/gnutls_session.c
index 62a3cdcf71..2a3419b42d 100644
--- a/lib/gnutls_session.c
+++ b/lib/gnutls_session.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2000, 2003, 2004, 2005, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2000, 2003, 2004, 2005, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -83,22 +83,23 @@ error:
 }
 
 /**
-  * gnutls_session_get_data2 - Returns all session parameters.
-  * @session: is a #gnutls_session_t structure.
-  * @session_data: is a pointer to a datum that will hold the session.
-  *
-  * Returns all session parameters, in order to support resuming.
-  * The client should call this, and keep the returned session, if he wants to
-  * resume that current version later by calling gnutls_session_set_data()
-  * This function must be called after a successful handshake. The returned
-  * datum must be freed with gnutls_free().
-  *
-  * Resuming sessions is really useful and speedups connections after
-  * a succesful one.
-  *
-  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
-  *   an error code is returned.
-  **/
+ * gnutls_session_get_data2 - Returns all session parameters.
+ * @session: is a #gnutls_session_t structure.
+ * @data: is a pointer to a datum that will hold the session.
+ *
+ * Returns all session parameters, in order to support resuming.  The
+ * client should call this, and keep the returned session, if he wants
+ * to resume that current version later by calling
+ * gnutls_session_set_data().  This function must be called after a
+ * successful handshake.  The returned datum must be freed with
+ * gnutls_free().
+ *
+ * Resuming sessions is really useful and speedups connections after
+ * a succesful one.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise
+ *   an error code is returned.
+ **/
 int
 gnutls_session_get_data2 (gnutls_session_t session, gnutls_datum_t * data)
 {
diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c
index 31b0c84c7e..3dd440eccc 100644
--- a/lib/gnutls_state.c
+++ b/lib/gnutls_state.c
@@ -1123,7 +1123,7 @@ gnutls_session_get_master_secret (gnutls_session_t session)
 /**
  * gnutls_session_set_finished_function:
  * @session: is a #gnutls_session_t structure.
- * @finished_func: a #gnutls_finished_callback_func callback.
+ * @func: a #gnutls_finished_callback_func callback.
  *
  * Register a callback function for the session that will be called
  * when a TLS Finished message has been generated.  The function is
@@ -1132,7 +1132,7 @@ gnutls_session_get_master_secret (gnutls_session_t session)
  *
  * The callback should follow this prototype:
  *
- * void callback (gnutls_session_t session, const void *finished, size_t len);
+ * void callback (gnutls_session_t @session, const void *@finished, size_t @len);
  *
  * The @finished parameter will contain the binary TLS finished
  * message, and @len will contains its length.  For SSLv3 connections,
@@ -1147,10 +1147,9 @@ gnutls_session_get_master_secret (gnutls_session_t session)
  **/
 void
 gnutls_session_set_finished_function (gnutls_session_t session,
-				      gnutls_finished_callback_func
-				      finished_func)
+				      gnutls_finished_callback_func func)
 {
-  session->internals.finished_func = finished_func;
+  session->internals.finished_func = func;
 }
 
 /**
@@ -1305,7 +1304,7 @@ _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
+ * @session: is a #gnutls_session_t structure.
  * @func: is the function to be called
  *
  * This function will set a callback to be called after the client
diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in
index ca3e206beb..bc4ada9208 100644
--- a/lib/includes/gnutls/gnutls.h.in
+++ b/lib/includes/gnutls/gnutls.h.in
@@ -330,8 +330,8 @@ extern "C" {
     GNUTLS_SIGN_RSA_SHA224
   } gnutls_sign_algorithm_t;
 
-  const char *gnutls_sign_algorithm_get_name (gnutls_sign_algorithm_t
-					      algorithm);
+  const char *
+  gnutls_sign_algorithm_get_name (gnutls_sign_algorithm_t sign);
 
 /* If you want to change this, then also change the define in
  * gnutls_int.h, and recompile.
@@ -432,8 +432,8 @@ extern "C" {
   const gnutls_kx_algorithm_t *gnutls_kx_list (void);
   const gnutls_pk_algorithm_t *gnutls_pk_list (void);
   const gnutls_sign_algorithm_t *gnutls_sign_list (void);
-  const char *gnutls_cipher_suite_info (size_t i,
-					char *id,
+  const char *gnutls_cipher_suite_info (size_t idx,
+					char *cs_id,
 					gnutls_kx_algorithm_t *kx,
 					gnutls_cipher_algorithm_t *cipher,
 					gnutls_mac_algorithm_t *mac,
@@ -569,14 +569,14 @@ extern "C" {
 /* if you just want some defaults, use the following.
  */
   int gnutls_priority_init (gnutls_priority_t *priority_cache,
-			    const char *priority,
+			    const char *priorities,
 			    const char** err_pos);
-  void gnutls_priority_deinit (gnutls_priority_t);
+  void gnutls_priority_deinit (gnutls_priority_t priority_cache);
 
   int gnutls_priority_set (gnutls_session_t session,
 			   gnutls_priority_t priority);
   int gnutls_priority_set_direct (gnutls_session_t session,
-				  const char *priority,
+				  const char *priorities,
 				  const char** err_pos);
 
   /* for compatibility
@@ -585,12 +585,10 @@ extern "C" {
   int gnutls_set_default_export_priority (gnutls_session_t session);
 
 /* Returns the name of a cipher suite */
-  const char *gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t
-					    kx_algorithm,
-					    gnutls_cipher_algorithm_t
-					    cipher_algorithm,
-					    gnutls_mac_algorithm_t
-					    mac_algorithm);
+  const char *
+  gnutls_cipher_suite_get_name (gnutls_kx_algorithm_t kx_algorithm,
+				gnutls_cipher_algorithm_t cipher_algorithm,
+				gnutls_mac_algorithm_t mac_algorithm);
 
 /* get the currently used protocol version */
   gnutls_protocol_t gnutls_protocol_get_version (gnutls_session_t session);
@@ -627,8 +625,7 @@ extern "C" {
 						 size_t len);
   void
   gnutls_session_set_finished_function (gnutls_session_t session,
-					gnutls_finished_callback_func
-					finished_func);
+					gnutls_finished_callback_func func);
 
 /* checks if this session is a resumed one 
  */
@@ -817,13 +814,12 @@ extern "C" {
   typedef void (*gnutls_free_function) (void *);
   typedef void *(*gnutls_realloc_function) (void *, size_t);
 
-  void gnutls_global_set_mem_functions (gnutls_alloc_function gt_alloc_func,
-					gnutls_alloc_function
-					gt_secure_alloc_func,
-					gnutls_is_secure_function
-					gt_is_secure_func,
-					gnutls_realloc_function gt_realloc_func,
-					gnutls_free_function gt_free_func);
+  void
+  gnutls_global_set_mem_functions (gnutls_alloc_function alloc_func,
+				   gnutls_alloc_function secure_alloc_func,
+				   gnutls_is_secure_function is_secure_func,
+				   gnutls_realloc_function realloc_func,
+				   gnutls_free_function free_func);
 
 /* For use in callbacks */
   extern gnutls_alloc_function gnutls_malloc;
@@ -1053,9 +1049,9 @@ extern "C" {
 						      const char *username,
 						      gnutls_datum_t * key);
   void
-    gnutls_psk_set_server_credentials_function
-    (gnutls_psk_server_credentials_t cred,
-     gnutls_psk_server_credentials_function * func);
+  gnutls_psk_set_server_credentials_function
+  (gnutls_psk_server_credentials_t cred,
+   gnutls_psk_server_credentials_function * func);
 
   typedef int gnutls_psk_client_credentials_function (gnutls_session_t,
 						      char **username,
@@ -1070,12 +1066,13 @@ extern "C" {
   int gnutls_hex_decode (const gnutls_datum_t * hex_data, char *result,
 			 size_t * result_size);
 
-  void gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res,
-					gnutls_dh_params_t dh_params);
+  void
+  gnutls_psk_set_server_dh_params (gnutls_psk_server_credentials_t res,
+				   gnutls_dh_params_t dh_params);
 
-  void gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t
-					      res,
-					      gnutls_params_function * func);
+  void
+  gnutls_psk_set_server_params_function (gnutls_psk_server_credentials_t res,
+					 gnutls_params_function * func);
 
   int gnutls_psk_netconf_derive_key (const char *password,
 				     const char *psk_identity,
diff --git a/lib/includes/gnutls/openpgp.h b/lib/includes/gnutls/openpgp.h
index 56373e278a..c75915e93b 100644
--- a/lib/includes/gnutls/openpgp.h
+++ b/lib/includes/gnutls/openpgp.h
@@ -69,7 +69,7 @@ extern "C"
 /* The key_usage flags are defined in gnutls.h. They are
  * the GNUTLS_KEY_* definitions.
  */
-  int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t cert,
+  int gnutls_openpgp_crt_get_key_usage (gnutls_openpgp_crt_t key,
 					unsigned int *key_usage);
   int gnutls_openpgp_crt_get_fingerprint (gnutls_openpgp_crt_t key, void *fpr,
 					  size_t * fprlen);
@@ -153,7 +153,8 @@ extern "C"
   int gnutls_openpgp_privkey_import (gnutls_openpgp_privkey_t key,
 				     const gnutls_datum_t * data,
 				     gnutls_openpgp_crt_fmt_t format,
-				     const char *pass, unsigned int flags);
+				     const char *password,
+				     unsigned int flags);
   int gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t key,
 					const gnutls_datum_t * hash,
 					gnutls_datum_t * signature);
@@ -287,6 +288,8 @@ extern "C"
  * fingerprint instead of a full key.  See also
  * gnutls_openpgp_set_recv_key_function().
  *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
  */
   typedef int (*gnutls_openpgp_recv_key_func) (gnutls_session_t session,
 					       const unsigned char *keyfpr,
@@ -309,24 +312,24 @@ extern "C"
   gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t res,
 					   const char *certfile,
 					   const char *keyfile,
-					   gnutls_openpgp_crt_fmt_t);
+					   gnutls_openpgp_crt_fmt_t format);
   int
   gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t res,
 					  const gnutls_datum_t * cert,
 					  const gnutls_datum_t * key,
-					  gnutls_openpgp_crt_fmt_t);
+					  gnutls_openpgp_crt_fmt_t format);
 
   int
   gnutls_certificate_set_openpgp_key_file2 (gnutls_certificate_credentials_t res,
 					    const char *certfile,
 					    const char *keyfile,
-					    const char *keyid,
+					    const char *subkey_id,
 					    gnutls_openpgp_crt_fmt_t format);
   int
   gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t res,
 					   const gnutls_datum_t * cert,
 					   const gnutls_datum_t * key,
-					   const char *keyid,
+					   const char *subkey_id,
 					   gnutls_openpgp_crt_fmt_t format);
 
   int
diff --git a/lib/includes/gnutls/pkcs12.h b/lib/includes/gnutls/pkcs12.h
index fcd6a49291..d0d94cb695 100644
--- a/lib/includes/gnutls/pkcs12.h
+++ b/lib/includes/gnutls/pkcs12.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2003, 2004, 2005, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2003, 2004, 2005, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -72,8 +72,9 @@ extern "C"
     GNUTLS_BAG_UNKNOWN = 20
   } gnutls_pkcs12_bag_type_t;
 
-  gnutls_pkcs12_bag_type_t gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t
-						       bag, int indx);
+  gnutls_pkcs12_bag_type_t
+  gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag,
+			      int indx);
   int gnutls_pkcs12_bag_get_data (gnutls_pkcs12_bag_t bag, int indx,
 				  gnutls_datum_t * data);
   int gnutls_pkcs12_bag_set_data (gnutls_pkcs12_bag_t bag,
diff --git a/lib/includes/gnutls/x509.h b/lib/includes/gnutls/x509.h
index 5dc386d398..0abb5867e0 100644
--- a/lib/includes/gnutls/x509.h
+++ b/lib/includes/gnutls/x509.h
@@ -271,11 +271,14 @@ extern "C"
 					    const void *data,
 					    unsigned int data_size,
 					    unsigned int flags);
-  int gnutls_x509_crt_sign (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
+  int gnutls_x509_crt_sign (gnutls_x509_crt_t crt,
+			    gnutls_x509_crt_t issuer,
 			    gnutls_x509_privkey_t issuer_key);
-  int gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt, gnutls_x509_crt_t issuer,
+  int gnutls_x509_crt_sign2 (gnutls_x509_crt_t crt,
+			     gnutls_x509_crt_t issuer,
 			     gnutls_x509_privkey_t issuer_key,
-			     gnutls_digest_algorithm_t, unsigned int flags);
+			     gnutls_digest_algorithm_t dig,
+			     unsigned int flags);
   int gnutls_x509_crt_set_activation_time (gnutls_x509_crt_t cert,
 					   time_t act_time);
   int gnutls_x509_crt_set_expiration_time (gnutls_x509_crt_t cert,
diff --git a/lib/openpgp/extras.c b/lib/openpgp/extras.c
index 00fd9d0c6e..bf0ec39733 100644
--- a/lib/openpgp/extras.c
+++ b/lib/openpgp/extras.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2003, 2004, 2005, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2003, 2004, 2005, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos, Timo Schulz
  *
@@ -256,9 +256,9 @@ gnutls_openpgp_keyring_get_crt_count (gnutls_openpgp_keyring_t ring)
 
 /**
  * gnutls_openpgp_keyring_get_crt - export an openpgp certificate from a keyring
- * @key: Holds the key.
+ * @ring: Holds the keyring.
  * @idx: the index of the certificate to export
- * @crt: An uninitialized #gnutls_openpgp_crt_t structure
+ * @cert: An uninitialized #gnutls_openpgp_crt_t structure
  *
  * This function will extract an OpenPGP certificate from the given
  * keyring.  If the index given is out of range
diff --git a/lib/openpgp/gnutls_openpgp.c b/lib/openpgp/gnutls_openpgp.c
index ddb4baae42..cda68a51c7 100644
--- a/lib/openpgp/gnutls_openpgp.c
+++ b/lib/openpgp/gnutls_openpgp.c
@@ -115,22 +115,24 @@ _gnutls_openpgp_raw_crt_to_gcert (gnutls_cert * gcert,
 }
 
 /**
-  * gnutls_certificate_set_openpgp_key - Used to set keys in a gnutls_certificate_credentials_t structure
-  * @res: is an #gnutls_certificate_credentials_t structure.
-  * @key: contains an openpgp public key
-  * @pkey: is an openpgp private key
-  *
-  * This function sets a certificate/private key pair in the 
-  * gnutls_certificate_credentials_t structure. This function may be called
-  * more than once (in case multiple keys/certificates exist for the
-  * server).
-  *
-  * With this function the subkeys of the certificate are not used.
-  *
-  **/
+ * gnutls_certificate_set_openpgp_key - Used to set keys in a gnutls_certificate_credentials_t structure
+ * @res: is an #gnutls_certificate_credentials_t structure.
+ * @key: contains an openpgp public key
+ * @pkey: is an openpgp private key
+ *
+ * This function sets a certificate/private key pair in the
+ * gnutls_certificate_credentials_t structure.  This function may be
+ * called more than once (in case multiple keys/certificates exist
+ * for the server).
+ *
+ * With this function the subkeys of the certificate are not used.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
+ **/
 int
-gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t
-				    res, gnutls_openpgp_crt_t crt,
+gnutls_certificate_set_openpgp_key (gnutls_certificate_credentials_t res,
+				    gnutls_openpgp_crt_t crt,
 				    gnutls_openpgp_privkey_t pkey)
 {
   int ret;
@@ -283,12 +285,12 @@ leave:
  *   negative error value.
  **/
 int
-gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t
-					res, const gnutls_datum_t * icert,
-					const gnutls_datum_t * ikey,
+gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t res,
+					const gnutls_datum_t * cert,
+					const gnutls_datum_t * key,
 					gnutls_openpgp_crt_fmt_t format)
 {
-  return gnutls_certificate_set_openpgp_key_mem2 (res, icert, ikey,
+  return gnutls_certificate_set_openpgp_key_mem2 (res, cert, key,
 						  NULL, format);
 }
 
@@ -308,8 +310,8 @@ gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t
  *   negative error value.
  **/
 int
-gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t
-					 res, const char *certfile,
+gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t res,
+					 const char *certfile,
 					 const char *keyfile,
 					 gnutls_openpgp_crt_fmt_t format)
 {
@@ -350,7 +352,7 @@ get_keyid (gnutls_openpgp_keyid_t keyid, const char *str)
  * 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
+ * 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.
  *
@@ -360,45 +362,45 @@ get_keyid (gnutls_openpgp_keyid_t keyid, const char *str)
  * Since: 2.4.0
  **/
 int
-gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t
-					 res, const gnutls_datum_t * icert,
-					 const gnutls_datum_t * ikey,
+gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t res,
+					 const gnutls_datum_t * cert,
+					 const gnutls_datum_t * key,
 					 const char *subkey_id,
 					 gnutls_openpgp_crt_fmt_t format)
 {
-  gnutls_openpgp_privkey_t key;
-  gnutls_openpgp_crt_t cert;
+  gnutls_openpgp_privkey_t pkey;
+  gnutls_openpgp_crt_t crt;
   int ret;
 
-  ret = gnutls_openpgp_privkey_init (&key);
+  ret = gnutls_openpgp_privkey_init (&pkey);
   if (ret < 0)
     {
       gnutls_assert ();
       return ret;
     }
 
-  ret = gnutls_openpgp_privkey_import (key, ikey, format, NULL, 0);
+  ret = gnutls_openpgp_privkey_import (pkey, key, format, NULL, 0);
   if (ret < 0)
     {
       gnutls_assert ();
-      gnutls_openpgp_privkey_deinit (key);
+      gnutls_openpgp_privkey_deinit (pkey);
       return ret;
     }
 
-  ret = gnutls_openpgp_crt_init (&cert);
+  ret = gnutls_openpgp_crt_init (&crt);
   if (ret < 0)
     {
       gnutls_assert ();
-      gnutls_openpgp_privkey_deinit (key);
+      gnutls_openpgp_privkey_deinit (pkey);
       return ret;
     }
 
-  ret = gnutls_openpgp_crt_import (cert, icert, format);
+  ret = gnutls_openpgp_crt_import (crt, cert, format);
   if (ret < 0)
     {
       gnutls_assert ();
-      gnutls_openpgp_privkey_deinit (key);
-      gnutls_openpgp_crt_deinit (cert);
+      gnutls_openpgp_privkey_deinit (pkey);
+      gnutls_openpgp_crt_deinit (crt);
       return ret;
     }
 
@@ -407,30 +409,30 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t
       gnutls_openpgp_keyid_t keyid;
 
       if (strcasecmp (subkey_id, "auto") == 0)
-	ret = gnutls_openpgp_crt_get_auth_subkey (cert, keyid, 1);
+	ret = gnutls_openpgp_crt_get_auth_subkey (crt, keyid, 1);
       else
 	ret = get_keyid (keyid, subkey_id);
 
       if (ret >= 0)
 	{
-	  ret = gnutls_openpgp_crt_set_preferred_key_id (cert, keyid);
+	  ret = gnutls_openpgp_crt_set_preferred_key_id (crt, keyid);
 	  if (ret >= 0)
-	    ret = gnutls_openpgp_privkey_set_preferred_key_id (key, keyid);
+	    ret = gnutls_openpgp_privkey_set_preferred_key_id (pkey, keyid);
 	}
 
       if (ret < 0)
 	{
 	  gnutls_assert ();
-	  gnutls_openpgp_privkey_deinit (key);
-	  gnutls_openpgp_crt_deinit (cert);
+	  gnutls_openpgp_privkey_deinit (pkey);
+	  gnutls_openpgp_crt_deinit (crt);
 	  return ret;
 	}
     }
 
-  ret = gnutls_certificate_set_openpgp_key (res, cert, key);
+  ret = gnutls_certificate_set_openpgp_key (res, crt, pkey);
 
-  gnutls_openpgp_privkey_deinit (key);
-  gnutls_openpgp_crt_deinit (cert);
+  gnutls_openpgp_privkey_deinit (pkey);
+  gnutls_openpgp_crt_deinit (crt);
 
   return ret;
 }
@@ -447,8 +449,9 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t
  * This funtion is used to load OpenPGP keys into the GnuTLS credential 
  * structure. The files should contain non encrypted keys.
  *
- * 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.
+ * 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.
@@ -599,6 +602,7 @@ gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c,
  * @c: A certificate credentials structure
  * @data: buffer with keyring data.
  * @dlen: length of data buffer.
+ * @format: the format of the keyring
  *
  * The function is used to set keyrings that will be used internally
  * by various OpenPGP functions. For example to find a key when it
@@ -609,8 +613,8 @@ gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c,
  *   negative error value.
  **/
 int
-gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t
-					    c, const opaque * data,
+gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t c,
+					    const opaque * data,
 					    size_t dlen,
 					    gnutls_openpgp_crt_fmt_t format)
 {
diff --git a/lib/openpgp/pgp.c b/lib/openpgp/pgp.c
index 09ae1047c9..d6182e80a8 100644
--- a/lib/openpgp/pgp.c
+++ b/lib/openpgp/pgp.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Timo Schulz, Nikos Mavrogiannopoulos
  *
@@ -1549,6 +1549,8 @@ gnutls_openpgp_crt_get_preferred_key_id (gnutls_openpgp_crt_t key,
  * This allows setting a preferred key id for the given certificate.
  * This key will be used by functions that involve key handling.
  *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
  **/
 int
 gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key,
@@ -1579,7 +1581,7 @@ gnutls_openpgp_crt_set_preferred_key_id (gnutls_openpgp_crt_t key,
 
 /**
  * gnutls_openpgp_crt_get_auth_subkey - Gets the keyID of an authentication subkey
- * @key: the structure that contains the OpenPGP public key.
+ * @crt: the structure that contains the OpenPGP public key.
  * @keyid: the struct to save the keyid.
  * @flag: Non zero indicates that a valid subkey is always returned.
  *
diff --git a/lib/openpgp/privkey.c b/lib/openpgp/privkey.c
index 2aff7dee3d..d84a35fcc7 100644
--- a/lib/openpgp/privkey.c
+++ b/lib/openpgp/privkey.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation
+ * Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -77,8 +77,8 @@ gnutls_openpgp_privkey_deinit (gnutls_openpgp_privkey_t key)
  * gnutls_openpgp_privkey_import - import a RAW or BASE64 encoded key
  * @key: The structure to store the parsed key.
  * @data: The RAW or BASE64 encoded key.
- * @format: One of gnutls_openpgp_crt_fmt_t elements.
- * @password: (unused for now)
+ * @format: One of #gnutls_openpgp_crt_fmt_t elements.
+ * @password: not used for now
  * @flags: should be zero
  *
  * This function will convert the given RAW or Base64 encoded key to
diff --git a/lib/x509/crq.c b/lib/x509/crq.c
index 3014ed8d33..67ecdbc2a4 100644
--- a/lib/x509/crq.c
+++ b/lib/x509/crq.c
@@ -2004,6 +2004,7 @@ gnutls_x509_crq_set_key_usage (gnutls_x509_crq_t crq, unsigned int usage)
  * @indx: This specifies which OID to return. Use zero to get the first one.
  * @oid: a pointer to a buffer to hold the OID (may be null)
  * @sizeof_oid: initially holds the size of @oid
+ * @critical: output variable with critical flag, may be NULL.
  *
  * This function will extract the key purpose OIDs of the Certificate
  * specified by the given index.  These are stored in the Extended
diff --git a/lib/x509/dn.c b/lib/x509/dn.c
index 7ce6df2712..662fd9f236 100644
--- a/lib/x509/dn.c
+++ b/lib/x509/dn.c
@@ -977,7 +977,6 @@ gnutls_x509_dn_init (gnutls_x509_dn_t * dn)
 
 /**
  * gnutls_x509_dn_import: get opaque DN object from DER RDN sequence
- *
  * @dn: the structure that will hold the imported DN
  * @data: should contain a DER encoded RDN sequence
  *
diff --git a/lib/x509/pkcs12_bag.c b/lib/x509/pkcs12_bag.c
index 42bc8f2075..3a5bb89a23 100644
--- a/lib/x509/pkcs12_bag.c
+++ b/lib/x509/pkcs12_bag.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2003, 2004, 2005, 2008 Free Software Foundation
+ * Copyright (C) 2003, 2004, 2005, 2008, 2009 Free Software Foundation
  *
  * Author: Nikos Mavrogiannopoulos
  *
@@ -95,14 +95,14 @@ gnutls_pkcs12_bag_deinit (gnutls_pkcs12_bag_t bag)
 }
 
 /**
-  * gnutls_pkcs12_bag_get_type - This function returns the bag's type
-  * @bag: The bag
-  * @indx: The element of the bag to get the type
-  *
-  * This function will return the bag's type. One of the gnutls_pkcs12_bag_type_t
-  * enumerations.
-  *
-  **/
+ * gnutls_pkcs12_bag_get_type - This function returns the bag's type
+ * @bag: The bag
+ * @indx: The element of the bag to get the type
+ *
+ * This function will return the bag's type.
+ *
+ * Returns: One of the #gnutls_pkcs12_bag_type_t enumerations.
+ **/
 gnutls_pkcs12_bag_type_t
 gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag, int indx)
 {
@@ -118,12 +118,14 @@ gnutls_pkcs12_bag_get_type (gnutls_pkcs12_bag_t bag, int indx)
 }
 
 /**
-  * gnutls_pkcs12_bag_get_count - This function returns the bag's elements count
-  * @bag: The bag
-  *
-  * This function will return the number of the elements withing the bag. 
-  *
-  **/
+ * gnutls_pkcs12_bag_get_count - This function returns the bag's elements count
+ * @bag: The bag
+ *
+ * This function will return the number of the elements withing the bag.
+ *
+ * Returns: Number of elements in bag, or an negative error code on
+ *   error.
+ **/
 int
 gnutls_pkcs12_bag_get_count (gnutls_pkcs12_bag_t bag)
 {
@@ -622,13 +624,16 @@ gnutls_pkcs12_bag_set_friendly_name (gnutls_pkcs12_bag_t bag, int indx,
 
 
 /**
-  * gnutls_pkcs12_bag_decrypt - This function will decrypt an encrypted bag
-  * @bag: The bag
-  * @pass: The password used for encryption. This can only be ASCII.
-  *
-  * This function will decrypt the given encrypted bag and return 0 on success.
-  *
-  **/
+ * gnutls_pkcs12_bag_decrypt - This function will decrypt an encrypted bag
+ * @bag: The bag
+ * @pass: The password used for encryption, must be ASCII.
+ *
+ * This function will decrypt the given encrypted bag and return 0 on
+ * success.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
+ **/
 int
 gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t bag, const char *pass)
 {
@@ -675,14 +680,16 @@ gnutls_pkcs12_bag_decrypt (gnutls_pkcs12_bag_t bag, const char *pass)
 }
 
 /**
-  * gnutls_pkcs12_bag_encrypt - This function will encrypt a bag
-  * @bag: The bag
-  * @pass: The password used for encryption. This can only be ASCII.
-  * @flags: should be one of gnutls_pkcs_encrypt_flags_t elements bitwise or'd
-  *
-  * This function will encrypt the given bag and return 0 on success.
-  *
-  **/
+ * gnutls_pkcs12_bag_encrypt - This function will encrypt a bag
+ * @bag: The bag
+ * @pass: The password used for encryption, must be ASCII
+ * @flags: should be one of #gnutls_pkcs_encrypt_flags_t elements bitwise or'd
+ *
+ * This function will encrypt the given bag.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
+ **/
 int
 gnutls_pkcs12_bag_encrypt (gnutls_pkcs12_bag_t bag, const char *pass,
 			   unsigned int flags)
diff --git a/lib/x509/x509.c b/lib/x509/x509.c
index 86ce2d2b0b..1f6616deb3 100644
--- a/lib/x509/x509.c
+++ b/lib/x509/x509.c
@@ -1541,20 +1541,20 @@ gnutls_x509_crt_get_extension_by_oid (gnutls_x509_crt_t cert,
 }
 
 /**
-  * gnutls_x509_crt_get_extension_oid - This function returns the specified extension OID
-  * @cert: should contain a #gnutls_x509_crt_t structure
-  * @indx: Specifies which extension OID to send. Use zero to get the first one.
-  * @oid: a pointer to a structure to hold the OID (may be null)
-  * @sizeof_oid: initially holds the size of @oid
-  *
-  * This function will return the requested extension OID in the certificate.
-  * The extension OID will be stored as a string in the provided buffer.
-  *
-  * A negative value may be returned in case of parsing error.
-  * If your have reached the last extension available 
-  * GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
-  *
-  **/
+ * gnutls_x509_crt_get_extension_oid - get the specified extension OID
+ * @cert: should contain a #gnutls_x509_crt_t structure
+ * @indx: Specifies which extension OID to send. Use zero to get the first one.
+ * @oid: a pointer to a structure to hold the OID (may be null)
+ * @sizeof_oid: initially holds the size of @oid
+ *
+ * This function will return the requested extension OID in the certificate.
+ * The extension OID will be stored as a string in the provided buffer.
+ *
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.  If you have reached the
+ *   last extension available %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
+ *   will be returned.
+ **/
 int
 gnutls_x509_crt_get_extension_oid (gnutls_x509_crt_t cert, int indx,
 				   void *oid, size_t * sizeof_oid)
@@ -1669,9 +1669,10 @@ gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t cert, int indx,
  * if you want to get data indexed by the extension OID rather than
  * sequence.
  *
- * Return 0 on success.  A negative value may be returned in case of
- * parsing error.  If you have reached the last extension available
- * GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE will be returned.
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.  If you have reached the
+ *   last extension available %GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE
+ *   will be returned.
  **/
 int
 gnutls_x509_crt_get_extension_data (gnutls_x509_crt_t cert, int indx,
diff --git a/lib/x509/x509_write.c b/lib/x509/x509_write.c
index 6ee514a94a..f19502db00 100644
--- a/lib/x509/x509_write.c
+++ b/lib/x509/x509_write.c
@@ -1169,11 +1169,13 @@ gnutls_x509_crt_set_authority_key_id (gnutls_x509_crt_t cert,
  *
  * Subsequent calls to this function will append OIDs to the OID list.
  *
- * On success 0 is returned.
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
  **/
 int
 gnutls_x509_crt_set_key_purpose_oid (gnutls_x509_crt_t cert,
-				     const void *oid, unsigned int critical)
+				     const void *oid,
+				     unsigned int critical)
 {
   int result;
   gnutls_datum_t old_id, der_data;
diff --git a/libextra/gnutls_ia.c b/libextra/gnutls_ia.c
index cbc1c63640..4e2c633aca 100644
--- a/libextra/gnutls_ia.c
+++ b/libextra/gnutls_ia.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2005, 2006, 2008 Free Software Foundation
+ * Copyright (C) 2005, 2006, 2008, 2009 Free Software Foundation
  *
  * Author: Simon Josefsson
  *
@@ -9,12 +9,12 @@
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation, either version 3 of the License, or
  * (at your option) any later version.
- *               
+ *
  * GNUTLS-EXTRA is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
- *                               
+ *
  * You should have received a copy of the GNU General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
@@ -635,7 +635,8 @@ gnutls_ia_handshake_p (gnutls_session_t session)
  * Perform a TLS/IA handshake.  This should be called after
  * gnutls_handshake() iff gnutls_ia_handshake_p().
  *
- * Return 0 on success, or an error code.
+ * Returns: On success, %GNUTLS_E_SUCCESS (zero) is returned,
+ *   otherwise an error code is returned.
  **/
 int
 gnutls_ia_handshake (gnutls_session_t session)