[rygel] docs: librygel-server: Document RygelTrackableContainer

[Murray Cumming <murrayc src gnome org>]

commit 98a70739d25862bfeb645f68b806c8e9b725790b
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Jan 17 12:50:29 2013 +0100

    docs: librygel-server: Document RygelTrackableContainer

 .../gtkdoc/librygel-server-docs.xml                |    1 +
 src/librygel-server/rygel-trackable-container.vala |   38 +++++++++++++++++++-
 2 files changed, 38 insertions(+), 1 deletions(-)
---
diff --git a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
index 8aa6199..1936857 100644
--- a/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
+++ b/doc/reference/librygel-server/gtkdoc/librygel-server-docs.xml
@@ -48,6 +48,7 @@
     <xi:include href="xml/rygel-simple-container.xml"/>
     <xi:include href="xml/rygel-subtitle.xml"/>
     <xi:include href="xml/rygel-thumbnail.xml"/>
+    <xi:include href="xml/rygel-trackable-container.xml"/>
     <xi:include href="xml/rygel-transcode-manager.xml"/>
     <xi:include href="xml/rygel-transcoder.xml"/>
     <xi:include href="xml/rygel-video-item.xml"/>
diff --git a/src/librygel-server/rygel-trackable-container.vala b/src/librygel-server/rygel-trackable-container.vala
index e22feb4..c4a5b64 100644
--- a/src/librygel-server/rygel-trackable-container.vala
+++ b/src/librygel-server/rygel-trackable-container.vala
@@ -18,6 +18,18 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/**
+ * The base class for containers that provide automatic change tracking.
+ *
+ * Derived classes should implement the add_child() and remove_child()
+ * virtual functions to keep track of child items and child containers.
+ *
+ * Rygel server plugins (See #RygelMediaServer) may then call
+ * rygel_trackable_container_add_child_tracked() and
+ * rygel_trackable_container_remove_child_tracked() to add and remove
+ * items, which will then cause the #RygelContainer::container_updated signal
+ * to be emitted.
+ */
 public interface Rygel.TrackableContainer : Rygel.MediaContainer {
     public async void clear () {
         try {
@@ -33,8 +45,20 @@ public interface Rygel.TrackableContainer : Rygel.MediaContainer {
         }
     }
 
+    /**
+     * Derived classes should implement this, keeping track
+     * of the child item or child container.
+     * See the remove_child() virtual function.
+     */
     public abstract async void add_child (MediaObject object);
 
+    /**
+     * Add a child object, emitting the #RygelContainer::container_updated signal
+     * with the object.
+     * @see rygel_trackable_object_remove_child_tracked()
+     *
+     * @param object The child item or child container to be added.
+     */
     public async void add_child_tracked (MediaObject object) {
         yield this.add_child (object);
 
@@ -48,8 +72,20 @@ public interface Rygel.TrackableContainer : Rygel.MediaContainer {
         }
     }
 
+    /**
+     * Derived classes should implement this, removing the
+     * child item or child container from its set of objects.
+     * See the add_child() virtual function.
+     */
     public abstract async void remove_child (MediaObject object);
 
+    /**
+     * Add a child object, emitting the #RygelContainer::container_updated signal
+     * with the object.
+     * @see rygel_trackable_object_add_child_tracked()
+     *
+     * @param object The child item or child container to be added.
+     */
     public async void remove_child_tracked (MediaObject object) {
         // We need to descend into this to get the proper events
         if (object is TrackableContainer) {
@@ -90,7 +126,7 @@ public interface Rygel.TrackableContainer : Rygel.MediaContainer {
     public virtual void set_service_reset_token (string token) {}
 
     /**
-     * Query the current system update id.
+     * Query the current system update ID.
      * This should be overriden by the root container of the back-end
      * implementation.
      *