done with documenting if-ff/* functions

6 files changed, 100 insertions, 24 deletions

diff --git a/lasso/id-ff/defederation.c b/lasso/id-ff/defederation.c
index 3b815b2f..2832b82c 100644
--- a/lasso/id-ff/defederation.c
+++ b/lasso/id-ff/defederation.c
@@ -42,16 +42,16 @@
  * <itemizedlist>
  * <listitem><para>
  *   if it is a SOAP method, then it builds the federation termination
- *   notification SOAP message, optionally signs the notification node, set the
- *   msg_body attribute, gets the SoapEndpoint url and set the msg_url
- *   attribute of the federation termination object.
+ *   notification SOAP message, optionally signs the notification node, sets
+ *   @msg_body, gets the SoapEndpoint url and sets @msg_url of the federation
+ *   termination object.
  * </para></listitem>
  * <listitem><para>
  *   if it is a HTTP-Redirect method, then it builds the federation termination
  *   notification QUERY message (optionally signs the notification message),
  *   builds the federation termination notification url with federation
- *   termination service url, set the msg_url attribute of the federation
- *   termination object, set the msg_body to NULL
+ *   termination service url, sets @msg_url in the federation termination
+ *   object, sets @msg_body to NULL.
  * </para></listitem>
  * </itemizedlist>
  * 
diff --git a/lasso/id-ff/lecp.c b/lasso/id-ff/lecp.c
index daf25a48..6b70ec38 100644
--- a/lasso/id-ff/lecp.c
+++ b/lasso/id-ff/lecp.c
@@ -32,6 +32,16 @@
 /* public methods                                                            */
 /*****************************************************************************/
 
+
+/**
+ * lasso_lecp_build_authn_request_envelope_msg:
+ * @lecp: a #LassoLecp
+ *
+ * Builds an enveloped authentication request message.  Sets @msg_body to that
+ * message.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_lecp_build_authn_request_envelope_msg(LassoLecp *lecp)
 {
@@ -91,12 +101,12 @@ lasso_lecp_build_authn_request_envelope_msg(LassoLecp *lecp)
 
 /**
  * lasso_lecp_build_authn_request_msg:
- * @lecp: a LassoLecp
+ * @lecp: a #LassoLecp
  * 
  * Builds an authentication request. The data for the sending of the request are
- * stored in msg_url and msg_body (SOAP POST).
+ * stored in @msg_url and @msg_body (SOAP POST).
  * 
- * Return value: 0 on success and a negative value otherwise.
+ * Return value: 0 on success; or a negative value otherwise.
  **/
 int
 lasso_lecp_build_authn_request_msg(LassoLecp *lecp)
@@ -121,6 +131,16 @@ lasso_lecp_build_authn_request_msg(LassoLecp *lecp)
 	return 0;
 }
 
