added documentation for id-wsf 2.0 functions

5 files changed, 329 insertions, 22 deletions

diff --git a/lasso/id-wsf-2.0/data_service.c b/lasso/id-wsf-2.0/data_service.c
index 734ba5ff..f6dbeb2c 100644
--- a/lasso/id-wsf-2.0/data_service.c
+++ b/lasso/id-wsf-2.0/data_service.c
@@ -22,6 +22,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * SECTION:idwsf2_data_service
+ * @short_description: ID-WSF 2.0 Data Service profile
+ *
+ * DataService allows Attribute Consumers (WSC) to request an Attribute Provider (WSP) to get
+ * or modify data about users with their consent.
+ */
+
 #include <libxml/xpath.h>
 #include <libxml/xpathInternals.h>
 
@@ -58,6 +66,14 @@ static GList* duplicate_glist_of_xmlnodes(GList*);
 /* public methods                                                            */
 /*****************************************************************************/
 
+/**
+ * lasso_idwsf2_data_service_init_query:
+ * @service: a #LassoIdWsf2DataService
+ *
+ * Initialise an ID-WSF 2.0 DataService query request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_init_query(LassoIdWsf2DataService *service)
 {
@@ -118,6 +134,16 @@ lasso_idwsf2_data_service_init_query(LassoIdWsf2DataService *service)
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_data_service_add_query_item:
+ * @service: a #LassoIdWsf2DataService
+ * @item_xpath: XPATH of the queried item
+ * @item_id: identifier of the queried item, which will allow to retrieve it in the response
+ *
+ * Add an item in the query request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_add_query_item(LassoIdWsf2DataService *service, const gchar *item_xpath,
 	const gchar *item_id)
@@ -143,6 +169,16 @@ lasso_idwsf2_data_service_add_query_item(LassoIdWsf2DataService *service, const
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_data_service_process_query_msg:
+ * @service: a #LassoIdWsf2DataService
+ * @message: received query soap request
+ *
+ * Process received query request.
+ * Parse query items and put the list of queried XPATH into @service->query_items.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_process_query_msg(LassoIdWsf2DataService *service, const gchar *message)
 {
@@ -179,6 +215,16 @@ lasso_idwsf2_data_service_process_query_msg(LassoIdWsf2DataService *service, con
 	return res;
 }
 
+/**
+ * lasso_idwsf2_data_service_parse_query_items:
+ * @service: a #LassoIdWsf2DataService
+ *
+ * Parse query items and user data from @service->data and fill response->Data accordingly.
+ * Set response status code to OK is all items were parsed correctly, FAILED if no item was parsed
+ * correctly, or PARTIAL if some items were parsed corretly and some others not.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_parse_query_items(LassoIdWsf2DataService *service)
 {
@@ -267,7 +313,7 @@ lasso_idwsf2_data_service_parse_query_items(LassoIdWsf2DataService *service)
 				xmlXPathFreeObject(xpathObj);
 				xpathObj = NULL;
 			}
-			/* Stop processing at first error */
+			/* Stop processing at first error, according to the specifications */
 			break;
 		}
 
@@ -337,6 +383,17 @@ lasso_idwsf2_data_service_process_query_response_soap_fault_msg(LassoIdWsf2DataS
 	return res;
 }
 
+/**
+ * lasso_idwsf2_data_service_process_query_response_msg:
+ * @service: a #LassoIdWsf2DataService
+ * @message: received query soap response
+ *
+ * Process received query response.
+ * Check if the response if a normal response or a soap fault.
+ * Check response status code.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_process_query_response_msg(LassoIdWsf2DataService *service,
 	const gchar *message)
@@ -378,7 +435,15 @@ lasso_idwsf2_data_service_process_query_response_msg(LassoIdWsf2DataService *ser
 	return 0;
 }
 
-
+/**
+ * lasso_idwsf2_data_service_get_attribute_nodes:
+ * @service: a #LassoIdWsf2DataService
+ * @item_id: identifier of the item to retrieve
+ *
+ * Get one of several items for specified @item_id and return them raw as a list of xmlnodes.
+ *
+ * Return value: a list of xmlnodes; or NULL if no item with the specified @item_id was found.
+ **/
 GList*
 lasso_idwsf2_data_service_get_attribute_nodes(LassoIdWsf2DataService *service,
 	const gchar *item_id)
