documenting #LassoIdentity and #LassoFederation

16 files changed, 522 insertions, 229 deletions

diff --git a/docs/reference/lasso-sections.txt b/docs/reference/lasso-sections.txt
index f4dac8e7..776e9402 100644
--- a/docs/reference/lasso-sections.txt
+++ b/docs/reference/lasso-sections.txt
@@ -51,6 +51,73 @@ LASSO_SERVER_GET_CLASS
 </SECTION>
 
 <SECTION>
+<FILE>identity</FILE>
+<TITLE>LassoIdentity</TITLE>
+LassoIdentity
+LassoIdentityClass
+lasso_identity_new
+lasso_identity_new_from_dump
+lasso_identity_destroy
+lasso_identity_dump
+lasso_identity_add_federation
+lasso_identity_get_federation
+lasso_identity_remove_federation
+<SUBSECTION Standard>
+LASSO_IDENTITY
+LASSO_IS_IDENTITY
+LASSO_TYPE_IDENTITY
+lasso_identity_get_type
+LASSO_IDENTITY_CLASS
+LASSO_IS_IDENTITY_CLASS
+LASSO_IDENTITY_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>session</FILE>
+<TITLE>LassoSession</TITLE>
+LassoSession
+LassoSessionClass
+lasso_session_new
+lasso_session_new_from_dump
+lasso_session_add_assertion
+lasso_session_destroy
+lasso_session_dump
+lasso_session_get_assertion
+lasso_session_get_authentication_method
+lasso_session_get_first_providerID
+lasso_session_get_provider_index
+lasso_session_remove_assertion
+<SUBSECTION Standard>
+LASSO_SESSION
+LASSO_IS_SESSION
+LASSO_TYPE_SESSION
+lasso_session_get_type
+LASSO_SESSION_CLASS
+LASSO_IS_SESSION_CLASS
+LASSO_SESSION_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>federation</FILE>
+<TITLE>LassoFederation</TITLE>
+LassoFederation
+lasso_federation_new
+lasso_federation_destroy
+lasso_federation_build_local_name_identifier
+lasso_federation_set_local_name_identifier
+lasso_federation_set_remote_name_identifier
+lasso_federation_verify_name_identifier
+<SUBSECTION Standard>
+LASSO_FEDERATION
+LASSO_IS_FEDERATION
+LASSO_TYPE_FEDERATION
+lasso_federation_get_type
+LASSO_FEDERATION_CLASS
+LASSO_IS_FEDERATION_CLASS
+LASSO_FEDERATION_GET_CLASS
+</SECTION>
+
+<SECTION>
 <FILE>profile</FILE>
 <TITLE>LassoProfile</TITLE>
 lassoMessageType
@@ -743,9 +810,8 @@ LASSO_SAMLP_STATUS_CODE_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>xml</FILE>
+<FILE>node</FILE>
 lassoNodeExportType
-LassoNodePrivate
 <TITLE>LassoNode</TITLE>
 lassoSignatureMethod
 LassoNode
@@ -824,22 +890,6 @@ LASSO_LIB_FEDERATION_TERMINATION_NOTIFICATION_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>lib_idp_provided_name_identifier</FILE>
-<TITLE>LassoLibIDPProvidedNameIdentifier</TITLE>
-LassoLibIDPProvidedNameIdentifier
-LassoLibIDPProvidedNameIdentifierClass
-lasso_lib_idp_provided_name_identifier_new
-<SUBSECTION Standard>
-LASSO_LIB_IDP_PROVIDED_NAME_IDENTIFIER
-LASSO_IS_LIB_IDP_PROVIDED_NAME_IDENTIFIER
-LASSO_TYPE_LIB_IDP_PROVIDED_NAME_IDENTIFIER
-lasso_lib_idp_provided_name_identifier_get_type
-LASSO_LIB_IDP_PROVIDED_NAME_IDENTIFIER_CLASS
-LASSO_IS_LIB_IDP_PROVIDED_NAME_IDENTIFIER_CLASS
-LASSO_LIB_IDP_PROVIDED_NAME_IDENTIFIER_GET_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>lib_logout_response</FILE>
 <TITLE>LassoLibLogoutResponse</TITLE>
 LassoLibLogoutResponse
@@ -894,22 +944,6 @@ LASSO_LIB_NAME_IDENTIFIER_MAPPING_RESPONSE_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>lib_old_provided_name_identifier</FILE>
-<TITLE>LassoLibOLDProvidedNameIdentifier</TITLE>
-LassoLibOLDProvidedNameIdentifier
-LassoLibOLDProvidedNameIdentifierClass
-lasso_lib_old_provided_name_identifier_new
-<SUBSECTION Standard>
-LASSO_LIB_OLD_PROVIDED_NAME_IDENTIFIER
-LASSO_IS_LIB_OLD_PROVIDED_NAME_IDENTIFIER
-LASSO_TYPE_LIB_OLD_PROVIDED_NAME_IDENTIFIER
-lasso_lib_old_provided_name_identifier_get_type
-LASSO_LIB_OLD_PROVIDED_NAME_IDENTIFIER_CLASS
-LASSO_IS_LIB_OLD_PROVIDED_NAME_IDENTIFIER_CLASS
-LASSO_LIB_OLD_PROVIDED_NAME_IDENTIFIER_GET_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>lib_register_name_identifier_request</FILE>
 <TITLE>LassoLibRegisterNameIdentifierRequest</TITLE>
 LassoLibRegisterNameIdentifierRequest