+
+/**
+ * lasso_lecp_build_authn_response_msg:
+ * @lecp: a #LassoLecp
+ *
+ * Builds the lecp authentication response message (base64).  Sets @msg_body to
+ * that message.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 int
 lasso_lecp_build_authn_response_msg(LassoLecp *lecp)
 {
@@ -141,6 +161,16 @@ lasso_lecp_build_authn_response_msg(LassoLecp *lecp)
 	return 0;
 }
 
+
+/**
+ * lasso_lecp_build_authn_response_envelope_msg:
+ * @lecp: a #LassoLecp
+ *
+ * Builds the enveloped LECP authentication response message (SOAP message).
+ * Sets @msg_body to that message.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_lecp_build_authn_response_envelope_msg(LassoLecp *lecp)
 {
@@ -177,6 +207,7 @@ lasso_lecp_build_authn_response_envelope_msg(LassoLecp *lecp)
 
 	if (LASSO_PROFILE(lecp)->msg_url)
 		g_free(LASSO_PROFILE(lecp)->msg_url);
+	LASSO_PROFILE(lecp)->msg_url = NULL;
 
 	lecp->authnResponseEnvelope = lasso_lib_authn_response_envelope_new(
 			LASSO_LIB_AUTHN_RESPONSE(profile->response),
@@ -220,6 +251,17 @@ lasso_lecp_init_authn_request(LassoLecp *lecp, const char *remote_providerID)
 	return res;
 }
 
+
+/**
+ * lasso_lecp_process_authn_request_msg:
+ * @lecp: a #LassoLecp
+ * @authn_request_msg: the authentication request received
+ *
+ * Processes received authentication request, checks it is signed correctly,
+ * checks if requested protocol profile is supported, etc.
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 int
 lasso_lecp_process_authn_request_msg(LassoLecp *lecp, const char *authn_request_msg)
 {
@@ -229,6 +271,17 @@ lasso_lecp_process_authn_request_msg(LassoLecp *lecp, const char *authn_request_
 	return lasso_login_process_authn_request_msg(LASSO_LOGIN(lecp), authn_request_msg);
 }
 
+
+/**
+ * lasso_lecp_process_authn_request_envelope_msg:
+ * @lecp: a #LassoLecp
+ * @request_msg: the enveloped authentication request received
+ *
+ * Processes received enveloped authentication request, extracts the
+ * authentication request out of it.
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 int
 lasso_lecp_process_authn_request_envelope_msg(LassoLecp *lecp, const char *request_msg)
 {
@@ -278,6 +331,17 @@ lasso_lecp_process_authn_request_envelope_msg(LassoLecp *lecp, const char *reque
 	return 0;
 }
 
+
+/**
+ * lasso_lecp_process_authn_response_envelope_msg:
+ * @lecp: a #LassoLecp
+ * @response_msg: the enveloped authentication response received
+ *
+ * Processes received enveloped authentication response, extracts the
+ * authentication response out of it and stores it in @response.
+ * 
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 int
 lasso_lecp_process_authn_response_envelope_msg(LassoLecp *lecp, const char *response_msg)
 {
diff --git a/lasso/id-ff/login.c b/lasso/id-ff/login.c
index 8534f651..81c7eaa1 100644
--- a/lasso/id-ff/login.c
+++ b/lasso/id-ff/login.c
@@ -434,8 +434,8 @@ lasso_login_accept_sso(LassoLogin *login)
  * @http_method: the HTTP method to send the artifact (REDIRECT or POST)
  * 
  * Builds a SAML artifact. Depending of the HTTP method, the data for the sending of
- * the artifact are stored in msg_url (REDIRECT) or msg_url, msg_body and
- * msg_relayState (POST).
+ * the artifact are stored in @msg_url (REDIRECT) or @msg_url, @msg_body and
+ * @msg_relayState (POST).
  *
  * Return value: 0 on success; or a negative value otherwise.
  **/
