Documentation: complete non finished documentation comments

 * too much warnings when generating doc, now we can concentrate on
   undocumented symbols (in
   lasso/docs/reference/lasso/lasso-undocumented.txt).

23 files changed, 127 insertions, 89 deletions

diff --git a/lasso/errors.h b/lasso/errors.h
index 039be943..2ead4f38 100644
--- a/lasso/errors.h
+++ b/lasso/errors.h
@@ -98,6 +98,11 @@
  * Construction of an object from an XML document failed.
  */
 #define LASSO_XML_ERROR_OBJECT_CONSTRUCTION_FAILED     -15
+/**
+ * LASSO_XML_ERROR_MISSING_NAMESPACE:
+ *
+ * A namespace is missing.
+ */
 #define LASSO_XML_ERROR_MISSING_NAMESPACE              -16
 /**
  * LASSO_XML_ERROR_SCHEMA_INVALID_FRAGMENT:
diff --git a/lasso/id-wsf/id_ff_extensions.c b/lasso/id-wsf/id_ff_extensions.c
index 26d7290f..50782763 100644
--- a/lasso/id-wsf/id_ff_extensions.c
+++ b/lasso/id-wsf/id_ff_extensions.c
@@ -50,11 +50,12 @@
 
 /**
  * lasso_login_assertion_add_discovery:
- * @login: a #LassoLogin
- * @assertion:
+ * @login: a #LassoLogin object
+ * @assertion: a #LassoSamlAssertion object
  *
- * Adds AttributeStatement and ResourceOffering attributes to assertion if
- * there is a discovery service.
+ * Adds AttributeStatement and ResourceOffering attributes to @assertion of a @login object if there
+ * is a discovery service registerered in the @LassoLogin.server field.
+ * .
  **/
 void
 lasso_login_assertion_add_discovery(LassoLogin *login, LassoSamlAssertion *assertion)
