[rygel-grilo] Update documentation

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

commit e0082de49926ccfeeb51933ad2769f569bc0fb40
Author: Juan A. Suarez Romero <jasuarez igalia com>
Date:   Wed May 12 20:17:24 2010 +0200

    Update documentation

 lib/media-server1-client.c       |   49 +++++++++++++++++--------------
 lib/media-server1-observer.c     |    1 +
 lib/media-server1-server-table.c |   59 ++++++++++++++++++++------------------
 lib/media-server1-server.c       |   19 ++++++++++++
 4 files changed, 78 insertions(+), 50 deletions(-)
---
diff --git a/lib/media-server1-client.c b/lib/media-server1-client.c
index 59d720e..a852444 100644
--- a/lib/media-server1-client.c
+++ b/lib/media-server1-client.c
@@ -81,6 +81,7 @@ free_gvalue (GValue *v)
   g_free (v);
 }
 
+/* Insert <key, value> in hashtable */
 static gboolean
 collect_value (gpointer key,
                gpointer value,
@@ -90,6 +91,9 @@ collect_value (gpointer key,
   return TRUE;
 }
 
+/* Given a NULL-terminated array of properties, returns an array of two
+   elements; each array is a NULL-terminated array with properties for one
+   interface. */
 static gchar ***
 split_properties_by_interface (gchar **properties)
 {
@@ -145,6 +149,7 @@ ms1_client_dispose (GObject *object)
   G_OBJECT_CLASS (ms1_client_parent_class)->dispose (object);
 }
 
+/* Finalize function */
 static void
 ms1_client_finalize (GObject *object)
 {
@@ -569,10 +574,10 @@ ms1_client_get_root_path (MS1Client *client)
 /******************** PROPERTIES TABLE API ********************/
 
 /**
- * ms1_client_get_id:
+ * ms1_client_get_path:
  * @properties: a #GHashTable
  *
- * Returns "id" property value.
+ * Returns "Path" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -595,7 +600,7 @@ ms1_client_get_path (GHashTable *properties)
  * ms1_client_get_parent:
  * @properties: a #GHashTable
  *
- * Returns "parent" property value.
+ * Returns "Parent" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -618,7 +623,7 @@ ms1_client_get_parent (GHashTable *properties)
  * ms1_client_get_display_name:
  * @properties: a #GHashTable
  *
- * Returns "display-name" property value.
+ * Returns "DisplayName" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -641,7 +646,7 @@ ms1_client_get_display_name (GHashTable *properties)
  * ms1_client_get_item_type:
  * @properties: a #GHashTable
  *
- * Returns "type" property value.
+ * Returns "Type" property value.
  *
  * Returns: property value
  **/
@@ -685,7 +690,7 @@ ms1_client_get_item_type (GHashTable *properties)
  * ms1_client_get_mime_type:
  * @properties: a #GHashTable
  *
- * Returns "mime-type" property value.
+ * Returns "MIMEType" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -708,7 +713,7 @@ ms1_client_get_mime_type (GHashTable *properties)
  * ms1_client_get_artist:
  * @properties: a #GHashTable
  *
- * Returns "artist" property value.
+ * Returns "Artist" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -731,7 +736,7 @@ ms1_client_get_artist (GHashTable *properties)
  * ms1_client_get_album:
  * @properties: a #GHashTable
  *
- * Returns "album" property value.
+ * Returns "Album" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -754,7 +759,7 @@ ms1_client_get_album (GHashTable *properties)
  * ms1_client_get_date:
  * @properties: a #GHashTable
  *
- * Returns "date" property value.
+ * Returns "Date" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -777,7 +782,7 @@ ms1_client_get_date (GHashTable *properties)
  * ms1_client_get_dlna_profile:
  * @properties: a #GHashTable
  *
- * Returns "dlna-profile" property value.
+ * Returns "DLNAProfile" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -800,7 +805,7 @@ ms1_client_get_dlna_profile (GHashTable *properties)
  * ms1_client_get_thumbnail:
  * @properties: a #GHashTable
  *
- * Returns "thumbanil" property value.
+ * Returns "Thumbanail" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -823,7 +828,7 @@ ms1_client_get_thumbnail (GHashTable *properties)
  * ms1_client_get_genre:
  * @properties: a #GHashTable
  *
- * Returns "genre" property value.
+ * Returns "Genre" property value.
  *
  * Returns: property value or @NULL if it is not available
  **/
@@ -846,7 +851,7 @@ ms1_client_get_genre (GHashTable *properties)
  * ms1_client_get_size:
  * @properties: a #GHashTable
  *
- * Returns "size" property value.
+ * Returns "Size" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -869,7 +874,7 @@ ms1_client_get_size (GHashTable *properties)
  * ms1_client_get_duration:
  * @properties: a #GHashTable
  *
- * Returns "duration" property value.
+ * Returns "Duration" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -892,7 +897,7 @@ ms1_client_get_duration (GHashTable *properties)
  * ms1_client_get_bitrate:
  * @properties: a #GHashTable
  *
- * Returns "bitrate" property value.
+ * Returns "Bitrate" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -915,7 +920,7 @@ ms1_client_get_bitrate (GHashTable *properties)
  * ms1_client_get_sample_rate:
  * @properties: a #GHashTable
  *
- * Returns "sample-rate" property value.
+ * Returns "SampleRate" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -938,7 +943,7 @@ ms1_client_get_sample_rate (GHashTable *properties)
  * ms1_client_get_bits_per_sample:
  * @properties: a #GHashTable
  *
- * Returns "bits-per-sample" property value.
+ * Returns "BitsPerSample" property value.
  *
  * Returns: property value of -1 if it is not available
  **/
@@ -961,7 +966,7 @@ ms1_client_get_bits_per_sample (GHashTable *properties)
  * ms1_client_get_width:
  * @properties: a #GHashTable
  *
- * Returns "width" property value.
+ * Returns "Width" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -984,7 +989,7 @@ ms1_client_get_width (GHashTable *properties)
  * ms1_client_get_height:
  * @properties: a #GHashTable
  *
- * Returns "height" property value.
+ * Returns "Height" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -1007,7 +1012,7 @@ ms1_client_get_height (GHashTable *properties)
  * ms1_client_get_color_depth:
  * @properties: a #GHashTable
  *
- * Returns "color-depth" property value.
+ * Returns "ColorDepth" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -1030,7 +1035,7 @@ ms1_client_get_color_depth (GHashTable *properties)
  * ms1_client_get_pixel_width:
  * @properties: a #GHashTable
  *
- * Returns "pixel-width" property value.
+ * Returns "PixelWidth" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
@@ -1053,7 +1058,7 @@ ms1_client_get_pixel_width (GHashTable *properties)
  * ms1_client_get_pixel_height:
  * @properties: a #GHashTable
  *
- * Returns "pixel-height" property value.
+ * Returns "PixelHeight" property value.
  *
  * Returns: property value or -1 if it is not available
  **/
diff --git a/lib/media-server1-observer.c b/lib/media-server1-observer.c
index dd24c05..c93f133 100644
--- a/lib/media-server1-observer.c
+++ b/lib/media-server1-observer.c
@@ -55,6 +55,7 @@ G_DEFINE_TYPE (MS1Observer, ms1_observer, G_TYPE_OBJECT);
 
 /******************** PRIVATE API ********************/
 
+/* Callback invoked when a NameOwner is changed in dbus */
 static void
 name_owner_changed (DBusGProxy *proxy,
                     const gchar *name,
diff --git a/lib/media-server1-server-table.c b/lib/media-server1-server-table.c
index 1d5755c..b70440f 100644
--- a/lib/media-server1-server-table.c
+++ b/lib/media-server1-server-table.c
@@ -133,6 +133,8 @@ id_to_object_path (MS1Server *server,
   return object_path;
 }
 
+/* Returns a GPtrArray of object_paths obtained from list of hashtable
+   properties */
 static GPtrArray *
 get_object_paths (GList *items)
 {
@@ -150,6 +152,7 @@ get_object_paths (GList *items)
 
   return op;
 }
+
 /********************* PUBLIC API *********************/
 
 /**
@@ -179,7 +182,7 @@ ms1_server_new_properties_hashtable ()
  * @id: identifier value
  * @is_container: @TRUE if the @id identifies a container
  *
- * Sets the "Path" property. Mandatory property
+ * Sets the "Path" property.
  *
  * @id will be transformed in an object path
  **/
@@ -207,7 +210,7 @@ ms1_server_set_path (MS1Server *server,
  * @properties: a #GHashTable
  * @parent: parent value
  *
- * Sets the "parent" property. Mandatory property.
+ * Sets the "Parent" property.
  *
  * @parent will be transformed in an object path.
  **/
@@ -236,7 +239,7 @@ ms1_server_set_parent (MS1Server *server,
  * @properties: a #GHashTable
  * @display_name: display name value
  *
- * Sets the "display-name" property. Mandatory property.
+ * Sets the "DisplayName" property.
  **/
 void
 ms1_server_set_display_name (MS1Server *server,
@@ -258,7 +261,7 @@ ms1_server_set_display_name (MS1Server *server,
  * @properties: a #GHashTable
  * @type: type of item
  *
- * Sets the "type" property. Mandatory property.
+ * Sets the "Type" property.
  *
  * Tells what kind of object we are dealing with.
  **/
@@ -322,7 +325,7 @@ ms1_server_set_item_type (MS1Server *server,
  * @properties: a #GHashTable
  * @mime_type: mime type value
  *
- * Sets the "mime-type" property. Mandatory property for items.
+ * Sets the "MIMEType" property.
  **/
 void
 ms1_server_set_mime_type (MS1Server *server,
@@ -344,7 +347,7 @@ ms1_server_set_mime_type (MS1Server *server,
  * @properties: a #GHashTable
  * @artist: artist value
  *
- * Sets the "artist" property. Recommended property for items.
+ * Sets the "Artist" property.
  **/
 void
 ms1_server_set_artist (MS1Server *server,
@@ -366,7 +369,7 @@ ms1_server_set_artist (MS1Server *server,
  * @properties: a #GHashTable
  * @album: album value
  *
- * Sets the "album" property. Recommended property for items.
+ * Sets the "Album" property.
  **/
 void
 ms1_server_set_album (MS1Server *server,
@@ -388,7 +391,7 @@ ms1_server_set_album (MS1Server *server,
  * @properties: a #GHashTable
  * @date: date value
  *
- * Sets the "date" property. Recommended property for items.
+ * Sets the "Date" property.
  *
  * This date can be date of creation or release. Must be compliant to ISO-8601
  * and RFC-3339.
@@ -413,7 +416,7 @@ ms1_server_set_date (MS1Server *server,
  * @properties: a #GHashTable
  * @dlna_profile: DLNA value
  *
- * Sets the "dlna-profile" property. Optional property for items.
+ * Sets the "DLNAProfile" property.
  *
  * If you provide a value for this property, it will greatly help avoiding
  * guessing of its value by UPnP consumers.
@@ -438,7 +441,7 @@ ms1_server_set_dlna_profile (MS1Server *server,
  * @properties: a #GHashTable
  * @thumbnail: thumbnail identifier value
  *
- * Sets the "thumbnail" property. Optional property for video/image items.
+ * Sets the "Thumbnail" property.
  **/
 void
 ms1_server_set_thumbnail (MS1Server *server,
@@ -460,7 +463,7 @@ ms1_server_set_thumbnail (MS1Server *server,
  * @properties: a #GHashTable
  * @album_art: albumart identifier value
  *
- * Sets the "AlbumArt" property. Optional property for video/image items.
+ * Sets the "AlbumArt" property.
  **/
 void
 ms1_server_set_album_art (MS1Server *server,
@@ -482,7 +485,7 @@ ms1_server_set_album_art (MS1Server *server,
  * @properties: a #GHashTable
  * @genre: genre value
  *
- * Sets the "genre" property. Optional property for audio/music items.
+ * Sets the "Genre" property. Optional property for audio/music items.
  **/
 void
 ms1_server_set_genre (MS1Server *server,
@@ -504,7 +507,7 @@ ms1_server_set_genre (MS1Server *server,
  * @properties: a #GHashTable
  * @size: size value
  *
- * Sets the "size" property. Recommended property for items.
+ * Sets the "Size" property.
  *
  * It is the resource size in bytes.
  **/
@@ -526,7 +529,7 @@ ms1_server_set_size (MS1Server *server,
  * @properties: a #GHashTable
  * @duration: duration (in seconds) value
  *
- * Sets the "duration" property. Optional property for audio/video/music items.
+ * Sets the "Duration" property.
  **/
 void
 ms1_server_set_duration (MS1Server *server,
@@ -546,7 +549,7 @@ ms1_server_set_duration (MS1Server *server,
  * @properties: a #GHashTable
  * @bitrate: bitrate value
  *
- * Sets the "bitrate" property. Optional property for audio/video/music items.
+ * Sets the "Bitrate" property.
  **/
 void
 ms1_server_set_bitrate (MS1Server *server,
@@ -566,7 +569,7 @@ ms1_server_set_bitrate (MS1Server *server,
  * @properties: a #GHashTable
  * @sample_rate: sample rate value
  *
- * Sets the "sample-rate" property. Optional property for audio/video/music
+ * Sets the "SampleRate" property.
  * items.
  **/
 void
@@ -587,7 +590,7 @@ ms1_server_set_sample_rate (MS1Server *server,
  * @properties: a #GHashTable
  * @bits_per_sample: bits per sample value
  *
- * Sets the "bits-per-sample" property. Optional property for audio/video/music
+ * Sets the "BitsPerSample" property.
  * items.
  **/
 void
@@ -608,7 +611,7 @@ ms1_server_set_bits_per_sample (MS1Server *server,
  * @properties: a #GHashTable
  * @width: width (in pixels) value
  *
- * Sets the "width" property. Recommended property for video/image items.
+ * Sets the "Width" property.
  **/
 void
 ms1_server_set_width (MS1Server *server,
@@ -628,7 +631,7 @@ ms1_server_set_width (MS1Server *server,
  * @properties: a #GHashTable
  * @height: height (in pixels) value
  *
- * Sets the "height" property. Recommended property for video/image items.
+ * Sets the "Height" property.
  **/
 void
 ms1_server_set_height (MS1Server *server,
@@ -648,7 +651,7 @@ ms1_server_set_height (MS1Server *server,
  * @properties: a #GHashTable
  * @depth: color depth value
  *
- * Sets the "color-depth" property. Recommended property for video/image items.
+ * Sets the "ColorDepth" property.
  **/
 void
 ms1_server_set_color_depth (MS1Server *server,
@@ -668,7 +671,7 @@ ms1_server_set_color_depth (MS1Server *server,
  * @properties: a #GHashTable
  * @pixel_width: pixel width value
  *
- * Sets the "pixel-width" property. Optional property for video/image items.
+ * Sets the "PixelWidth" property.
  **/
 void
 ms1_server_set_pixel_width (MS1Server *server,
@@ -688,7 +691,7 @@ ms1_server_set_pixel_width (MS1Server *server,
  * @properties: a #GHashTable
  * @pixel_height: pixel height value
  *
- * Sets the "pixel-height" property. Optional property for video/image items.
+ * Sets the "PixelHeight" property.
  **/
 void
 ms1_server_set_pixel_height (MS1Server *server,
@@ -708,7 +711,7 @@ ms1_server_set_pixel_height (MS1Server *server,
  * @properties: a #GHashTable
  * @urls: @NULL-terminated array of URLs values
  *
- * Sets the "URLs" property. Mandatory property for items.
+ * Sets the "URLs" property.
  **/
 void
 ms1_server_set_urls (MS1Server *server,
@@ -739,7 +742,7 @@ ms1_server_set_urls (MS1Server *server,
  * @properties: a #GHashTable
  * @searchable: @TRUE if item is searchable
  *
- * Sets the "Searchable" property. Optional property for video/image items.
+ * Sets the "Searchable" property.
  **/
 void
 ms1_server_set_searchable (MS1Server *server,
@@ -759,7 +762,7 @@ ms1_server_set_searchable (MS1Server *server,
  * @properties: a #GHashTable
  * @items: a list of children
  *
- * Sets the "Items" property. Mandatory property for items.
+ * Sets the "Items" property.
  **/
 void
 ms1_server_set_items (MS1Server *server,
@@ -784,7 +787,7 @@ ms1_server_set_items (MS1Server *server,
  * @properties: a #GHashTable
  * @item_count: how many items have this container
  *
- * Sets the "ItemCount" property. Optional property for video/image items.
+ * Sets the "ItemCount" property.
  **/
 void
 ms1_server_set_item_count (MS1Server *server,
@@ -804,7 +807,7 @@ ms1_server_set_item_count (MS1Server *server,
  * @properties: a #GHashTable
  * @containers: a list of children
  *
- * Sets the "Containers" property. Mandatory property for items.
+ * Sets the "Containers" property.
  **/
 void
 ms1_server_set_containers (MS1Server *server,
@@ -829,7 +832,7 @@ ms1_server_set_containers (MS1Server *server,
  * @properties: a #GHashTable
  * @container_count: how many containers have this container
  *
- * Sets the "ContainerCount" property. Optional property for video/image items.
+ * Sets the "ContainerCount" property.
  **/
 void
 ms1_server_set_container_count (MS1Server *server,
diff --git a/lib/media-server1-server.c b/lib/media-server1-server.c
index 7f10b20..a3e01df 100644
--- a/lib/media-server1-server.c
+++ b/lib/media-server1-server.c
@@ -199,6 +199,8 @@ ptrarray_to_value (GPtrArray *array)
   return val;
 }
 
+/* Search for string needle in NULL-terminated string array strv; search is done
+   by comparing pointers */
 static gboolean
 lookup_in_strv (gchar **strv,
                 const gchar *needle)
@@ -212,6 +214,8 @@ lookup_in_strv (gchar **strv,
   return (strv[i] != NULL);
 }
 
+/* Searches for property in properties and return its value; if is not found,
+   then returns a default value for that property */
 static GValue *
 properties_lookup_with_default (GHashTable *properties,
                                 const gchar *property)
@@ -290,6 +294,7 @@ properties_lookup_with_default (GHashTable *properties,
   return ret_value;
 }
 
+/* Check if property makes sense in the interface */
 static gboolean
 is_property_valid (const gchar *interface,
                    const gchar *property)
@@ -471,6 +476,7 @@ add_gptrarray_as_as (DBusMessage *m,
   dbus_message_iter_close_container (iter, &sub_array);
 }
 
+/* Adds a GPtrArray as an array of object paths to dbus message */
 static void
 add_gptrarray_as_os (DBusMessage *m,
                      DBusMessageIter *iter,
@@ -497,6 +503,7 @@ add_gptrarray_as_os (DBusMessage *m,
   dbus_message_iter_close_container (iter, &sub_array);
 }
 
+/* Adds a pair <key, v> to dbus message */
 static void
 add_variant (DBusMessage *m,
              DBusMessageIter *iter,
@@ -547,6 +554,7 @@ add_variant (DBusMessage *m,
   }
 }
 
+/* Adds a GHashTable as a dictionary to dbus message */
 static void
 add_hashtable_as_dict (DBusMessage *m,
                        DBusMessageIter *iter,
@@ -587,6 +595,7 @@ add_hashtable_as_dict (DBusMessage *m,
   dbus_message_iter_close_container (iter, &sub_array);
 }
 
+/* Adds a GList as an array of pairs <string, variant> to dbus message */
 static void
 add_glist_as_array (DBusMessage *m,
                     DBusMessageIter *iter,
@@ -610,6 +619,7 @@ add_glist_as_array (DBusMessage *m,
   dbus_message_iter_close_container (iter, &sub_array);
 }
 
+/* Introspect message handler */
 static DBusHandlerResult
 handle_introspect_message (DBusConnection *c,
                            DBusMessage *m,
@@ -630,6 +640,7 @@ handle_introspect_message (DBusConnection *c,
   }
 }
 
+/* Get message handler */
 static DBusHandlerResult
 handle_get_message (DBusConnection *c,
                     DBusMessage *m,
@@ -665,6 +676,7 @@ handle_get_message (DBusConnection *c,
   }
 }
 
+/* GetAll message handler */
 static DBusHandlerResult
 handle_get_all_message (DBusConnection *c,
                         DBusMessage *m,
@@ -721,6 +733,7 @@ handle_get_all_message (DBusConnection *c,
   }
 }
 
+/* ListChildren message handler */
 static DBusHandlerResult
 handle_list_children_message (DBusConnection *c,
                               DBusMessage *m,
@@ -774,6 +787,7 @@ handle_list_children_message (DBusConnection *c,
   }
 }
 
+/* SearchObjects message handler */
 static DBusHandlerResult
 handle_search_objects_message (DBusConnection *c,
                                DBusMessage *m,
@@ -830,6 +844,7 @@ handle_search_objects_message (DBusConnection *c,
   }
 }
 
+/* Items interface handler */
 static DBusHandlerResult
 items_handler (DBusConnection *c,
                DBusMessage *m,
@@ -853,6 +868,7 @@ items_handler (DBusConnection *c,
   }
 }
 
+/* Containers interface handler */
 static DBusHandlerResult
 containers_handler (DBusConnection *c,
                     DBusMessage *m,
@@ -884,6 +900,7 @@ containers_handler (DBusConnection *c,
   }
 }
 
+/* Root category handler */
 static DBusHandlerResult
 root_handler (DBusConnection *c,
               DBusMessage *m,
@@ -951,6 +968,7 @@ ms1_server_dbus_register (MS1Server *server,
   return TRUE;
 }
 
+/* Unregister MS1Server from dbus */
 static void
 ms1_server_dbus_unregister (MS1Server *server,
                             const gchar *name)
@@ -990,6 +1008,7 @@ ms1_server_dbus_unregister (MS1Server *server,
   g_free (dbus_name);
 }
 
+/* Finalize function */
 static void
 ms1_server_finalize (GObject *object)
 {