diff --git a/lasso/id-ff/logout.c b/lasso/id-ff/logout.c
index 8a8fe201..9e0f99b9 100644
--- a/lasso/id-ff/logout.c
+++ b/lasso/id-ff/logout.c
@@ -52,12 +52,12 @@ static void check_soap_support(gchar *key, LassoProvider *provider, LassoProfile
  * <listitem><para>
  *   if it is a SOAP method, then it builds the logout request SOAP message,
  *   sets the msg_body attribute, gets the single logout service url and sets
- *   the msg_url attribute of the logout object.
+ *   @msg_url in the logout object.
  * </para></listitem>
  * <listitem><para>
  *   if it is a HTTP-Redirect method, then it builds the logout request QUERY
- *   message, builds the logout request url, sets the msg_url to the logout
- *   request url, sets the msg_body to NULL.
+ *   message, builds the logout request url, sets @msg_url in the logout
+ *   request url, sets @msg_body to NULL.
  * </para></listitem>
  * </itemizedlist>
  *
@@ -134,12 +134,12 @@ lasso_logout_build_request_msg(LassoLogout *logout)
  * <listitem><para>
  *    if it is a SOAP method, then it builds the logout response SOAP message,
  *    sets the msg_body attribute, gets the single logout service return url
- *    and sets the msg_url attribute of the logout object.
+ *    and sets @msg_url in the logout object.
  * </para></listitem>
  * <listitem><para>
  *    if it is a HTTP-Redirect method, then it builds the logout response QUERY message,
- *    builds the logout response url, sets the msg_url with the logout response url,
- *    sets the msg_body with NULL
+ *    builds the logout response url, sets @msg_url with the logout response url,
+ *    sets @msg_body to NULL
  * </para></listitem>
  * </itemizedlist>
  *
diff --git a/lasso/id-ff/name_registration.c b/lasso/id-ff/name_registration.c
index 75dc3920..255079c5 100644
--- a/lasso/id-ff/name_registration.c
+++ b/lasso/id-ff/name_registration.c
@@ -41,15 +41,15 @@
  * <itemizedlist>
  * <listitem><para>
  *   if it is a SOAP method, then it builds the register name identifier
- *   request SOAP message, optionally signs his node, set the msg_body
- *   attribute, gets the SoapEndpoint url and set the msg_url attribute.
+ *   request SOAP message, optionally signs his node, sets @msg_body,
+ *   gets the SoapEndpoint url and sets @msg_url.
  * </para></listitem>
  * <listitem><para>
  *   if it is a HTTP-Redirect method, then it builds the register name
  *   identifier request QUERY message (optionally signs the request message),
  *   builds the request url with register name identifier url with register
- *   name identifier service url, set the msg_url attribute of the register
- *   name identifier object, set the msg_body to NULL.
+ *   name identifier service url, sets @msg_url in the register name
+ *   identifier object, sets @msg_body to NULL.
  * </para></listitem>
  * </itemizedlist>
  * 
@@ -120,11 +120,11 @@ lasso_name_registration_build_request_msg(LassoNameRegistration *name_registrati
  * <listitem><para>
  *    if it is a SOAP method, then it builds the response SOAP message, sets
  *    the msg_body attribute, gets the register name identifier service return
- *    url and sets the msg_url attribute of the object.
+ *    url and sets @msg_url of the object.
  * </para></listitem>
  * <listitem><para>
  *    if it is a HTTP-Redirect method, then it builds the response QUERY
- *    message, builds the response url, sets the msg_url with the response url
+ *    message, builds the response url, sets @msg_url with the response url
  *    and sets the msg_body with NULL
  * </para></listitem>
  * </itemizedlist>
diff --git a/lasso/id-ff/profile.c b/lasso/id-ff/profile.c
index f55edd26..bcb23f0c 100644
--- a/lasso/id-ff/profile.c
+++ b/lasso/id-ff/profile.c
@@ -43,6 +43,18 @@ struct _LassoProfilePrivate
 /* public functions                                                          */
 /*****************************************************************************/
 
+
+/**
+ * lasso_profile_get_nameIdentifier:
+ * @profile: a #LassoProifle
+ *
+ * Looks up appropriate federation in object and gets the service provider name
+ * identifier.
+ *
+ * Return value: the name identifier or NULL if none was found.  The
+ *     #LassoSamlNameIdentifier object is internally allocated and must not be
+ *     freed by the caller.
+ **/
 LassoSamlNameIdentifier*
 lasso_profile_get_nameIdentifier(LassoProfile *profile)
 {
@@ -173,7 +185,7 @@ lasso_profile_is_liberty_query(const gchar *query)
  *
  * Gets the identity bound to @profile.
  *
- * Return value: the identity or NULL if it none was bound.  The #LassoIdentity
+ * Return value: the identity or NULL if it none was found.  The #LassoIdentity
  *      object is internally allocated and must not be freed by the caller.
  **/
 LassoIdentity*
@@ -191,7 +203,7 @@ lasso_profile_get_identity(LassoProfile *profile)
  *
  * Gets the session bound to @profile.
  *
- * Return value: the session or NULL if it none was bound.  The #LassoSession
+ * Return value: the session or NULL if it none was found.  The #LassoSession
  *      object is internally allocated and must not be freed by the caller.
  **/
 LassoSession*