@@ -947,22 +981,6 @@ LASSO_LIB_REGISTER_NAME_IDENTIFIER_RESPONSE_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>lib_sp_provided_name_identifier</FILE>
-<TITLE>LassoLibSPProvidedNameIdentifier</TITLE>
-LassoLibSPProvidedNameIdentifier
-LassoLibSPProvidedNameIdentifierClass
-lasso_lib_sp_provided_name_identifier_new
-<SUBSECTION Standard>
-LASSO_LIB_SP_PROVIDED_NAME_IDENTIFIER
-LASSO_IS_LIB_SP_PROVIDED_NAME_IDENTIFIER
-LASSO_TYPE_LIB_SP_PROVIDED_NAME_IDENTIFIER
-lasso_lib_sp_provided_name_identifier_get_type
-LASSO_LIB_SP_PROVIDED_NAME_IDENTIFIER_CLASS
-LASSO_IS_LIB_SP_PROVIDED_NAME_IDENTIFIER_CLASS
-LASSO_LIB_SP_PROVIDED_NAME_IDENTIFIER_GET_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>lib_status_response</FILE>
 <TITLE>LassoLibStatusResponse</TITLE>
 LassoLibStatusResponse
@@ -1053,40 +1071,6 @@ LASSO_LIB_AUTHENTICATION_STATEMENT_GET_CLASS
 </SECTION>
 
 <SECTION>
-<FILE>soap-env_body</FILE>
-<TITLE>LassoSoapEnvBody</TITLE>
-LassoSoapEnvBody
-LassoSoapEnvBodyClass
-lasso_soap_env_body_new
-lasso_soap_env_body_add_child
-<SUBSECTION Standard>
-LASSO_SOAP_ENV_BODY
-LASSO_IS_SOAP_ENV_BODY
-LASSO_TYPE_SOAP_ENV_BODY
-lasso_soap_env_body_get_type
-LASSO_SOAP_ENV_BODY_CLASS
-LASSO_IS_SOAP_ENV_BODY_CLASS
-LASSO_SOAP_ENV_BODY_GET_CLASS
-</SECTION>
- 
-<SECTION>
-<FILE>soap-env_envelope</FILE>
-<TITLE>LassoSoapEnvEnvelope</TITLE>
-LassoSoapEnvEnvelope
-LassoSoapEnvEnvelopeClass
-lasso_soap_env_envelope_new
-lasso_soap_env_envelope_set_body
-<SUBSECTION Standard>
-LASSO_SOAP_ENV_ENVELOPE
-LASSO_IS_SOAP_ENV_ENVELOPE
-LASSO_TYPE_SOAP_ENV_ENVELOPE
-lasso_soap_env_envelope_get_type
-LASSO_SOAP_ENV_ENVELOPE_CLASS
-LASSO_IS_SOAP_ENV_ENVELOPE_CLASS
-LASSO_SOAP_ENV_ENVELOPE_GET_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>lasso</FILE>
 lasso_init
 lasso_shutdown
@@ -1106,54 +1090,6 @@ LASSO_VERSION_INFO
 </SECTION>
 
 <SECTION>
-<FILE>federation_termination_notification</FILE>
-<TITLE>LassoFederationTerminationNotification</TITLE>
-LassoFederationTerminationNotification
-LassoFederationTerminationNotificationClass
-lasso_federation_termination_notification_new
-lasso_federation_termination_notification_new_from_export
-<SUBSECTION Standard>
-LASSO_FEDERATION_TERMINATION_NOTIFICATION
-LASSO_IS_FEDERATION_TERMINATION_NOTIFICATION
-LASSO_TYPE_FEDERATION_TERMINATION_NOTIFICATION
-lasso_federation_termination_notification_get_type
-LASSO_FEDERATION_TERMINATION_NOTIFICATION_CLASS
-LASSO_IS_FEDERATION_TERMINATION_NOTIFICATION_CLASS
-LASSO_FEDERATION_TERMINATION_NOTIFICATION_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>federation</FILE>
-LASSO_FEDERATION_NODE
-LASSO_FEDERATION_REMOTE_PROVIDERID_NODE
-LASSO_FEDERATION_LOCAL_NAME_IDENTIFIER_NODE
-LASSO_FEDERATION_REMOTE_NAME_IDENTIFIER_NODE
-<TITLE>LassoFederation</TITLE>
-LassoFederation
-LassoFederationClass
-lasso_federation_new
-lasso_federation_new_from_dump
-lasso_federation_copy
-lasso_federation_destroy
-lasso_federation_dump
-lasso_federation_get_remote_nameIdentifier
-lasso_federation_get_local_nameIdentifier
-lasso_federation_remove_local_nameIdentifier
-lasso_federation_remove_remote_nameIdentifier
-lasso_federation_set_local_nameIdentifier
-lasso_federation_set_remote_nameIdentifier
-lasso_federation_verify_nameIdentifier
-<SUBSECTION Standard>
-LASSO_FEDERATION
-LASSO_IS_FEDERATION
-LASSO_TYPE_FEDERATION
-lasso_federation_get_type
-LASSO_FEDERATION_CLASS
-LASSO_IS_FEDERATION_CLASS
-LASSO_FEDERATION_GET_CLASS
-</SECTION>
-
-<SECTION>
 <FILE>lecp</FILE>
 <TITLE>LassoLecp</TITLE>
 LassoLecp
