[rygel] server: Add/improve docs for MediaServer and co.

[Murray Cumming <murrayc src gnome org>]

commit a7c6d052a4a547a1c88020bc022801095b6729fb
Author: Murray Cumming <murrayc openismus com>
Date:   Thu Sep 13 12:15:43 2012 +0200

    server: Add/improve docs for MediaServer and co.

 src/librygel-server/rygel-media-container.vala  |   30 ++++++++++++-------
 src/librygel-server/rygel-media-server.vala     |   19 ++++++++++++
 src/librygel-server/rygel-simple-container.vala |   36 +++++++++++++++++++---
 3 files changed, 69 insertions(+), 16 deletions(-)
---
diff --git a/src/librygel-server/rygel-media-container.vala b/src/librygel-server/rygel-media-container.vala
index 535f628..47ff14e 100644
--- a/src/librygel-server/rygel-media-container.vala
+++ b/src/librygel-server/rygel-media-container.vala
@@ -2,6 +2,7 @@
  * Copyright (C) 2008 Zeeshan Ali <zeenix gmail com>.
  * Copyright (C) 2010 MediaNet Inh.
  * Copyright (C) 2010 Nokia Corporation.
+ * Copyright (C) 2012 Intel Corporation.
  *
  * Authors: Zeeshan Ali <zeenix gmail com>
  *          Sunil Mohan Adapa <sunil medhas org>