@@ -425,6 +490,15 @@ lasso_idwsf2_data_service_get_attribute_nodes(LassoIdWsf2DataService *service,
 	return duplicate_glist_of_xmlnodes(data->any);
 }
 
+/**
+ * lasso_idwsf2_data_service_get_attribute_node:
+ * @service: a #LassoIdWsf2DataService
+ * @item_id: identifier of the item to retrieve
+ *
+ * Get one item for specified @item_id and return it raw as an xmlnode.
+ *
+ * Return value: an xmlnode; or NULL if no item with the specified @item_id was found.
+ **/
 xmlNode*
 lasso_idwsf2_data_service_get_attribute_node(LassoIdWsf2DataService *service, const gchar *item_id)
 {
@@ -471,6 +545,15 @@ lasso_idwsf2_data_service_get_attribute_node(LassoIdWsf2DataService *service, co
 	return xmlCopyNode(data->any->data, 1);
 }
 
+/**
+ * lasso_idwsf2_data_service_get_attribute_strings:
+ * @service: a #LassoIdWsf2DataService
+ * @item_id: identifier of the item to retrieve
+ *
+ * Get one of several items for specified @item_id and return their content as a list of strings.
+ *
+ * Return value: a list of strings; or NULL if no item with the specified @item_id was found.
+ **/
 GList*
 lasso_idwsf2_data_service_get_attribute_strings(LassoIdWsf2DataService *service,
 	const gchar *item_id)
@@ -495,6 +578,15 @@ lasso_idwsf2_data_service_get_attribute_strings(LassoIdWsf2DataService *service,
 	return contents;
 }
 
+/**
+ * lasso_idwsf2_data_service_get_attribute_string:
+ * @service: a #LassoIdWsf2DataService
+ * @item_id: identifier of the item to retrieve
+ *
+ * Get one item for specified @item_id and return its content as a string.
+ *
+ * Return value: a string; or NULL if no item with the specified @item_id was found.
+ **/
 gchar*
 lasso_idwsf2_data_service_get_attribute_string(LassoIdWsf2DataService *service,
 	const gchar *item_id)
@@ -515,6 +607,15 @@ lasso_idwsf2_data_service_get_attribute_string(LassoIdWsf2DataService *service,
 	return content;
 }
 
+/**
+ * lasso_idwsf2_data_service_init_redirect_user_for_consent:
+ * @service: a #LassoIdWsf2DataService
+ * @redirect_url: URL to ask for redirection
+ *
+ * Initialise a soap fault response to ask the requesting service to redirect to the @redirect_url.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_init_redirect_user_for_consent(LassoIdWsf2DataService *service,
 	const gchar *redirect_url)
@@ -549,6 +650,14 @@ lasso_idwsf2_data_service_init_redirect_user_for_consent(LassoIdWsf2DataService
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_data_service_init_modify:
+ * @service: a #LassoIdWsf2DataService
+ *
+ * Initialise an ID-WSF 2.0 DataService modify request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_init_modify(LassoIdWsf2DataService *service)
 {
@@ -624,6 +733,19 @@ static void set_xml_string(xmlNode **xmlnode, const char* string)
 	*xmlnode = node;
 }
 
+/**
+ * lasso_idwsf2_data_service_add_modify_item:
+ * @service: a #LassoIdWsf2DataService
+ * @item_xpath: XPATH of the item to modify
+ * @item_id: identifier of the item to modify
+ * @new_data: new value for the selected item
+ * @overrideAllowed: FALSE means only allowing to create a new item, but not modify existing one,
+ *                   TRUE means allowing to modify existing item
+ *
+ * Add an item in the modification request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_add_modify_item(LassoIdWsf2DataService *service, const gchar *item_xpath,
 	const gchar *item_id, const gchar *new_data, gboolean overrideAllowed)
@@ -652,6 +774,15 @@ lasso_idwsf2_data_service_add_modify_item(LassoIdWsf2DataService *service, const
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_data_service_process_modify_msg:
+ * @service: a #LassoIdWsf2DataService
+ * @message: received modify soap request
+ *
+ * Process received modify request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_process_modify_msg(LassoIdWsf2DataService *service, const gchar *message)
 {
@@ -728,6 +859,14 @@ lasso_idwsf2_data_service_parse_one_modify_item(LassoIdWsf2DstRefModifyItem *ite
 	return res;
 }
 
+/**
+ * lasso_idwsf2_data_service_parse_modify_items:
+ * @service: a #LassoIdWsf2DataService
+ *
+ * Parse modify items and modify @service->data accordingly.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_parse_modify_items(LassoIdWsf2DataService *service)
 {
@@ -813,6 +952,16 @@ lasso_idwsf2_data_service_parse_modify_items(LassoIdWsf2DataService *service)
 	return res;
 }
 
+/**
+ * lasso_idwsf2_data_service_process_modify_response_msg:
+ * @service: a #LassoIdWsf2DataService
+ * @message: received modify soap response
+ *
+ * Process received modify response.
+ * Check response status code.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_data_service_process_modify_response_msg(LassoIdWsf2DataService *service,
 	const gchar *message)
@@ -975,8 +1124,9 @@ lasso_idwsf2_data_service_get_type()
 
 /**
  * lasso_idwsf2_data_service_new:
+ * @server: the #LassoServer
  *
- * Creates a new #LassoIdWsf2DataService.
+ * Create a new #LassoIdWsf2DataService.
  *
  * Return value: a newly created #LassoIdWsf2DataService object
  **/
@@ -994,6 +1144,15 @@ lasso_idwsf2_data_service_new(LassoServer *server)
 	return service;
 }
 