@@ -1178,58 +1114,6 @@ LASSO_IS_LECP_CLASS
 LASSO_LECP_GET_CLASS
 </SECTION>
 
-<SECTION>
-<FILE>identity</FILE>
-LassoIdentityPrivate
-<TITLE>LassoIdentity</TITLE>
-LassoIdentity
-LassoIdentityClass
-lasso_identity_new
-lasso_identity_new_from_dump
-lasso_identity_add_federation
-lasso_identity_copy
-lasso_identity_destroy
-lasso_identity_dump
-lasso_identity_get_federation
-lasso_identity_get_first_providerID
-lasso_identity_get_next_federation_remote_providerID
-lasso_identity_remove_federation
-<SUBSECTION Standard>
-LASSO_IDENTITY
-LASSO_IS_IDENTITY
-LASSO_TYPE_IDENTITY
-lasso_identity_get_type
-LASSO_IDENTITY_CLASS
-LASSO_IS_IDENTITY_CLASS
-LASSO_IDENTITY_GET_CLASS
-</SECTION>
-
-<SECTION>
-<FILE>session</FILE>
-LassoSessionPrivate
-<TITLE>LassoSession</TITLE>
-LassoSession
-LassoSessionClass
-lasso_session_new
-lasso_session_new_from_dump
-lasso_session_add_assertion
-lasso_session_copy
-lasso_session_destroy
-lasso_session_dump
-lasso_session_get_assertion
-lasso_session_get_authentication_method
-lasso_session_get_first_providerID
-lasso_session_get_provider_index
-lasso_session_remove_assertion
-<SUBSECTION Standard>
-LASSO_SESSION
-LASSO_IS_SESSION
-LASSO_TYPE_SESSION
-lasso_session_get_type
-LASSO_SESSION_CLASS
-LASSO_IS_SESSION_CLASS
-LASSO_SESSION_GET_CLASS
-</SECTION>
 
 <SECTION>
 <FILE>strings</FILE>
diff --git a/docs/reference/lasso.sgml b/docs/reference/lasso.sgml
index cf83dc91..2045557d 100644
--- a/docs/reference/lasso.sgml
+++ b/docs/reference/lasso.sgml
@@ -29,7 +29,7 @@
 <!ENTITY LassoSamlpResponseAbstract SYSTEM "sgml/samlp_response_abstract.xml">
 <!ENTITY LassoSamlpStatus SYSTEM "sgml/samlp_status.xml">
 <!ENTITY LassoSamlpStatusCode SYSTEM "sgml/samlp_status_code.xml">
-<!ENTITY LassoNode SYSTEM "sgml/xml.xml">
+<!ENTITY LassoNode SYSTEM "sgml/node.xml">
 <!ENTITY LassoLibLogoutRequest SYSTEM "sgml/lib_logout_request.xml">
 <!ENTITY LassoLibFederationTerminationNotification SYSTEM "sgml/lib_federation_termination_notification.xml">
 <!ENTITY LassoLibLogoutResponse SYSTEM "sgml/lib_logout_response.xml">
diff --git a/docs/reference/tmpl/defederation.sgml b/docs/reference/tmpl/defederation.sgml
index 5415770c..e5e89751 100644
--- a/docs/reference/tmpl/defederation.sgml
+++ b/docs/reference/tmpl/defederation.sgml
@@ -53,8 +53,10 @@ Federation Termination Notification Profile
 
 @defederation: 
 @remote_providerID: 
-@notification_method: 
+@http_method: 
 @Returns: 
+<!-- # Unused Parameters # -->
+@notification_method: 
 
 
 <!-- ##### FUNCTION lasso_defederation_process_notification_msg ##### -->