@@ -95,10 +96,11 @@ lasso_login_assertion_add_discovery(LassoLogin *login, LassoSamlAssertion *asser
 
 /**
  * lasso_login_set_encryptedResourceId:
- * @login: a #LassoLogin
- * @encryptedResourceId:
+ * @login: a #LassoLogin object
+ * @encryptedResourceId: the #LassoDiscoEncryptedResourceID to setup in the login object
  *
- * ...
+ * Set the #LassoDiscoEncryptedResourceID to place the next produced assertions as an ID-WSF 1.0
+ * bootstrap.
  *
  * Return value: 0 on success; or a negative value otherwise.
  **/
@@ -119,9 +121,9 @@ lasso_login_set_encryptedResourceId(LassoLogin *login,
 /**
  * lasso_login_set_resourceId:
  * @login: a #LassoLogin
- * @content:
+ * @content: a resourceID identifier
  *
- * ...
+ * Set the resourceId to place in the next produced assertion for ID-WSF bootstrap.
  *
  * Return value: 0 on success; or a negative value otherwise.
  **/
@@ -364,9 +366,9 @@ lasso_server_add_service_from_dump(LassoServer *server, const gchar *dump)
 /**
  * lasso_server_get_service:
  * @server: a #LassoServer
- * @serviceType:
+ * @serviceType: the service type
  *
- * ...
+ * Look up a disco service instance corresponding to this service type.
  *
  * Return value: the #LassoDiscoServiceInstance, NULL if it was not found.
  *     The #LassoDiscoServiceInstance is owned by Lasso and should not be
diff --git a/lasso/id-wsf/wsf_profile.c b/lasso/id-wsf/wsf_profile.c
index 72f18af3..4dd052a8 100644
--- a/lasso/id-wsf/wsf_profile.c
+++ b/lasso/id-wsf/wsf_profile.c
@@ -1195,13 +1195,16 @@ lasso_wsf_profile_new_full(LassoServer *server, LassoDiscoResourceOffering *offe
 
 /**
  * add_signature_template:
- * @server:
- * @doc:
- * @node
- * @signature_ptr:
+ * @server: a #LassoServer object
+ * @doc: a #xmlDoc structure
+ * @node a #xmlNode structure
+ * @signature_ptr: an output argument for an #xmlNode structure
  *
- * Create a new XmlSig template without any reference and return the create
- * Signature node. If node is not null add Signature as a last child to it.
+ * Create a new XMLDSig template without any reference and return the created
+ * Signature node. If node is not NULL add Signature as a last child to it. If @signature_ptr is not
+ * NULL the template node is stored there.
+ *
+ * Return value: 0 if successful, LASSO_DS_ERROR_SIGNATURE_TMPL_CREATION_FAILED otherwise.
  */
 static gint
 add_signature_template(LassoServer *server, xmlDoc *doc, xmlNode *node, xmlNode **signature_ptr) {
diff --git a/lasso/lasso.c b/lasso/lasso.c
index cb19957a..b006dfb6 100644
--- a/lasso/lasso.c
+++ b/lasso/lasso.c
@@ -29,10 +29,11 @@
  * <sec2>
  * <title>Environment variables</title>
  * <para>
- * <literal>LASSO_FLAG</literal> is an environment vairable containing white-space separated values
+ * <literal>LASSO_FLAG</literal> is an environment variable containing white-space separated values
  * which allows to modify the behaviour of lasso. To negate the effect of one of
- * the value, just add <literal>no-</literal> in front of its name. Those values
- * are:
+ * the value, just add <literal>no-</literal> in front of its name. The flag are also modifiable
+ * using the lasso_set_flag() function. Those values are:
+ *
  * <informaltable frame="non">
  * <tgroup cols="2">
  * <tbody>
@@ -64,7 +65,8 @@
  * </tbody>
  * </tgroup>
  * </informaltable>
- *  </para>
+ * </para>
+ * </sec2>
  **/
 
 #include <stdlib.h> /* getenv */
@@ -267,8 +269,8 @@ lasso_check_version(int major, int minor, int subminor, LassoCheckVersionMode mo
  * lasso_set_flag:
  * @flag: a string representing a flag name, prefix with 'no-' to disable it.
  *
- * Set a debugging flag. You can also use the environment variable named by the #LASSO_FLAG_ENV_VAR
- * macro to get the same effect. LASSO_DEBUG must contain flag name separated by spaces, commas,
+ * Set a debugging flag. You can also use the environment variable LASSO_FLAG
+ * to get the same effect. LASSO_FLAG must contain flag name separated by spaces, commas,
  * tabulations or colons.
  */
 void lasso_set_flag(char *flag) {
@@ -319,8 +321,3 @@ static void lasso_flag_parse_environment_variable() {
 		} while ((token = strtok_r(NULL, delim, &save_ptr)) != NULL);
 	}
 }
-
-
-
-
-
diff --git a/lasso/saml-2.0/saml2_helper.h b/lasso/saml-2.0/saml2_helper.h
index e0d967c0..030cf440 100644
--- a/lasso/saml-2.0/saml2_helper.h
+++ b/lasso/saml-2.0/saml2_helper.h
@@ -43,10 +43,30 @@ typedef enum {
 	LASSO_SAML2_ASSERTION_INDETERMINATE
 } LassoSaml2AssertionValidationState;
 
+/**
+ * LASSO_DURATION_MINUTE:
+ *
+ * Number of seconds in a minute.
+ */
 #define LASSO_DURATION_MINUTE 60
+/**
+ * LASSO_DURATION_HOUR:
+ *
+ * Number of seconds in a hour.
+ */
 #define LASSO_DURATION_HOUR 3600
-#define LASSO_DURATION_DAY 24*2600
-#define LASSO_DURATION_WEEK LASSO_DURATION_DAY*7
+/**
+ * LASSO_DURATION_DAY:
+ *
+ * Number of seconds in a day.
+ */
+#define LASSO_DURATION_DAY 24*LASSO_DURATION_HOUR
+/**
+ * LASSO_DURATION_WEEK:
+ *
+ * Number of seconds in a week.
+ */
+#define LASSO_DURATION_WEEK 7*LASSO_DURATION_DAY
 
 LASSO_EXPORT gboolean lasso_saml2_assertion_has_audience_restriction(
 		LassoSaml2Assertion *saml2_assertion);
diff --git a/lasso/xml/id-wsf-2.0/disco_abstract.c b/lasso/xml/id-wsf-2.0/disco_abstract.c
index 12c87c88..837f2129 100644
--- a/lasso/xml/id-wsf-2.0/disco_abstract.c
+++ b/lasso/xml/id-wsf-2.0/disco_abstract.c
@@ -109,10 +109,10 @@ lasso_idwsf2_disco_abstract_new()
 
 /**
  * lasso_idwsf2_disco_abstract_new_with_string:
- * @content:
+ * @content: the content string
  *
  * Creates a new #LassoIdWsf2DiscoAbstract object and initializes it
- * with @content.
+ * with @content as content.
  *
  * Return value: a newly created #LassoIdWsf2DiscoAbstract object
  **/
diff --git a/lasso/xml/id-wsf-2.0/disco_provider_id.c b/lasso/xml/id-wsf-2.0/disco_provider_id.c
index bda2cf6d..d5f2abbe 100644
--- a/lasso/xml/id-wsf-2.0/disco_provider_id.c
+++ b/lasso/xml/id-wsf-2.0/disco_provider_id.c
@@ -109,10 +109,10 @@ lasso_idwsf2_disco_provider_id_new()
 
 /**
  * lasso_idwsf2_disco_provider_id_new_with_string:
- * @content:
+ * @content: the content string
  *
  * Creates a new #LassoIdWsf2DiscoProviderID object and initializes it
- * with @content.
+ * with @content as content.
  *
  * Return value: a newly created #LassoIdWsf2DiscoProviderID object
  **/
diff --git a/lasso/xml/id-wsf-2.0/disco_service_type.c b/lasso/xml/id-wsf-2.0/disco_service_type.c
index 4d8681f3..feba4c8a 100644
--- a/lasso/xml/id-wsf-2.0/disco_service_type.c
+++ b/lasso/xml/id-wsf-2.0/disco_service_type.c
@@ -109,10 +109,10 @@ lasso_idwsf2_disco_service_type_new()
 
 /**
  * lasso_idwsf2_disco_service_type_new_with_string:
- * @content:
+ * @content: the content string
  *
  * Creates a new #LassoIdWsf2DiscoServiceType object and initializes it
- * with @content.
+ * with @content as content.
  *
  * Return value: a newly created #LassoIdWsf2DiscoServiceType object
  **/
diff --git a/lasso/xml/lib_assertion.c b/lasso/xml/lib_assertion.c
index c15ccab6..feff3636 100644
--- a/lasso/xml/lib_assertion.c
+++ b/lasso/xml/lib_assertion.c
@@ -126,14 +126,15 @@ lasso_lib_assertion_new()
 
 /**
  * lasso_lib_assertion_new_full:
- * @issuer:
- * @requestID:
- * @audience:
- * @notBefore:
- * @notOnOrAfter:
+ * @issuer: the issuer entityID string
+ * @requestID:(allow-none): the identifier of the request which initiated the creation of this
+ * assertion
+ * @audience:(allow-none): the entityID of the receiver of this assertion
+ * @notBefore: a timestamp formatted as iso-8601
+ * @notOnOrAfter: a timestamp formatted as iso-8601
  *
- * Creates a new #LassoLibAssertion object and initializes it with the
- * parameters.
+ * Creates a new #LassoLibAssertion object and initializes its Issuer, InResponseTo,
+ * AudienceRestrictionCondition, notBefore and notOnOrAfter fields or attributes.
  *
  * Return value: a newly created #LassoLibAssertion object
  **/
diff --git a/lasso/xml/lib_authentication_statement.c b/lasso/xml/lib_authentication_statement.c
index 7091a6f5..fb36d203 100644
--- a/lasso/xml/lib_authentication_statement.c
+++ b/lasso/xml/lib_authentication_statement.c
@@ -119,14 +119,16 @@ lasso_lib_authentication_statement_new(void)
 
 /**
  * lasso_lib_authentication_statement_new_full:
- * @authenticationMethod:
- * @authenticationInstant: AuthenticationInstant (NULL to get current time)
- * @reauthenticateOnOrAfter:
- * @sp_identifier:
- * @idp_identifier:
+ * @authenticationMethod: an URI identifier for the authentication method
+ * @authenticationInstant:(allow-none): an ISO-8601 formatted timestamp for the authentication
+ * instant
+ * @reauthenticateOnOrAfter:(allow-none): an ISO-8601 formatted timestamp to set a limit on the value of this
+ * authentication
+ * @sp_identifier:(allow-none) a #LassoSamlNameIdentifier object, the SP qualifier for the subject of this statement
+ * @idp_identifier: a #LassoSamlNameIdentifier object, the IdP qualifier for the subject of this statemtn
  *
- * Creates a new #LassoLibAuthenticationStatement object and initializes it
- * with the parameters.
+ * Creates a new #LassoLibAuthenticationStatement object and initializes its subject,
+ * its AuthenticationMethod, its AuthenticationInstant, 
  *
  * Return value: a newly created #LassoLibAuthenticationStatement object
  **/
@@ -144,7 +146,7 @@ lasso_lib_authentication_statement_new_full(const char *authenticationMethod,
 	char *time;
 
 	g_return_val_if_fail(LASSO_IS_SAML_NAME_IDENTIFIER(idp_identifier), NULL);
-	g_return_val_if_fail(sp_identifier || idp_identifier, NULL);
+	g_return_val_if_fail(authenticationMethod, NULL);
 
 	subject = lasso_lib_subject_new();
 	if (sp_identifier == NULL) {
diff --git a/lasso/xml/lib_federation_termination_notification.c b/lasso/xml/lib_federation_termination_notification.c
index c08a1320..aed69fdd 100644
--- a/lasso/xml/lib_federation_termination_notification.c
+++ b/lasso/xml/lib_federation_termination_notification.c
@@ -194,8 +194,8 @@ lasso_lib_federation_termination_notification_new()
  * lasso_lib_federation_termination_notification_new_full:
  * @providerID: the provider ID doing the notification
  * @nameIdentifier: the name identifier for the federation to terminate.
- * @sign_type:
- * @sign_method:
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
  * Creates a new #LassoLibFederationTerminationNotification object and
  * initializes it with the parameters.
diff --git a/lasso/xml/lib_logout_request.c b/lasso/xml/lib_logout_request.c
index 9a603fca..69d8405b 100644
--- a/lasso/xml/lib_logout_request.c
+++ b/lasso/xml/lib_logout_request.c
@@ -180,8 +180,8 @@ lasso_lib_logout_request_new()
  * lasso_lib_logout_request_new_full:
  * @providerID: the provider ID requesting the logout
  * @nameIdentifier: the name identifier to log out
- * @sign_type:
- * @sign_method:
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
  * Creates a new #LassoLibLogoutRequest object and initializes it with the
  * parameters.
diff --git a/lasso/xml/lib_logout_response.c b/lasso/xml/lib_logout_response.c
index 069c06ad..2e56947a 100644
--- a/lasso/xml/lib_logout_response.c
+++ b/lasso/xml/lib_logout_response.c
@@ -94,11 +94,11 @@ lasso_lib_logout_response_new()
 
 /**
  * lasso_lib_logout_response_new_full:
- * @providerID:
- * @statusCodeValue:
+ * @providerID: the providerID of the responded
+ * @statusCodeValue: a response status code
  * @request: the request this is a response to
- * @sign_type:
- * @sign_method:
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
  * Creates a new #LassoLibLogoutResponse object and initializes it with the
  * parameters.
diff --git a/lasso/xml/lib_name_identifier_mapping_request.c b/lasso/xml/lib_name_identifier_mapping_request.c
index 3c675e5b..142fe5dd 100644
--- a/lasso/xml/lib_name_identifier_mapping_request.c
+++ b/lasso/xml/lib_name_identifier_mapping_request.c
@@ -128,13 +128,14 @@ lasso_lib_name_identifier_mapping_request_new()
 /**
  * lasso_lib_name_identifier_mapping_request_new_full:
  * @providerID: the provider ID requesting the name identifier mapping
- * @nameIdentifier:
- * @targetNamespace:
- * @sign_type:
- * @sign_method:
+ * @nameIdentifier: a #LassoSamlNameIdentifier object
+ * @targetNamespace: an URI for the target namespace
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
- * Creates a new #LassoLibNameIdentifierMappingRequest object and initializes
- * it with the parameters.
+ * Creates a new #LassoLibNameIdentifierMappingRequest object and initializes it with the
+ * parameters. It also setups the signature on the request object, you must preceise the signing key
+ * later.
  *
  * Return value: a newly created #LassoLibNameIdentifierMappingRequest object
  **/
diff --git a/lasso/xml/lib_name_identifier_mapping_response.c b/lasso/xml/lib_name_identifier_mapping_response.c
index 43777a87..22fc5853 100644
--- a/lasso/xml/lib_name_identifier_mapping_response.c
+++ b/lasso/xml/lib_name_identifier_mapping_response.c
@@ -123,11 +123,11 @@ lasso_lib_name_identifier_mapping_response_new()
 
 /**
  * lasso_lib_name_identifier_mapping_response_new_full:
- * @providerID:
- * @statusCodeValue:
- * @request: the request this is a response to
- * @sign_type:
- * @sign_method:
+ * @providerID: the providerID of the responder
+ * @statusCodeValue: a response status code
+ * @request: the request which is asnwered by this response
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
  * Creates a new #LassoLibNameIdentifierMappingResponse object and initializes
  * it with the parameters.
diff --git a/lasso/xml/lib_register_name_identifier_request.c b/lasso/xml/lib_register_name_identifier_request.c
index 87a61af4..0a883c3e 100644
--- a/lasso/xml/lib_register_name_identifier_request.c
+++ b/lasso/xml/lib_register_name_identifier_request.c
@@ -193,12 +193,13 @@ lasso_lib_register_name_identifier_request_new()
 
 /**
  * lasso_lib_register_name_identifier_request_new_full:
- * @providerID:
- * @idpNameIdentifier:
- * @spNameIdentifier:
- * @oldNameIdentifier:
- * @sign_type:
- * @sign_method:
+ * @providerID: the providerID of the requester
+ * @idpNameIdentifier: a #LassoSamlNameIdentifier object, giving the new idp provided name
+ * identifier
+ * @spNameIdentifier: a #LassoSamlNameIdentifier object, giving the new sp provided name identifier
+ * @oldNameIdentifier: a #LassoSamlNameIdentifier object, giving the old name identifier
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
  * Creates a new #LassoLibRegisterNameIdentifierRequest object and initializes
  * it with the parameters.
diff --git a/lasso/xml/lib_register_name_identifier_response.c b/lasso/xml/lib_register_name_identifier_response.c
index 87852516..e87dce92 100644
--- a/lasso/xml/lib_register_name_identifier_response.c
+++ b/lasso/xml/lib_register_name_identifier_response.c
@@ -98,11 +98,11 @@ lasso_lib_register_name_identifier_response_new()
 
 /**
  * lasso_lib_register_name_identifier_response_new_full:
- * @providerID:
- * @statusCodeValue:
- * @request: the request this is a response to
- * @sign_type:
- * @sign_method:
+ * @providerID: the providerID of the responder
+ * @statusCodeValue: a response status code
+ * @request: the request which is answered by this response
+ * @sign_type: a #LassoSignatureType value
+ * @sign_method: a #LassoSignatureMethod value
  *
  * Creates a new #LassoLibRegisterNameIdentifierResponse object and initializes
  * it with the parameters.
diff --git a/lasso/xml/strings.h b/lasso/xml/strings.h
index 6d532b9e..e7c8ba7b 100644
--- a/lasso/xml/strings.h
+++ b/lasso/xml/strings.h
@@ -584,10 +584,15 @@
 /**
  * LASSO_METADATA_HREF:
  *
- * Namespace for FIXME
+ * Namespace for ID-FF 1.2 metadatas.
  *
  */
 #define LASSO_METADATA_HREF	 "urn:liberty:metadata:2003-08"
+/**
+ * LASSO_METADATA_PREFIX:
+ *
+ * Preferred prefix for ID-FF 1.2 metadata namespace.
+ */
 #define LASSO_METADATA_PREFIX	 "md"
 
 /*****************************************************************************/
diff --git a/lasso/xml/tools.c b/lasso/xml/tools.c
index f40f10f6..69a34315 100644
--- a/lasso/xml/tools.c
+++ b/lasso/xml/tools.c
@@ -668,7 +668,7 @@ done:
 }
 
 /**
- * lasso_saml2_query_verify_signature(const char *query, const xmlSecKey *sender_public_key):
+ * lasso_saml2_query_verify_signature:
  * @query: a query string
  * @sender_public_key: the #xmlSecKey for the sender
  *
diff --git a/lasso/xml/ws/wsa_attributed_qname.c b/lasso/xml/ws/wsa_attributed_qname.c
index 3f5b911f..012fac3a 100644
--- a/lasso/xml/ws/wsa_attributed_qname.c
+++ b/lasso/xml/ws/wsa_attributed_qname.c
@@ -117,10 +117,10 @@ lasso_wsa_attributed_qname_new()
 
 /**
  * lasso_wsa_attributed_qname_new_with_string:
- * @content:
+ * @content: a content string.
  *
  * Creates a new #LassoWsAddrAttributedQName object and initializes it
- * with @content.
+ * with @content as content.
  *
  * Return value: a newly created #LassoWsAddrAttributedQName object
  **/
diff --git a/lasso/xml/ws/wsa_attributed_uri.c b/lasso/xml/ws/wsa_attributed_uri.c
index 50c6aad8..6d594aa6 100644
--- a/lasso/xml/ws/wsa_attributed_uri.c
+++ b/lasso/xml/ws/wsa_attributed_uri.c
@@ -121,10 +121,10 @@ lasso_wsa_attributed_uri_new()
 
 /**
  * lasso_wsa_attributed_uri_new_with_string:
- * @content:
+ * @content: a content string
  *
  * Creates a new #LassoWsAddrAttributedURI object and initializes it
- * with @content.
+ * with @content as content.
  *
  * Return value: a newly created #LassoWsAddrAttributedURI object
  **/
diff --git a/lasso/xml/ws/wsa_relates_to.c b/lasso/xml/ws/wsa_relates_to.c
index 651a3871..dc657380 100644
--- a/lasso/xml/ws/wsa_relates_to.c
+++ b/lasso/xml/ws/wsa_relates_to.c
@@ -121,10 +121,10 @@ lasso_wsa_relates_to_new()
 
 /**
  * lasso_wsa_relates_to_new_with_string:
- * @content:
+ * @content: a content string
  *
  * Creates a new #LassoWsAddrRelatesTo object and initializes it
- * with @content.
+ * with @content as content.
  *
  * Return value: a newly created #LassoWsAddrRelatesTo object
  **/
diff --git a/lasso/xml/ws/wsse_username_token.c b/lasso/xml/ws/wsse_username_token.c
index a6579b9a..ad71d216 100644
--- a/lasso/xml/ws/wsse_username_token.c
+++ b/lasso/xml/ws/wsse_username_token.c
@@ -23,6 +23,7 @@
 
 /**
  * SECTION:wsse_username_token
+ *
  * Transmit username and password credential as a WS-Security token. The password can be transmitted
  * as cleartext or using a digest mode. It also allows to derive encryption and HMAC signing keys.
  */