[rygel-grilo] Document functions

[Juan A. Suarez Romero <jasuarez src gnome org>]

commit 4cf75de0a6fe81a03de2c1328ddaabb09b67c7bf
Author: Juan A. Suarez Romero <jasuarez igalia com>
Date:   Fri Apr 16 19:15:44 2010 +0200

    Document functions
    
    Add gtk-doc documentation to public functions.

 lib/media-server2-client.c |  299 ++++++++++++++++++++++++++++++++++++++++++++
 lib/media-server2-server.c |  252 +++++++++++++++++++++++++++++++++++++
 2 files changed, 551 insertions(+), 0 deletions(-)
---
diff --git a/lib/media-server2-client.c b/lib/media-server2-client.c
index 57f8b6c..df1b7de 100644
--- a/lib/media-server2-client.c
+++ b/lib/media-server2-client.c
@@ -192,6 +192,7 @@ ms2_client_class_init (MS2ClientClass *klass)
   g_type_class_add_private (klass, sizeof (MS2ClientPrivate));
 }
 
+/* Object init function */
 static void
 ms2_client_init (MS2Client *client)
 {
@@ -200,6 +201,13 @@ ms2_client_init (MS2Client *client)
 
 /******************** PUBLIC API ********************/
 
+/**
+ * ms2_client_get_providers:
+ *
+ * Returns a list of content providers following MediaServer2 specification.
+ *
+ * Returns: a new @NULL-terminated array of strings
+ **/
 gchar **
 ms2_client_get_providers ()
 {
@@ -225,6 +233,7 @@ ms2_client_get_providers ()
                                       DBUS_PATH_DBUS,
                                       DBUS_INTERFACE_DBUS);
 
+  /* Get a list of all DBUS services running */
   org_freedesktop_DBus_list_names (gproxy, &dbus_names, &error);
   g_object_unref (gproxy);
 
@@ -238,6 +247,7 @@ ms2_client_get_providers ()
     return FALSE;
   }
 
+  /* Filter the list to obtain those services that fulfils MediaServer2 spec */
   providers = g_ptr_array_new ();
   for (p = dbus_names; *p; p++) {
     if (g_str_has_prefix (*p, MS2_DBUS_SERVICE_PREFIX)) {
@@ -245,6 +255,7 @@ ms2_client_get_providers ()
     }
   }
 
+  /* Put them in a NULL-terminated array */
   list_providers = g_new (gchar *, providers->len + 1);
   for (i = 0; i < providers->len; i++) {
     list_providers[i] = g_strdup (g_ptr_array_index (providers, i) + prefix_size);
@@ -258,6 +269,16 @@ ms2_client_get_providers ()
   return list_providers;
 }
 
+/**
+ * ms2_client_new:
+ * @provider: provider name.
+ *
+ * Create a new #MS2Client that will be used to obtain content from the provider specified.
+ *
+ * Providers can be obtained with ms2_client_get_providers().
+ *
+ * Returns: a new #MS2Client
+ **/
 MS2Client *ms2_client_new (const gchar *provider)
 {
   DBusGConnection *connection;
@@ -300,6 +321,18 @@ MS2Client *ms2_client_new (const gchar *provider)
   return client;
 }
 