diff --git a/docs/reference/tmpl/federation.sgml b/docs/reference/tmpl/federation.sgml
new file mode 100644
index 00000000..d207b08e
--- /dev/null
+++ b/docs/reference/tmpl/federation.sgml
@@ -0,0 +1,83 @@
+<!-- ##### SECTION Title ##### -->
+LassoFederation
+
+<!-- ##### SECTION Short_Description ##### -->
+Principal federation between two providers
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT LassoFederation ##### -->
+<para>
+
+</para>
+
+@remote_providerID: 
+@local_nameIdentifier: 
+@remote_nameIdentifier: 
+
+<!-- ##### FUNCTION lasso_federation_new ##### -->
+<para>
+
+</para>
+
+@remote_providerID: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_federation_destroy ##### -->
+<para>
+
+</para>
+
+@federation: 
+
+
+<!-- ##### FUNCTION lasso_federation_build_local_name_identifier ##### -->
+<para>
+
+</para>
+
+@federation: 
+@nameQualifier: 
+@format: 
+@content: 
+
+
+<!-- ##### FUNCTION lasso_federation_set_local_name_identifier ##### -->
+<para>
+
+</para>
+
+@federation: 
+@name_identifier: 
+
+
+<!-- ##### FUNCTION lasso_federation_set_remote_name_identifier ##### -->
+<para>
+
+</para>
+
+@federation: 
+@name_identifier: 
+
+
+<!-- ##### FUNCTION lasso_federation_verify_name_identifier ##### -->
+<para>
+
+</para>
+
+@federation: 
+@name_identifier: 
+@Returns: 
+<!-- # Unused Parameters # -->
+@nameIdentifier: 
+
+
diff --git a/docs/reference/tmpl/identity.sgml b/docs/reference/tmpl/identity.sgml
new file mode 100644
index 00000000..7b76ace9
--- /dev/null
+++ b/docs/reference/tmpl/identity.sgml
@@ -0,0 +1,97 @@
+<!-- ##### SECTION Title ##### -->
+LassoIdentity
+
+<!-- ##### SECTION Short_Description ##### -->
+Principal Identity
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT LassoIdentity ##### -->
+<para>
+
+</para>
+
+@federations: 
+@is_dirty: 
+
+<!-- ##### STRUCT LassoIdentityClass ##### -->
+<para>
+
+</para>
+
+@parent: 
+
+<!-- ##### FUNCTION lasso_identity_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_identity_new_from_dump ##### -->
+<para>
+
+</para>
+
+@dump: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_identity_destroy ##### -->
+<para>
+
+</para>
+
+@identity: 
+
+
+<!-- ##### FUNCTION lasso_identity_dump ##### -->
+<para>
+
+</para>
+
+@identity: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_identity_add_federation ##### -->
+<para>
+
+</para>
+
+@identity: 
+@federation: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_identity_get_federation ##### -->
+<para>
+
+</para>
+
+@identity: 
+@providerID: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_identity_remove_federation ##### -->
+<para>
+
+</para>
+
+@identity: 
+@providerID: 
+@Returns: 
+<!-- # Unused Parameters # -->
+@remote_providerID: 
+
+
diff --git a/docs/reference/tmpl/session.sgml b/docs/reference/tmpl/session.sgml
new file mode 100644
index 00000000..a02a0043
--- /dev/null
+++ b/docs/reference/tmpl/session.sgml
@@ -0,0 +1,123 @@
+<!-- ##### SECTION Title ##### -->
+LassoSession
+
+<!-- ##### SECTION Short_Description ##### -->
+Principal Session
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT LassoSession ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT LassoSessionClass ##### -->
+<para>
+
+</para>
+
+@parent: 
+
+<!-- ##### FUNCTION lasso_session_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_new_from_dump ##### -->
+<para>
+
+</para>
+
+@dump: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_add_assertion ##### -->
+<para>
+
+</para>
+
+@session: 
+@providerID: 
+@assertion: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_destroy ##### -->
+<para>
+
+</para>
+
+@session: 
+
+
+<!-- ##### FUNCTION lasso_session_dump ##### -->
+<para>
+
+</para>
+
+@session: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_get_assertion ##### -->
+<para>
+
+</para>
+
+@session: 
+@providerID: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_get_authentication_method ##### -->
+<para>
+
+</para>
+
+@session: 
+@providerID: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_get_first_providerID ##### -->
+<para>
+
+</para>
+
+@session: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_get_provider_index ##### -->
+<para>
+
+</para>
+
+@session: 
+@index: 
+@Returns: 
+
+
+<!-- ##### FUNCTION lasso_session_remove_assertion ##### -->
+<para>
+
+</para>
+
+@session: 
+@providerID: 
+@Returns: 
+
+
diff --git a/lasso/id-ff/defederation.c b/lasso/id-ff/defederation.c
index 209a6864..a4a01510 100644
--- a/lasso/id-ff/defederation.c
+++ b/lasso/id-ff/defederation.c
@@ -126,15 +126,16 @@ lasso_defederation_destroy(LassoDefederation *defederation)
 
 /**
  * lasso_defederation_init_notification:
- * @defederation: the federation termination object
+ * @defederation: a #LassoDefederation
  * @remote_providerID: the provider id of the federation termination notified
- * provider.
+ *     provider.
+ * @http_method: the HTTP method to send the message.
  *
- * It sets a new federation termination notification to the remote provider id
- * with the provider id of the requester (from the server object )
- * and the name identifier of the federated principal
+ * Sets a new federation termination notification to the remote provider id
+ * with the provider id of the requester (from the server object) and the name
+ * identifier of the federated principal.
  * 
- * Return value: 0 if OK else < 0
+ * Return value: 0 on success; or a negative value otherwise.
  **/
 gint
 lasso_defederation_init_notification(LassoDefederation *defederation, gchar *remote_providerID,
@@ -386,7 +387,7 @@ lasso_defederation_validate_notification(LassoDefederation *defederation)
 		return critical_error(LASSO_PROFILE_ERROR_FEDERATION_NOT_FOUND);
 	}
 
