core: Document WritableContainer some more

Provide more information on what exactly is expected and not expected from
WritableContainer implementations.

diff --git a/src/rygel/rygel-writable-container.vala b/src/rygel/rygel-writable-container.vala
index b020d44..6e075cb 100644 (file)
--- a/src/rygel/rygel-writable-container.vala
+++ b/src/rygel/rygel-writable-container.vala
@@ -29,9 +29,12 @@ using Gee;
  * creation, removal and editing of items directly under them. Currently, only
  * addition and removal is supported.
  *
- * In addition to implementing this interface, a writable container must also
- * provide one URI that points to a writable folder on a GIO supported
- * filesystem.
+ * In addition to implementing this interface, a writable container must also:
+ *
+ * 1. Provide one URI that points to a writable folder on a GIO supported
+ *    filesystem.
+ * 2. Monitor not only it's own URI but also that of it's child items, though
+ *    the latter is implied in the former if you use GIO for monitoring.
  */
 public interface Rygel.WritableContainer : MediaContainer {
     // List of classes that an object in this container could be created of
@@ -40,6 +43,9 @@ public interface Rygel.WritableContainer : MediaContainer {
     /**
      * Add a new item directly under this container.
      *
+     * This doesn't imply creation of file(s) pointed to by item's URI(s), that
+     * is handled for you.
+     *
      * @param item The item to add to this container
      * @param cancellable optional cancellable for this operation
      *
@@ -52,6 +58,9 @@ public interface Rygel.WritableContainer : MediaContainer {
     /**
      * Remove an item directly under this container that has the ID @id.
      *
+     * This doesn't imply deletion of file(s) pointed to by item's URI(s), that
+     * is handled for you.
+     *
      * @param item The ID of the item to remove from this container
      * @param cancellable optional cancellable for this operation
      *