+/**
+ * ms2_client_get_properties:
+ * @client: a #MS2Client
+ * @id: media identifier to obtain properties from
+ * @properties: @NULL-terminated array of properties to request
+ * @error: a #GError location to store the error ocurring, or @NULL to ignore
+ *
+ * Gets the properties of media id. Properties will be returned in a hash table
+ * of <prop_id, prop_gvalue> pairs.
+ *
+ * Returns: a new #GHashTable
+ **/
 GHashTable *
 ms2_client_get_properties (MS2Client *client,
                            const gchar *id,
@@ -325,6 +358,23 @@ ms2_client_get_properties (MS2Client *client,
   return prop_result;
 }
 
+/**
+ * ms2_client_get_properties_async:
+ * @client: a #MS2Client
+ * @id: media identifier to obtain properties from
+ * @properties: @NULL-terminated array of properties to request
+ * @callback: a #GAsyncReadyCallback to call when request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Starts an asynchronous get properties.
+ *
+ * For more details, see ms2_client_get_properties(), which is the synchronous
+ * version of this call.
+ *
+ * When the properties have been obtained, @callback will be called with
+ * @user_data. To finish the operation, call ms2_client_get_properties_finish()
+ * with the #GAsyncResult returned by the @callback.
+ **/
 void ms2_client_get_properties_async (MS2Client *client,
                                       const gchar *id,
                                       const gchar **properties,
@@ -358,6 +408,17 @@ void ms2_client_get_properties_async (MS2Client *client,
                                                     res);
 }
 
+/**
+ * ms2_client_get_properties_finish:
+ * @client: a #MS2Client
+ * @res: a #GAsyncResult
+ * @error: a #GError location to store the error ocurring, or @NULL to ignore
+ *
+ * Finishes an asynchronous getting properties operation. Properties are
+ * returned in a #GHashTable.
+ *
+ * Returns: a new #GHashTable
+ **/
 GHashTable *
 ms2_client_get_properties_finish (MS2Client *client,
                                   GAsyncResult *res,
@@ -372,6 +433,21 @@ ms2_client_get_properties_finish (MS2Client *client,
   return adata->properties_result;
 }
 
+/**
+ * ms2_client_get_children:
+ * @client: a #MS2Client
+ * @id: container identifier to get children from
+ * @offset: number of children to skip
+ * @max_count: maximum number of children to return, or -1 for no limit
+ * @properties: @NULL-terminated array of properties to request for each child
+ * @error: a #GError location to store the error ocurring, or @NULL to ignore
+ *
+ * Gets the list of children directly under the container id. Each child consist
+ * of a hash table of <prop_id, prop_gvalue> pairs.
+ *
+ * Returns: a new #GList of #GHashTable. To free it, free first each element
+ * (g_hash_table_unref()) and finally the list itself (g_list_free())
+ **/
 GList *
 ms2_client_get_children (MS2Client *client,
                          const gchar *id,
@@ -403,6 +479,25 @@ ms2_client_get_children (MS2Client *client,
   return children;
 }
 
+/**
+ * ms2_client_get_children_async:
+ * @client: a #MS2Client
+ * @id: container identifier to get children from
+ * @offset: number of children to skip
+ * @max_count: maximum number of children to return, or -1 for no limit
+ * @properties: @NULL-terminated array of properties to request for each child
+ * @callback: a #GAsyncReadyCallback to call when request is satisfied
+ * @user_data: the data to pass to callback function
+ *
+ * Starts an asynchronous get children.
+ *
+ * For more details, see ms2_client_get_children(), which is the synchronous
+ * version of this call.
+ *
+ * When the children have been obtained, @callback will be called with
+ * @user_data. To finish the operation, call ms2_client_get_children_finish()
+ * with the #GAsyncResult returned by the @callback.
+ **/
 void ms2_client_get_children_async (MS2Client *client,
                                     const gchar *id,
                                     guint offset,
@@ -440,6 +535,17 @@ void ms2_client_get_children_async (MS2Client *client,
                                                   res);
 }
 
+/**
+ * ms2_client_get_children_finish:
+ * @client: a #MS2Client
+ * @res: a #GAsyncResult
+ * @error: a #GError location to store the error ocurring, or @NULL to ignore
+ *
+ * Finishes an asynchronous getting children operation.
+ *
+ * Returns: a new #GList of #GHashTAble. To free it, free first each element
+ * (g_hash_table_unref()) and finally the list itself (g_list_free())
+ **/
 GList *
 ms2_client_get_children_finish (MS2Client *client,
                                 GAsyncResult *res,
@@ -456,6 +562,14 @@ ms2_client_get_children_finish (MS2Client *client,
 
 /******************** PROPERTIES TABLE API ********************/
 
+/**
+ * ms2_client_get_id:
+ * @properties: a #GHashTable
+ *
+ * Returns "id" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_id (GHashTable *properties)
 {
@@ -471,6 +585,14 @@ ms2_client_get_id (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_parent:
+ * @properties: a #GHashTable
+ *
+ * Returns "parent" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_parent (GHashTable *properties)
 {
@@ -486,6 +608,14 @@ ms2_client_get_parent (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_display_name:
+ * @properties: a #GHashTable
+ *
+ * Returns "display-name" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_display_name (GHashTable *properties)
 {
@@ -501,6 +631,14 @@ ms2_client_get_display_name (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_item_type:
+ * @properties: a #GHashTable
+ *
+ * Returns "type" property value.
+ *
+ * Returns: property value
+ **/
 MS2ItemType
 ms2_client_get_item_type (GHashTable *properties)
 {
@@ -535,6 +673,14 @@ ms2_client_get_item_type (GHashTable *properties)
   }
 }
 
+/**
+ * ms2_client_get_icon:
+ * @properties: a #GHashTable
+ *
+ * Returns "icon" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_icon (GHashTable *properties)
 {
@@ -550,6 +696,14 @@ ms2_client_get_icon (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_mime_type:
+ * @properties: a #GHashTable
+ *
+ * Returns "mime-type" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_mime_type (GHashTable *properties)
 {
@@ -565,6 +719,14 @@ ms2_client_get_mime_type (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_artist:
+ * @properties: a #GHashTable
+ *
+ * Returns "artist" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_artist (GHashTable *properties)
 {
@@ -580,6 +742,14 @@ ms2_client_get_artist (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_album:
+ * @properties: a #GHashTable
+ *
+ * Returns "album" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_album (GHashTable *properties)
 {
@@ -595,6 +765,14 @@ ms2_client_get_album (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_date:
+ * @properties: a #GHashTable
+ *
+ * Returns "date" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_date (GHashTable *properties)
 {
@@ -610,6 +788,14 @@ ms2_client_get_date (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_dlna_profile:
+ * @properties: a #GHashTable
+ *
+ * Returns "dlna-profile" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_dlna_profile (GHashTable *properties)
 {
@@ -625,6 +811,14 @@ ms2_client_get_dlna_profile (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_thumbnail:
+ * @properties: a #GHashTable
+ *
+ * Returns "thumbanil" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_thumbnail (GHashTable *properties)
 {
@@ -640,6 +834,14 @@ ms2_client_get_thumbnail (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_genre:
+ * @properties: a #GHashTable
+ *
+ * Returns "genre" property value.
+ *
+ * Returns: property value or @NULL if it is not available
+ **/
 const gchar *
 ms2_client_get_genre (GHashTable *properties)
 {
@@ -655,6 +857,14 @@ ms2_client_get_genre (GHashTable *properties)
   return g_value_get_string (val);
 }
 
+/**
+ * ms2_client_get_child_count:
+ * @properties: a #GHashTable
+ *
+ * Returns "child-count" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_child_count (GHashTable *properties)
 {
@@ -670,6 +880,14 @@ ms2_client_get_child_count (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_size:
+ * @properties: a #GHashTable
+ *
+ * Returns "size" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_size (GHashTable *properties)
 {
@@ -685,6 +903,14 @@ ms2_client_get_size (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_duration:
+ * @properties: a #GHashTable
+ *
+ * Returns "duration" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_duration (GHashTable *properties)
 {
@@ -700,6 +926,14 @@ ms2_client_get_duration (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_bitrate:
+ * @properties: a #GHashTable
+ *
+ * Returns "bitrate" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_bitrate (GHashTable *properties)
 {
@@ -715,6 +949,14 @@ ms2_client_get_bitrate (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_sample_rate:
+ * @properties: a #GHashTable
+ *
+ * Returns "sample-rate" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_sample_rate (GHashTable *properties)
 {
@@ -730,6 +972,14 @@ ms2_client_get_sample_rate (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_bits_per_sample:
+ * @properties: a #GHashTable
+ *
+ * Returns "bits-per-sample" property value.
+ *
+ * Returns: property value of -1 if it is not available
+ **/
 gint
 ms2_client_get_bits_per_sample (GHashTable *properties)
 {
@@ -745,6 +995,14 @@ ms2_client_get_bits_per_sample (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_width:
+ * @properties: a #GHashTable
+ *
+ * Returns "width" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_width (GHashTable *properties)
 {
@@ -760,6 +1018,14 @@ ms2_client_get_width (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_height:
+ * @properties: a #GHashTable
+ *
+ * Returns "height" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_height (GHashTable *properties)
 {
@@ -775,6 +1041,14 @@ ms2_client_get_height (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_color_depth:
+ * @properties: a #GHashTable
+ *
+ * Returns "color-depth" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_color_depth (GHashTable *properties)
 {
@@ -790,6 +1064,14 @@ ms2_client_get_color_depth (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_pixel_width:
+ * @properties: a #GHashTable
+ *
+ * Returns "pixel-width" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_pixel_width (GHashTable *properties)
 {
@@ -805,6 +1087,14 @@ ms2_client_get_pixel_width (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_pixel_height:
+ * @properties: a #GHashTable
+ *
+ * Returns "pixel-height" property value.
+ *
+ * Returns: property value or -1 if it is not available
+ **/
 gint
 ms2_client_get_pixel_height (GHashTable *properties)
 {
@@ -820,6 +1110,15 @@ ms2_client_get_pixel_height (GHashTable *properties)
   return g_value_get_int (val);
 }
 
+/**
+ * ms2_client_get_urls:
+ * @properties: a #GHashTable
+ *
+ * Returns "URLs" property value.
+ *
+ * Returns: a new @NULL-terminated array of strings or @NULL if it is not
+ * available
+ **/
 gchar **
 ms2_client_get_urls (GHashTable *properties)
 {
diff --git a/lib/media-server2-server.c b/lib/media-server2-server.c
index 4aa4acb..ac9d028 100644
--- a/lib/media-server2-server.c
+++ b/lib/media-server2-server.c
@@ -286,6 +286,18 @@ ms2_server_init (MS2Server *server)
 
 /****************** INTERNAL PUBLIC API (NOT TO BE EXPORTED) ******************/
 
+/*
+ * ms2_server_get_properties:
+ * @server: a #MS2Server
+ * @id: media identifier to obtain properties from
+ * @filter: @NULL-terminated array of requested properties
+ * @context: DBus context to send the reply through
+ * @error: a #GError location to store the error ocurring, or @NULL to ignore
+ *
+ * Sends a #GPtrArray of properties values through DBus.
+ *
+ * Returns: @TRUE if success
+ */
 gboolean
 ms2_server_get_properties (MS2Server *server,
                            const gchar *id,
@@ -299,6 +311,7 @@ ms2_server_get_properties (MS2Server *server,
   GPtrArray *prop_array = NULL;
   const gchar *wrong_prop;
 
+  /* Check if peer has defined a function to retrieve properties */
   if (!server->priv->get_properties) {
     send_error = g_error_new_literal (MS2_ERROR,
                                       MS2_ERROR_GENERAL,
@@ -326,6 +339,7 @@ ms2_server_get_properties (MS2Server *server,
     }
   }
 
+  /* Check if there was an error */
   if (send_error) {
     if (error) {
       *error = g_error_copy (send_error);
@@ -336,6 +350,8 @@ ms2_server_get_properties (MS2Server *server,
     return TRUE;
   }
 
+  /* Convert properties table in a type suitable to send through DBus (in this
+     case, in a gptrarray of gvalues) */
   prop_array = get_array_properties (properties, filter);
   dbus_g_method_return (context, prop_array);
 
@@ -350,6 +366,21 @@ ms2_server_get_properties (MS2Server *server,
   return TRUE;
 }
 
+/*
+ * ms2_server_get_children:
+ * @server: a #MS2Server
+ * @id: container identifier to get children from
+ * @offset: number of children to skip in the result
+ * @max_count: maximum number of children to return, or -1 for no limit
+ * @filter: @NULL-terminated array of requested properties
+ * @context: DBus context to send the reply through
+ * @error: a #GError location to store the error ocurring, or @NULL to ignore
+ *
+ * Sends a #GPtrArray of children through DBus. Each child is in its turn a
+ * #GPtrArray of properties values.
+ *
+ * Returns: @TRUE if success
+ */
 gboolean
 ms2_server_get_children (MS2Server *server,
                          const gchar *id,
@@ -365,6 +396,7 @@ ms2_server_get_children (MS2Server *server,
   GList *children = NULL;
   const gchar *wrong_prop;
 
+  /* Check if peer has defined a function to retrieve children */
   if (!server->priv->get_children) {
     send_error = g_error_new_literal (MS2_ERROR,
                                       MS2_ERROR_GENERAL,
@@ -394,6 +426,7 @@ ms2_server_get_children (MS2Server *server,
     }
   }
 
+  /* Check if there was an error */
   if (send_error) {
     if (error) {
       *error = g_error_copy (send_error);
@@ -404,6 +437,8 @@ ms2_server_get_children (MS2Server *server,
     return TRUE;
   }
 
+  /* Convert children list in a type suitable to send through DBUS (in this
+     case, in a gptrarray of gptrarray o gvalues) */
   children_array = get_array_children (children, filter);
   dbus_g_method_return (context, children_array);
 
@@ -419,6 +454,19 @@ ms2_server_get_children (MS2Server *server,
 
 /********** SERVER API **********/
 
+/**
+ * ms2_server_new:
+ * @name: the name used when registered in DBus
+ * @data: user defined data
+ *
+ * Creates a new #MS2Server that will be registered in DBus under name
+ * "org.gnome.UPnP.MediaServer2.<name>".
+ *
+ * @data will be used as parameter when invoking the functions to retrieve
+ * properties or children.
+ *
+ * Returns: a new #MS2Server registed in DBus, or @NULL if fails
+ **/
 MS2Server *
 ms2_server_new (const gchar *name,
                 gpointer data)
@@ -429,6 +477,7 @@ ms2_server_new (const gchar *name,
 
   server->priv->data = data;
 
+  /* Register object in DBus */
   if (!ms2_server_dbus_register (server, name)) {
     g_object_unref (server);
     return NULL;
@@ -437,6 +486,13 @@ ms2_server_new (const gchar *name,
   }
 }
 
+/**
+ * ms2_server_set_get_properties_func:
+ * @server: a #MS2Server
+ * @get_properties_func: user-defined function to request properties
+ *
+ * Defines which function must be used when requesting properties.
+ **/
 void
 ms2_server_set_get_properties_func (MS2Server *server,
                                     GetPropertiesFunc get_properties_func)
@@ -446,6 +502,13 @@ ms2_server_set_get_properties_func (MS2Server *server,
   server->priv->get_properties = get_properties_func;
 }
 
+/**
+ * ms2_server_set_get_children_func:
+ * @server: a #MS2Server
+ * @get_children_func: user-defined function to request children
+ *
+ * Defines which function must be used when requesting children.
+ **/
 void
 ms2_server_set_get_children_func (MS2Server *server,
                                   GetChildrenFunc get_children_func)
@@ -458,6 +521,16 @@ ms2_server_set_get_children_func (MS2Server *server,
 
 /********** PROPERTIES TABLE API **********/
 
+/**
+ * ms2_server_new_properties_hashtable:
+ * @id: identifier of item which properties will be stored in the table
+ *
+ * Creates a new #GHashTable suitable to store items properties.
+ *
+ * For root container, identifier should be "0".
+ *
+ * Returns: a new #GHashTable
+ **/
 GHashTable *
 ms2_server_new_properties_hashtable (const gchar *id)
 {
@@ -474,6 +547,13 @@ ms2_server_new_properties_hashtable (const gchar *id)
   return properties;
 }
 
+/**
+ * ms2_server_set_parent:
+ * @properties: a #GHashTable
+ * @parent: parent value
+ *
+ * Sets the "parent" property. Mandatory property.
+ **/
 void
 ms2_server_set_parent (GHashTable *properties,
                        const gchar *parent)
@@ -487,6 +567,13 @@ ms2_server_set_parent (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_display_name:
+ * @properties: a #GHashTable
+ * @display_name: display name value
+ *
+ * Sets the "display-name" property. Mandatory property.
+ **/
 void
 ms2_server_set_display_name (GHashTable *properties,
                              const gchar *display_name)
@@ -500,6 +587,15 @@ ms2_server_set_display_name (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_item_type:
+ * @properties: a #GHashTable
+ * @type: type of item
+ *
+ * Sets the "type" property. Mandatory property.
+ *
+ * Tells what kind of object we are dealing with.
+ **/
 void
 ms2_server_set_item_type (GHashTable *properties,
                           MS2ItemType type)
@@ -548,6 +644,16 @@ ms2_server_set_item_type (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_icon:
+ * @properties: a #GHashTable
+ * @icon: icon identifier value
+ *
+ * Sets the "icon" property. Recommended property for containers.
+ *
+ * Use this to provide an icon to be used by consumer UIs to represent the
+ * provider. This is only relevant to root container.
+ **/
 void
 ms2_server_set_icon (GHashTable *properties,
                      const gchar *icon)
@@ -561,6 +667,13 @@ ms2_server_set_icon (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_mime_type:
+ * @properties: a #GHashTable
+ * @mime_type: mime type value
+ *
+ * Sets the "mime-type" property. Mandatory property for items.
+ **/
 void
 ms2_server_set_mime_type (GHashTable *properties,
                           const gchar *mime_type)
@@ -574,6 +687,13 @@ ms2_server_set_mime_type (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_artist:
+ * @properties: a #GHashTable
+ * @artist: artist value
+ *
+ * Sets the "artist" property. Recommended property for items.
+ **/
 void
 ms2_server_set_artist (GHashTable *properties,
                        const gchar *artist)
@@ -587,6 +707,13 @@ ms2_server_set_artist (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_album:
+ * @properties: a #GHashTable
+ * @album: album value
+ *
+ * Sets the "album" property. Recommended property for items.
+ **/
 void
 ms2_server_set_album (GHashTable *properties,
                       const gchar *album)
@@ -600,6 +727,16 @@ ms2_server_set_album (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_date:
+ * @properties: a #GHashTable
+ * @date: date value
+ *
+ * Sets the "date" property. Recommended property for items.
+ *
+ * This date can be date of creation or release. Must be compliant to ISO-8601
+ * and RFC-3339.
+ **/
 void
 ms2_server_set_date (GHashTable *properties,
                      const gchar *date)
@@ -613,6 +750,16 @@ ms2_server_set_date (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_dlna_profile:
+ * @properties: a #GHashTable
+ * @dlna_profile: DLNA value
+ *
+ * Sets the "dlna-profile" property. Optional property for items.
+ *
+ * If you provide a value for this property, it will greatly help avoiding
+ * guessing of its value by UPnP consumers.
+ **/
 void
 ms2_server_set_dlna_profile (GHashTable *properties,
                              const gchar *dlna_profile)
@@ -626,6 +773,13 @@ ms2_server_set_dlna_profile (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_thumbnail:
+ * @properties: a #GHashTable
+ * @thumbnail: thumbnail identifier value
+ *
+ * Sets the "thumbnail" property. Optional property for video/image items.
+ **/
 void
 ms2_server_set_thumbnail (GHashTable *properties,
                           const gchar *thumbnail)
@@ -639,6 +793,13 @@ ms2_server_set_thumbnail (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_genre:
+ * @properties: a #GHashTable
+ * @genre: genre value
+ *
+ * Sets the "genre" property. Optional property for audio/music items.
+ **/
 void
 ms2_server_set_genre (GHashTable *properties,
                       const gchar *genre)
@@ -652,6 +813,15 @@ ms2_server_set_genre (GHashTable *properties,
   }
 }
 
+/**
+ * ms2_server_set_child_count:
+ * @properties: a #GHashTable
+ * @child_count: childcount value
+ *
+ * Sets the "child-count" property. Recommended property for containers.
+ *
+ * It is the number of media objects directly under this container.
+ **/
 void
 ms2_server_set_child_count (GHashTable *properties,
                             gint child_count)
@@ -663,6 +833,15 @@ ms2_server_set_child_count (GHashTable *properties,
                        int_to_value (child_count));
 }
 
+/**
+ * ms2_server_set_size:
+ * @properties: a #GHashTable
+ * @size: size value
+ *
+ * Sets the "size" property. Recommended property for items.
+ *
+ * It is the resource size in bytes.
+ **/
 void
 ms2_server_set_size (GHashTable *properties,
                      gint size)
@@ -674,6 +853,13 @@ ms2_server_set_size (GHashTable *properties,
                        int_to_value (size));
 }
 
+/**
+ * ms2_server_set_duration:
+ * @properties: a #GHashTable
+ * @duration: duration (in seconds) value
+ *
+ * Sets the "duration" property. Optional property for audio/video/music items.
+ **/
 void
 ms2_server_set_duration (GHashTable *properties,
                          gint duration)
@@ -685,6 +871,13 @@ ms2_server_set_duration (GHashTable *properties,
                        int_to_value (duration));
 }
 
+/**
+ * ms2_server_set_bitrate:
+ * @properties: a #GHashTable
+ * @bitrate: bitrate value
+ *
+ * Sets the "bitrate" property. Optional property for audio/video/music items.
+ **/
 void
 ms2_server_set_bitrate (GHashTable *properties,
                         gint bitrate)
@@ -696,6 +889,14 @@ ms2_server_set_bitrate (GHashTable *properties,
                        int_to_value (bitrate));
 }
 
+/**
+ * ms2_server_set_sample_rate:
+ * @properties: a #GHashTable
+ * @sample_rate: sample rate value
+ *
+ * Sets the "sample-rate" property. Optional property for audio/video/music
+ * items.
+ **/
 void
 ms2_server_set_sample_rate (GHashTable *properties,
                             gint sample_rate)
@@ -707,6 +908,14 @@ ms2_server_set_sample_rate (GHashTable *properties,
                        int_to_value (sample_rate));
 }
 
+/**
+ * ms2_server_set_bits_per_sample:
+ * @properties: a #GHashTable
+ * @bits_per_sample: bits per sample value
+ *
+ * Sets the "bits-per-sample" property. Optional property for audio/video/music
+ * items.
+ **/
 void
 ms2_server_set_bits_per_sample (GHashTable *properties,
                                 gint bits_per_sample)
@@ -718,6 +927,13 @@ ms2_server_set_bits_per_sample (GHashTable *properties,
                        int_to_value (bits_per_sample));
 }
 
+/**
+ * ms2_server_set_width:
+ * @properties: a #GHashTable
+ * @width: width (in pixels) value
+ *
+ * Sets the "width" property. Recommended property for video/image items.
+ **/
 void
 ms2_server_set_width (GHashTable *properties,
                       gint width)
@@ -729,6 +945,13 @@ ms2_server_set_width (GHashTable *properties,
                        int_to_value (width));
 }
 
+/**
+ * ms2_server_set_height:
+ * @properties: a #GHashTable
+ * @height: height (in pixels) value
+ *
+ * Sets the "height" property. Recommended property for video/image items.
+ **/
 void
 ms2_server_set_height (GHashTable *properties,
                        gint height)
@@ -740,6 +963,13 @@ ms2_server_set_height (GHashTable *properties,
                        int_to_value (height));
 }
 
+/**
+ * ms2_server_set_color_depth:
+ * @properties: a #GHashTable
+ * @depth: color depth value
+ *
+ * Sets the "color-depth" property. Recommended property for video/image items.
+ **/
 void
 ms2_server_set_color_depth (GHashTable *properties,
                             gint depth)
@@ -751,6 +981,13 @@ ms2_server_set_color_depth (GHashTable *properties,
                        int_to_value (depth));
 }
 
+/**
+ * ms2_server_set_pixel_width:
+ * @properties: a #GHashTable
+ * @pixel_width: pixel width value
+ *
+ * Sets the "pixel-width" property. Optional property for video/image items.
+ **/
 void
 ms2_server_set_pixel_width (GHashTable *properties,
                             gint pixel_width)
@@ -762,6 +999,13 @@ ms2_server_set_pixel_width (GHashTable *properties,
                        int_to_value (pixel_width));
 }
 
+/**
+ * ms2_server_set_pixel_height:
+ * @properties: a #GHashTable
+ * @pixel_height: pixel height value
+ *
+ * Sets the "pixel-height" property. Optional property for video/image items.
+ **/
 void
 ms2_server_set_pixel_height (GHashTable *properties,
                              gint pixel_height)
@@ -773,6 +1017,13 @@ ms2_server_set_pixel_height (GHashTable *properties,
                        int_to_value (pixel_height));
 }
 
+/**
+ * ms2_server_set_urls:
+ * @properties: a #GHashTable
+ * @urls: @NULL-terminated array of URLs values
+ *
+ * Sets the "URLs" property. Mandatory property for items.
+ **/
 void
 ms2_server_set_urls (GHashTable *properties,
                      gchar **urls)
@@ -782,6 +1033,7 @@ ms2_server_set_urls (GHashTable *properties,
 
   g_return_if_fail (properties);
 
+  /* Check if there is at least one URL */
   if (urls && urls[0]) {
     url_array = g_ptr_array_sized_new (g_strv_length (urls));
     for (i = 0; urls[i]; i++) {