-	if (lasso_federation_verify_nameIdentifier(federation, nameIdentifier) == FALSE) {
+	if (lasso_federation_verify_name_identifier(federation, nameIdentifier) == FALSE) {
 		return critical_error(LASSO_PROFILE_ERROR_NAME_IDENTIFIER_NOT_FOUND);
 	}
 
@@ -431,7 +432,6 @@ lasso_defederation_get_type()
 /**
  * lasso_defederation_new:
  * @server: the server object of the provider
- * @provider_type: the provider type (service provider or identity provider)
  * 
  * This function build a new federation termination object to build
  * a notification message or to process a notification.
diff --git a/lasso/id-ff/defederation.h b/lasso/id-ff/defederation.h
index 4f13245a..f2f4983b 100644
--- a/lasso/id-ff/defederation.h
+++ b/lasso/id-ff/defederation.h
@@ -65,7 +65,7 @@ LASSO_EXPORT gint lasso_defederation_build_notification_msg(LassoDefederation *d
 LASSO_EXPORT void lasso_defederation_destroy(LassoDefederation *defederation);
 
 LASSO_EXPORT gint lasso_defederation_init_notification(LassoDefederation *defederation,
-		gchar *remote_providerID, lassoHttpMethod notification_method);
+		gchar *remote_providerID, lassoHttpMethod http_method);
 
 LASSO_EXPORT gint lasso_defederation_process_notification_msg(
 		LassoDefederation *defederation, gchar *notification_msg);
diff --git a/lasso/id-ff/federation.c b/lasso/id-ff/federation.c
index 3319e117..06a1d37f 100644
--- a/lasso/id-ff/federation.c
+++ b/lasso/id-ff/federation.c
@@ -35,9 +35,8 @@ struct _LassoFederationPrivate
 /*****************************************************************************/
 
 static LassoSamlNameIdentifier*
-lasso_federation_build_nameIdentifier(const gchar *nameQualifier,
-				      const gchar *format,
-				      const gchar *content)
+lasso_federation_build_name_identifier(const gchar *nameQualifier,
+		const gchar *format, const gchar *content)
 {
 	LassoSamlNameIdentifier *nameIdentifier;
 
@@ -58,16 +57,33 @@ lasso_federation_build_nameIdentifier(const gchar *nameQualifier,
 /* public methods                                                            */
 /*****************************************************************************/
 
+/**
+ * lasso_federation_build_local_name_identifier:
+ * @federation: a #LassoFederation
+ * @nameQualifier: the name identifier qualifier
+ * @format: the name identifier format
+ * @content: the name identifier content
+ *
+ * Builds federation local name identifier.
+ **/
 void
-lasso_federation_build_local_nameIdentifier(LassoFederation *federation,
+lasso_federation_build_local_name_identifier(LassoFederation *federation,
 					    const gchar     *nameQualifier,
 					    const gchar     *format,
 					    const gchar     *content)
 {
-	federation->local_nameIdentifier = lasso_federation_build_nameIdentifier(
+	federation->local_nameIdentifier = lasso_federation_build_name_identifier(
 			nameQualifier, format, content);
 }
 
+/**
+ * lasso_federation_set_local_name_identifier:
+ * @federation: a #LassoFederation
+ * @name_identifier: the #LassoSamlNameIdentifier
+ *
+ * Sets local name identifier to @name_identifier.  Caller keeps ownership of
+ * @name_identifier.
+ **/
 void
 lasso_federation_set_local_name_identifier(LassoFederation *federation,
 		LassoSamlNameIdentifier *name_identifier)
@@ -76,6 +92,15 @@ lasso_federation_set_local_name_identifier(LassoFederation *federation,
 		lasso_node_destroy(LASSO_NODE(federation->local_nameIdentifier));
 	federation->local_nameIdentifier = g_object_ref(name_identifier);
 }
+
+/**
+ * lasso_federation_set_remote_name_identifier:
+ * @federation: a #LassoFederation
+ * @name_identifier: the #LassoSamlNameIdentifier
+ *
+ * Sets remote name identifier to @name_identifier.  Caller keeps ownership of
+ * @name_identifier
+ **/
 void
 lasso_federation_set_remote_name_identifier(LassoFederation *federation,
 		LassoSamlNameIdentifier *name_identifier)
@@ -85,27 +110,42 @@ lasso_federation_set_remote_name_identifier(LassoFederation *federation,
 	federation->remote_nameIdentifier = g_object_ref(name_identifier);
 }
 
+/**
+ * lasso_federation_destroy:
+ * @federation: a #LassoFederation
+ *
+ * Destroys a federation.
+ **/
 void
 lasso_federation_destroy(LassoFederation *federation)
 {
 	lasso_node_destroy(LASSO_NODE(federation));
 }
 
+/**
+ * lasso_federation_verify_name_identifier:
+ * @federation: a #LassoFederation
+ * @name_identifier: the #LassoSamlNameIdentifier
+ *
+ * Checks whether federation is for @name_identifier.
+ *
+ * Return value: %TRUE if the federation is for @name_identifier.
+ **/
 gboolean
-lasso_federation_verify_nameIdentifier(LassoFederation *federation,
-				       LassoSamlNameIdentifier *nameIdentifier)
+lasso_federation_verify_name_identifier(LassoFederation *federation,
+		LassoSamlNameIdentifier *name_identifier)
 {
 	char *s;
-	/* XXX: verify_nameIdentifier only checks content; what about Format
+	/* XXX: verify_name_identifier only checks content; what about Format
 	 * and NameQualifier ? */
 
 	g_return_val_if_fail(LASSO_IS_FEDERATION(federation), FALSE);
-	g_return_val_if_fail(LASSO_IS_NODE(nameIdentifier), FALSE);
+	g_return_val_if_fail(LASSO_IS_NODE(name_identifier), FALSE);
 
 	/* verify local name identifier */
 	if (federation->local_nameIdentifier != NULL) {
 		s = federation->local_nameIdentifier->content;
-		if (strcmp(s, nameIdentifier->content) == 0) {
+		if (strcmp(s, name_identifier->content) == 0) {
 			return TRUE;
 		}
 	}
@@ -113,7 +153,7 @@ lasso_federation_verify_nameIdentifier(LassoFederation *federation,
 	/* verify remote name identifier */
 	if (federation->remote_nameIdentifier != NULL) {
 		s = federation->remote_nameIdentifier->content;
-		if (strcmp(s, nameIdentifier->content) == 0) {
+		if (strcmp(s, name_identifier->content) == 0) {
 			return TRUE;
 		}
 	}
@@ -239,6 +279,14 @@ lasso_federation_get_type()
 	return this_type;
 }
 
+/**
+ * lasso_federation_new:
+ * @remote_providerID: remote Provider ID
+ *
+ * Creates a new #LassoFederation with the remote provider.
+ *
+ * Return value: a newly created #LassoFederation
+ **/
 LassoFederation*
 lasso_federation_new(gchar *remote_providerID)
 {
@@ -251,4 +299,3 @@ lasso_federation_new(gchar *remote_providerID)
 
 	return federation;
 }
-
diff --git a/lasso/id-ff/federation.h b/lasso/id-ff/federation.h
index 1b8d51fa..35aaa3f1 100644
--- a/lasso/id-ff/federation.h
+++ b/lasso/id-ff/federation.h
@@ -51,11 +51,12 @@ typedef struct _LassoFederationPrivate LassoFederationPrivate;
 struct _LassoFederation {
 	LassoNode parent;
 
+	/*< public >*/
 	gchar *remote_providerID;
-
 	LassoSamlNameIdentifier *local_nameIdentifier;
 	LassoSamlNameIdentifier *remote_nameIdentifier;
 
+	/*< private >*/
 	LassoFederationPrivate *private_data;
 };
 
@@ -67,7 +68,7 @@ LASSO_EXPORT GType lasso_federation_get_type(void);
 
 LASSO_EXPORT LassoFederation* lasso_federation_new(gchar *remote_providerID);
 
-LASSO_EXPORT void lasso_federation_build_local_nameIdentifier(LassoFederation *federation,
+LASSO_EXPORT void lasso_federation_build_local_name_identifier(LassoFederation *federation,
 		const gchar *nameQualifier, const gchar *format, const gchar *content);
 
 LASSO_EXPORT void lasso_federation_set_local_name_identifier(LassoFederation *federation,
@@ -77,8 +78,8 @@ LASSO_EXPORT void lasso_federation_set_remote_name_identifier(LassoFederation *f
 
 LASSO_EXPORT void lasso_federation_destroy(LassoFederation *federation);
 
-LASSO_EXPORT gboolean lasso_federation_verify_nameIdentifier(
-		LassoFederation *federation, LassoSamlNameIdentifier *nameIdentifier);
+LASSO_EXPORT gboolean lasso_federation_verify_name_identifier(
+		LassoFederation *federation, LassoSamlNameIdentifier *name_identifier);
 
 #ifdef __cplusplus
 }
diff --git a/lasso/id-ff/identity.c b/lasso/id-ff/identity.c
index 8e0e91e4..98cf5eca 100644
--- a/lasso/id-ff/identity.c
+++ b/lasso/id-ff/identity.c
@@ -34,6 +34,15 @@ struct _LassoIdentityPrivate
 /* public methods                                                            */
 /*****************************************************************************/
 
+/**
+ * lasso_identity_add_federation:
+ * @identity: a #LassoIdentity
+ * @federation: the #LassoFederation
+ *
+ * Adds @federation as a known federation for @identity.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_identity_add_federation(LassoIdentity *identity, LassoFederation *federation)
 {
@@ -48,16 +57,36 @@ lasso_identity_add_federation(LassoIdentity *identity, LassoFederation *federati
 	return 0;
 }
 
+/**
+ * lasso_identity_get_federation:
+ * @identity: a #LassoIdentity
+ * @providerID: the provider ID
+ *
+ * Looks up and returns the #LassoFederation for this provider ID.
+ *
+ * Return value: the #LassoFederation; or NULL if it didn't exist.  The
+ *      #LassoFederation is internally allocated.  It must not be freed,
+ *      modified or stored.
+ **/
 LassoFederation*
-lasso_identity_get_federation(LassoIdentity *identity, gchar *providerID)
+lasso_identity_get_federation(LassoIdentity *identity, const char *providerID)
 {
 	return g_hash_table_lookup(identity->federations, providerID);
 }
 
+/**
+ * lasso_identity_remove_federation:
+ * @identity: a #LassoIdentity
+ * @providerID: the provider ID
+ *
+ * Remove federation between identity and provider with @providerID
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
-lasso_identity_remove_federation(LassoIdentity *identity, char *remote_providerID)
+lasso_identity_remove_federation(LassoIdentity *identity, const char *providerID)
 {
-	if (g_hash_table_remove(identity->federations, remote_providerID) == FALSE) {
+	if (g_hash_table_remove(identity->federations, providerID) == FALSE) {
 		debug("Failed to remove federation for remote Provider %s", remote_providerID);
 		return LASSO_ERROR_UNDEFINED;
 	}
@@ -65,6 +94,12 @@ lasso_identity_remove_federation(LassoIdentity *identity, char *remote_providerI
 	return 0;
 }
 
+/**
+ * lasso_identity_destroy:
+ * @identity: a #LassoIdentity
+ *
+ * Destroys an identity.
+ **/
 void
 lasso_identity_destroy(LassoIdentity *identity)
 {
@@ -212,12 +247,27 @@ lasso_identity_get_type()
 	return this_type;
 }
 
+/**
+ * lasso_identity_new:
+ *
+ * Creates a new #LassoIdentity.
+ *
+ * Return value: a newly created #LassoIdentity
+ **/
 LassoIdentity*
 lasso_identity_new()
 {
 	return g_object_new(LASSO_TYPE_IDENTITY, NULL);
 }
 
+/**
+ * lasso_identity_new_from_dump:
+ * @dump: XML server dump
+ *
+ * Restores the @dump to a new #LassoIdentity.
+ *
+ * Return value: a newly created #LassoIdentity; or NULL if an error occured
+ **/
 LassoIdentity*
 lasso_identity_new_from_dump(const gchar *dump)
 {
@@ -232,6 +282,14 @@ lasso_identity_new_from_dump(const gchar *dump)
 	return identity;
 }
 
+/**
+ * lasso_identity_dump:
+ * @identity: a #LassoIdentity
+ *
+ * Dumps @identity content to an XML string.
+ *
+ * Return value: the dump string.  It must be freed by the caller.
+ **/
 gchar*
 lasso_identity_dump(LassoIdentity *identity)
 {
@@ -240,4 +298,3 @@ lasso_identity_dump(LassoIdentity *identity)
 
 	return lasso_node_dump(LASSO_NODE(identity), NULL, 1);
 }
-
diff --git a/lasso/id-ff/identity.h b/lasso/id-ff/identity.h
index 0985897d..8c8f2bf4 100644
--- a/lasso/id-ff/identity.h
+++ b/lasso/id-ff/identity.h
@@ -49,9 +49,11 @@ typedef struct _LassoIdentityPrivate LassoIdentityPrivate;
 struct _LassoIdentity {
 	LassoNode parent;
 
+	/*< public >*/
 	GHashTable *federations; /* hash for federations with remote ProviderID as key */
 	gboolean is_dirty;
 
+	/*< private >*/
 	LassoIdentityPrivate *private_data;
 };
 
@@ -61,18 +63,18 @@ struct _LassoIdentityClass {
 
 LASSO_EXPORT GType lasso_identity_get_type(void);
 LASSO_EXPORT LassoIdentity* lasso_identity_new(void);
+LASSO_EXPORT LassoIdentity* lasso_identity_new_from_dump(const gchar *dump);
 
 LASSO_EXPORT gint lasso_identity_add_federation(LassoIdentity *identity,
 		LassoFederation *federation);
 LASSO_EXPORT LassoFederation* lasso_identity_get_federation(
-		LassoIdentity *identity, gchar *providerID);
+		LassoIdentity *identity, const char *providerID);
 LASSO_EXPORT gint lasso_identity_remove_federation(LassoIdentity *identity,
-		char *remote_providerID);
+		const char *providerID);
 
 LASSO_EXPORT void lasso_identity_destroy(LassoIdentity *identity);
 
 LASSO_EXPORT gchar* lasso_identity_dump(LassoIdentity *identity);
-LASSO_EXPORT LassoIdentity* lasso_identity_new_from_dump(const gchar *dump);
 
 #ifdef __cplusplus
 }
diff --git a/lasso/id-ff/login.c b/lasso/id-ff/login.c
index df7a9c52..995589c7 100644
--- a/lasso/id-ff/login.c
+++ b/lasso/id-ff/login.c
@@ -292,7 +292,7 @@ lasso_login_process_federation(LassoLogin *login, gboolean is_consent_obtained)
 
 	if (federation == NULL) {
 		federation = lasso_federation_new(LASSO_PROFILE(login)->remote_providerID);
-		lasso_federation_build_local_nameIdentifier(federation,
+		lasso_federation_build_local_name_identifier(federation,
 				LASSO_PROVIDER(LASSO_PROFILE(login)->server)->ProviderID,
 				LASSO_LIB_NAME_IDENTIFIER_FORMAT_FEDERATED,
 				NULL);
@@ -516,15 +516,11 @@ lasso_login_build_artifact_msg(LassoLogin *login, lassoHttpMethod http_method)
 /**
  * lasso_login_build_authn_request_msg:
  * @login: a LassoLogin
- * @remote_providerID: the providerID of the identity provider or NULL
  * 
  * Builds an authentication request. Depending of the selected HTTP method,
  * the data for the sending of the request are stored in msg_url (GET) or
  * msg_url and msg_body (POST).
  * 
- * If remote_providerID is NULL, the providerID of the first provider
- * of server is used.
- *
  * Return value: 0 on success and a negative value otherwise.
  **/
 gint
@@ -690,6 +686,7 @@ lasso_login_build_request_msg(LassoLogin *login)
 /**
  * lasso_login_build_response_msg:
  * @login: a LassoLogin
+ * @remote_providerID: the providerID of the session provider
  * 
  * Builds a SOAP response message. The data for the sending of the response
  * are stored in msg_body.
@@ -755,7 +752,7 @@ lasso_login_build_response_msg(LassoLogin *login, gchar *remote_providerID)
 
 /**
  * lasso_login_destroy:
- * @login: a LassoLogin
+ * @login: a #LassoLogin
  * 
  * Destroys LassoLogin objects created with lasso_login_new() or lasso_login_new_from_dump().
  **/
@@ -1299,7 +1296,7 @@ lasso_login_get_type()
 
 /**
  * lasso_login_new
- * @server: a #LassoServer
+ * @server: the #LassoServer
  *
  * Creates a new #LassoLogin.
  *
@@ -1321,6 +1318,7 @@ lasso_login_new(LassoServer *server)
 
 /**
  * lasso_login_new_from_dump:
+ * @server: the #LassoServer
  * @dump: XML login dump
  *
  * Restores the @dump to a new #LassoLogin.
diff --git a/lasso/id-ff/logout.c b/lasso/id-ff/logout.c
index c93adf5b..5c211c2d 100644
--- a/lasso/id-ff/logout.c
+++ b/lasso/id-ff/logout.c
@@ -730,7 +730,7 @@ lasso_logout_validate_request(LassoLogout *logout)
 			return critical_error(LASSO_PROFILE_ERROR_FEDERATION_NOT_FOUND);
 		}
 
-		if (lasso_federation_verify_nameIdentifier(federation, nameIdentifier) == FALSE) {
+		if (lasso_federation_verify_name_identifier(federation, nameIdentifier) == FALSE) {
 			message(G_LOG_LEVEL_WARNING, "No name identifier for %s",
 					profile->remote_providerID);
 			lasso_profile_set_response_status(profile,
@@ -936,7 +936,6 @@ lasso_logout_get_type()
 /**
  * lasso_logout_new:
  * @server: the logout object
- * @provider_type: the provider type (service provider or identity provider)
  * 
  * initialises a new logout object
  * 
diff --git a/lasso/id-ff/name_registration.c b/lasso/id-ff/name_registration.c
index 65b75156..693b2af0 100644
--- a/lasso/id-ff/name_registration.c
+++ b/lasso/id-ff/name_registration.c
@@ -486,7 +486,7 @@ lasso_name_registration_validate_request(LassoNameRegistration *name_registratio
 		return LASSO_ERROR_UNDEFINED;
 	}
 
-	if (lasso_federation_verify_nameIdentifier(federation,
+	if (lasso_federation_verify_name_identifier(federation,
 				request->OldProvidedNameIdentifier) == FALSE) {
 		message(G_LOG_LEVEL_CRITICAL, "No name identifier");
 		return LASSO_ERROR_UNDEFINED;
diff --git a/lasso/id-ff/server.c b/lasso/id-ff/server.c
index d924dbd4..168002dc 100644
--- a/lasso/id-ff/server.c
+++ b/lasso/id-ff/server.c
@@ -93,7 +93,7 @@ lasso_server_add_service(LassoServer *server,
 }
 
 /**
- * lasso_server_destroy
+ * lasso_server_destroy:
  * @server: a #LassoServer
  *
  * Destroys a server.