@@ -27,9 +28,12 @@ using GUPnP;
 using Gee;
 
 /**
- * Represents a container (folder) for media items and containers. Provides
- * basic serialization (to DIDLLiteWriter) implementation. Deriving classes
- * are supposed to provide working implementations of get_children.
+ * This is a container (folder) for media items and child containers.
+ *
+ * It provides a basic serialization implementation (to DIDLLiteWriter).
+ *
+ * A derived class should provide a working implementation of get_children
+ * and should emit the container_updated signal.
  */
 public abstract class Rygel.MediaContainer : MediaObject {
     public const string UPNP_CLASS = "object.container";
@@ -44,11 +48,15 @@ public abstract class Rygel.MediaContainer : MediaObject {
                                               "+upnp:originalTrackNumber," +
                                               "+dc:title";
 
+    /* TODO: When we implement ContentDirectory v4, this will be emitted also
+     * when child _items_ are updated.
+     */
+
     /**
-     * container_updated signal that is emitted if a child container under the
-     * tree of this container gets updated.
+     * The container_updated signal is emitted if a child container under the
+     * tree of this container has been updated.
      *
-     * @param container the container that just got updated.
+     * @param container The child container that has been updated.
      */
     public signal void container_updated (MediaContainer container);
 
@@ -126,8 +134,7 @@ public abstract class Rygel.MediaContainer : MediaObject {
                                                       throws Error;
 
     /**
-     * Recursively searches for media object with the given id in this
-     * container.
+     * Recursively searches this container for a media object with the given ID.
      *
      * @param id ID of the media object to search for
      * @param cancellable optional cancellable for this operation
@@ -139,10 +146,11 @@ public abstract class Rygel.MediaContainer : MediaObject {
                                                     throws Error;
 
     /**
-     * Method to be be called each time this container is updated (metadata
-     * changes for this container, items under it gets removed/added or their
-     * metadata changes etc).
+     * This method should be called each time this container is updated.
      *
+     * For instance, this should be called if there are metadata changes
+     * for this container, if items under it are removed or added, if
+     * there are metadata changes to items under it, etc.
      */
     public void updated () {
         this.update_id++;
diff --git a/src/librygel-server/rygel-media-server.vala b/src/librygel-server/rygel-media-server.vala
index cfd0e30..f48e48a 100644
--- a/src/librygel-server/rygel-media-server.vala
+++ b/src/librygel-server/rygel-media-server.vala
@@ -1,5 +1,6 @@
 /*
  * Copyright (C) 2012 Openismus GmbH.
+ * Copyright (C) 2012 Intel Corporation.
  *
  * Author: Jens Georg <jensg openismus com>
  *
@@ -24,7 +25,25 @@ internal class Plugin : Rygel.MediaServerPlugin {
     }
 }
 
+/**
+ * This class may be used to implement in-process UPnP-AV media servers.
+ *
+ * Call rygel_media_device_add_interface() on the RygelMediaServer to allow it
+ * to serve media via that network interface.
+ *
+ * See the standalone-server.c example.
+ */
 public class Rygel.MediaServer : MediaDevice {
+
+    /**
+     * Create a MediaServer to serve the media in the RygelMediaContainer.
+     * For instance, you might use a RygelSimpleContainer. Alternatively,
+     * you might use your own RygelMediaContainer implementation.
+     *
+     * Assuming that the RygelMediaContainer is correctly implemented,
+     * the RygelMediaServer will respond appropriately to changes in the
+     * RygelMediaContainer. 
+     */
     public MediaServer (string title, MediaContainer root_container) {
         base ();
         this.plugin = new global::Plugin (root_container);
diff --git a/src/librygel-server/rygel-simple-container.vala b/src/librygel-server/rygel-simple-container.vala
index bb7d18b..6f3fa3b 100644
--- a/src/librygel-server/rygel-simple-container.vala
+++ b/src/librygel-server/rygel-simple-container.vala
@@ -1,6 +1,7 @@
 /*
  * Copyright (C) 2009 Zeeshan Ali (Khattak) <zeeshanak gnome org>.
  * Copyright (C) 2009 Nokia Corporation.
+ * Copyright (C) 2012 Intel Corporation.
  *
  * Author: Zeeshan Ali (Khattak) <zeeshanak gnome org>
  *                               <zeeshan ali nokia com>
@@ -25,9 +26,8 @@
 using Gee;
 
 /**
- * A simple implementation of MediaContainer that keeps all MediaObjects
- * in memory. In order for it to be of any use, you must add children to
- * children ArrayList field.
+ * A simple implementation of RygelMediaContainer that keeps all RygelMediaObjects
+ * in memory. You should add children via rygel_simple_container_add_child_item().
  */
 public class Rygel.SimpleContainer : Rygel.MediaContainer,
                                      Rygel.SearchableContainer {
@@ -37,6 +37,13 @@ public class Rygel.SimpleContainer : Rygel.MediaContainer,
 
     public ArrayList<string> search_classes { get; set; }
 
+    /**
+     * Creates a child RygelSimpleContainer.
+     *
+     * @param id The ID of the item. This should be unique in the server.
+     * @param parent The parent of the container.
+     * @param title The title of the container. 
+     */
     public SimpleContainer (string          id,
                             MediaContainer? parent,
                             string          title) {
@@ -47,10 +54,20 @@ public class Rygel.SimpleContainer : Rygel.MediaContainer,
         this.search_classes = new ArrayList<string> ();
     }
 
+    /**
+     * Creates a RygelSimpleContainer as a root container.
+     *
+     * @param title The title of the container.
+     */
     public SimpleContainer.root (string title) {
         this ("0", null, title);
     }
 
+    /**
+     * Adds an item to the container.
+     *
+     * @param child The child item to add to the container.
+     */
     public void add_child_item (MediaItem child) {
         this.add_child (child);
     }
@@ -64,8 +81,10 @@ public class Rygel.SimpleContainer : Rygel.MediaContainer,
     }
 
     /**
-     * NOTE: This method only actually adds the child container to the hierarchy
-     * until it has any children to offer.
+     * Adds a child container to this container.
+     *
+     * The child container will only be added to the hierarchy if, or when,
+     * it contains some children.
      */
     public void add_child_container (MediaContainer child) {
         if (child is SearchableContainer) {
@@ -84,12 +103,19 @@ public class Rygel.SimpleContainer : Rygel.MediaContainer,
         }
     }
 
+    /**
+     * Removes the item from the container.
+     */
     public void remove_child (MediaObject child) {
         this.children.remove (child);
 
         this.child_count--;
     }
 
+    /**
+     * Removes all child items and child containers
+     * from the container.
+     */
     public void clear () {
         this.children.clear ();