+/**
+ * lasso_idwsf2_data_service_new_full:
+ * @server: the #LassoServer
+ * @epr: the #LassoWsAddrEndpointReference
+ *
+ * Create a new #LassoIdWsf2DataService.
+ *
+ * Return value: a newly created #LassoIdWsf2DataService object; or NULL if an error occured.
+ **/
 LassoIdWsf2DataService*
 lasso_idwsf2_data_service_new_full(LassoServer *server, LassoWsAddrEndpointReference *epr)
 {
diff --git a/lasso/id-wsf-2.0/discovery.c b/lasso/id-wsf-2.0/discovery.c
index a6579bc8..ac43b309 100644
--- a/lasso/id-wsf-2.0/discovery.c
+++ b/lasso/id-wsf-2.0/discovery.c
@@ -22,6 +22,16 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/**
+ * SECTION:idwsf2_discovery
+ * @short_description: ID-WSF 2.0 Discovery Service profile
+ *
+ * The Discovery service usually runs on the principal identity provider and
+ * knowns about resources and services related to the principal.  Attribute
+ * providers can register themselves as offering resources for an user while
+ * other services can ask where to find a given resource.
+ */
+
 #include <libxml/xpath.h>
 #include <libxml/xpathInternals.h>
 
@@ -72,8 +82,20 @@ struct _LassoIdWsf2DiscoveryPrivate
 /* public methods */
 /*****************************************************************************/
 
-
-/* XXX: return value must be freed by caller */
+/**
+ * lasso_idwsf2_discovery_metadata_register_self:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @service_type: the service type of the registered metadata, for example LASSO_IDWSF2_DISCO_HREF
+ * @abstract: label/title of the service, free form
+ * @soap_endpoint: URL of the SoapEndpoint to the service
+ * @svcMDID: identifier of the metadatas if caller wants to specify which identifier it wants.
+ *           If NULL, a random identifier will be generated.
+ *
+ * Register metadata service on itself as an ID-WSF Provider (WSP).
+ * Typically used for an IdP to register itself as Discovery service.
+ * 
+ * Return value: the svcMDID of the registered service metadata.
+ **/
 gchar*
 lasso_idwsf2_discovery_metadata_register_self(LassoIdWsf2Discovery *discovery,
 	const gchar *service_type, const gchar *abstract,
@@ -115,6 +137,19 @@ lasso_idwsf2_discovery_metadata_register_self(LassoIdWsf2Discovery *discovery,
 	return new_svcMDID;
 }
 
+/**
+ * lasso_idwsf2_discovery_init_metadata_register:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @service_type: the service type of the registered metadata, for example LASSO_IDWSF2_DISCO_HREF
+ * @abstract: label/title of the service, free form
+ * @disco_provider_id: provider identifier of the discovery service
+ * @soap_endpoint: URL of the SoapEndpoint to the service
+ *
+ * Initialise a ID-WSF service metadata registration request to a Discovery service
+ * specified by disco_provider_id.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_init_metadata_register(LassoIdWsf2Discovery *discovery,
 	const gchar *service_type, const gchar *abstract,
@@ -154,6 +189,16 @@ lasso_idwsf2_discovery_init_metadata_register(LassoIdWsf2Discovery *discovery,
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_discovery_process_metadata_register_msg:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @message: received metadata register soap request
+ *
+ * Process received metadata register request.
+ * If successful, register the service metadata into the discovery service.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_process_metadata_register_msg(LassoIdWsf2Discovery *discovery,
 	const gchar *message)
@@ -214,6 +259,18 @@ lasso_idwsf2_discovery_process_metadata_register_msg(LassoIdWsf2Discovery *disco
 	return res;
 }
 
+/**
+ * lasso_idwsf2_discovery_process_metadata_register_response_msg:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @message: received metadata register soap response
+ *
+ * Process received metadata register response.
+ * Check response status code.
+ * If successful, save into @discovery->svcMDID the service metadata identifier
+ * found in the response.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_process_metadata_register_response_msg(LassoIdWsf2Discovery *discovery,
 	const gchar *message)
@@ -249,7 +306,16 @@ lasso_idwsf2_discovery_process_metadata_register_response_msg(LassoIdWsf2Discove
 	return res;
 }
 
-
+/**
+ * lasso_idwsf2_discovery_init_metadata_association_add:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @svcMDID: identifier of the service metadata the user wants to associate with
+ *
+ * Initialise a request to associate a user account to a service metadata, allowing
+ * a WSC to request this service for data related to this user account.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_init_metadata_association_add(LassoIdWsf2Discovery *discovery,
 	const gchar *svcMDID)
@@ -281,6 +347,15 @@ lasso_idwsf2_discovery_init_metadata_association_add(LassoIdWsf2Discovery *disco
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_discovery_process_metadata_association_add_msg:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @message: received metadata association add soap request
+ *
+ * Process received metadata association add request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_process_metadata_association_add_msg(LassoIdWsf2Discovery *discovery,
 	const gchar *message)
@@ -312,6 +387,14 @@ lasso_idwsf2_discovery_process_metadata_association_add_msg(LassoIdWsf2Discovery
 	return res;
 }
 
+/**
+ * lasso_idwsf2_discovery_register_metadata:
+ * @discovery: a #LassoIdWsf2Discovery
+ *
+ * Add service metadata identifier into user identity object.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_register_metadata(LassoIdWsf2Discovery *discovery)
 {
@@ -360,6 +443,16 @@ lasso_idwsf2_discovery_register_metadata(LassoIdWsf2Discovery *discovery)
 	return res;
 }
 
+/**
+ * lasso_idwsf2_discovery_process_metadata_association_add_response_msg:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @message: received metadata association add soap response
+ *
+ * Process received metadata association add response.
+ * Check response status code.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_process_metadata_association_add_response_msg(
 	LassoIdWsf2Discovery *discovery, const gchar *message)
@@ -399,8 +492,9 @@ lasso_idwsf2_discovery_process_metadata_association_add_response_msg(
 /**
  * lasso_idwsf2_discovery_init_query
  * @discovery: a #LassoIdWsf2Discovery
+ * @security_mech_id: obsolete ; can be NULL
  *
- * Initializes a disco:Query message.
+ * Initialise a request for ID-WSF discovery Query to a discovery service.
  *
  * Return value: 0 on success; or a negative value otherwise.
  **/
@@ -430,6 +524,15 @@ lasso_idwsf2_discovery_init_query(LassoIdWsf2Discovery *discovery, G_GNUC_UNUSED
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_discovery_add_requested_service_type
+ * @discovery: a #LassoIdWsf2Discovery
+ * @service_type: the service type (or data profile) requested
+ *
+ * Select the requested service type which will be queried.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_add_requested_service_type(LassoIdWsf2Discovery *discovery,
 	const gchar *service_type)
@@ -452,6 +555,15 @@ lasso_idwsf2_discovery_add_requested_service_type(LassoIdWsf2Discovery *discover
 	return 0;
 }
 
+/**
+ * lasso_idwsf2_discovery_process_query_msg:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @message: received query soap request
+ *
+ * Process received query request.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_process_query_msg(LassoIdWsf2Discovery *discovery, const gchar *message)
 {
@@ -472,6 +584,17 @@ lasso_idwsf2_discovery_process_query_msg(LassoIdWsf2Discovery *discovery, const
 	return res;
 }
 
+/**
+ * lasso_idwsf2_discovery_build_epr:
+ * @service: a #LassoIdWsf2DiscoRequestedService containing the query criteria
+ * @identity: a #LassoIdentity of the current user
+ * @server: current #LassoServer
+ *
+ * Build an EndpointReference (EPR) which contains all the information about a WSP providing
+ * the requested service type and matching other query criteria to allow a WSC to request it.
+ *
+ * Return value: the newly built EPR; or NULL if no WSP match the query criteria.
+ **/
 static LassoWsAddrEndpointReference*
 lasso_idwsf2_discovery_build_epr(LassoIdWsf2DiscoRequestedService *service,
 	LassoIdentity *identity, LassoServer *server)
@@ -596,6 +719,15 @@ lasso_idwsf2_discovery_build_epr(LassoIdWsf2DiscoRequestedService *service,
 	return epr;
 }
 
+/**
+ * lasso_idwsf2_discovery_build_query_response_eprs:
+ * @discovery: a #LassoIdWsf2Discovery
+ *
+ * Build a query response containing one or more EndpointReference (EPR) for each WSP providing
+ * the requested service type and matching other query criteria to allow a WSC to request them.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_build_query_response_eprs(LassoIdWsf2Discovery *discovery)
 {
@@ -659,6 +791,17 @@ lasso_idwsf2_discovery_build_query_response_eprs(LassoIdWsf2Discovery *discovery
 	return res;
 }
 
+/**
+ * lasso_idwsf2_discovery_process_query_response_msg:
+ * @discovery: a #LassoIdWsf2Discovery
+ * @message: received query soap response
+ *
+ * Process received query response.
+ * Copy returned EPRs into session object.
+ * Check response status code.
+ *
+ * Return value: 0 on success; or a negative value otherwise.
+ **/
 gint
 lasso_idwsf2_discovery_process_query_response_msg(LassoIdWsf2Discovery *discovery,
 	const gchar *message)
@@ -711,11 +854,10 @@ lasso_idwsf2_discovery_process_query_response_msg(LassoIdWsf2Discovery *discover
  * @discovery: a #LassoIdWsf2Discovery
  * @service_type: the requested service type
  *
- * After a disco:query message, creates a #LassoIdWsf2DataService instance for the
+ * After a discovery query message, create a #LassoIdWsf2DataService instance for the
  * requested @service_type.
  *
- * Return value: a newly created #LassoIdWsf2DataService object; or NULL if an
- *     error occured.
+ * Return value: a newly created #LassoIdWsf2DataService object; or NULL if an error occured.
  **/
 LassoIdWsf2DataService*
 lasso_idwsf2_discovery_get_service(LassoIdWsf2Discovery *discovery, G_GNUC_UNUSED const gchar *service_type)
@@ -854,10 +996,9 @@ lasso_idwsf2_discovery_get_type()
  * lasso_idwsf2_discovery_new:
  * @server: the #LassoServer
  *
- * Creates a new #LassoIdWsf2Discovery.
+ * Create a new #LassoIdWsf2Discovery.
  *
- * Return value: a newly created #LassoIdWsf2Discovery object; or NULL if an error
- *      occured.
+ * Return value: a newly created #LassoIdWsf2Discovery object; or NULL if an error occured.
  **/
 LassoIdWsf2Discovery*
 lasso_idwsf2_discovery_new(LassoServer *server)
diff --git a/lasso/id-wsf-2.0/discovery.h b/lasso/id-wsf-2.0/discovery.h
index 400f73ec..4cc4ca43 100644
--- a/lasso/id-wsf-2.0/discovery.h
+++ b/lasso/id-wsf-2.0/discovery.h
@@ -72,8 +72,6 @@ LASSO_EXPORT GType lasso_idwsf2_discovery_get_type(void);
 
 LASSO_EXPORT LassoIdWsf2Discovery* lasso_idwsf2_discovery_new(LassoServer *server);
 
-LASSO_EXPORT void lasso_idwsf2_discovery_destroy(LassoIdWsf2Discovery *discovery);
-
 LASSO_EXPORT gchar* lasso_idwsf2_discovery_metadata_register_self(LassoIdWsf2Discovery *discovery,
 	const gchar *service_type, const gchar *abstract,
 	const gchar *soap_endpoint, const gchar *svcMDID);
diff --git a/lasso/id-wsf/data_service.c b/lasso/id-wsf/data_service.c
index 974f0f00..477d2732 100644
--- a/lasso/id-wsf/data_service.c
+++ b/lasso/id-wsf/data_service.c
@@ -24,7 +24,10 @@
 
 /**
  * SECTION:data_service
- * @short_description: ID-WSF Data Service Profile
+ * @short_description: ID-WSF Data Service profile
+ *
+ * DataService allows Attribute Consumers (WSC) to request an Attribute Provider (WSP) to get
+ * or modify data about users with their consent.
  *
  * Following up on #LassoDiscovery first example, it created a @service object,
  * this is a #LassoDataService instance.  This example continues from that step
@@ -1030,6 +1033,15 @@ lasso_data_service_new(LassoServer *server)
 	return service;
 }
 
+/**
+ * lasso_data_service_new_full:
+ * @server: the #LassoServer
+ * @offering: the #LassoDiscoResourceOffering
+ *
+ * Creates a new #LassoDataService.
+ *
+ * Return value: a newly created #LassoDataService object; or NULL if an error occured.
+ **/
 LassoDataService*
 lasso_data_service_new_full(LassoServer *server, LassoDiscoResourceOffering *offering)
 {
diff --git a/lasso/id-wsf/discovery.c b/lasso/id-wsf/discovery.c
index 3b958dc9..1d160d95 100644
--- a/lasso/id-wsf/discovery.c
+++ b/lasso/id-wsf/discovery.c
@@ -1360,8 +1360,7 @@ lasso_discovery_get_type()
  *
  * Creates a new #LassoDiscovery.
  *
- * Return value: a newly created #LassoDiscovery object; or NULL if an error
- *      occured.
+ * Return value: a newly created #LassoDiscovery object; or NULL if an error occured.
  **/
 LassoDiscovery*
 lasso_discovery_new(LassoServer *server)
@@ -1376,16 +1375,14 @@ lasso_discovery_new(LassoServer *server)
 	return discovery;
 }
 
-
 /**
  * lasso_discovery_new_full:
  * @server: the #LassoServer
- * @offering: the
+ * @offering: the #LassoDiscoResourceOffering
  *
  * Creates a new #LassoDiscovery.
  *
- * Return value: a newly created #LassoDiscovery object; or NULL if an error
- *      occured.
+ * Return value: a newly created #LassoDiscovery object; or NULL if an error occured.
  **/
 LassoDiscovery*
 lasso_discovery_new_full(LassoServer *server, LassoDiscoResourceOffering *offering)