From: Murray Cumming <murrayc@murrayc.com>
Date: Thu, 18 Oct 2012 12:22:30 +0000 (+0200)
Subject: docs: Explain modules, plugins, and players a bit more
X-Git-Tag: RYGEL_0_17_1~33
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6eda5c61b06e73d90e67d21689bcdfe48e815462;p=profile%2Fivi%2Frygel.git

docs: Explain modules, plugins, and players a bit more
---

diff --git a/src/librygel-core/rygel-plugin.vala b/src/librygel-core/rygel-plugin.vala
index f170a79..d8259cc 100644
--- a/src/librygel-core/rygel-plugin.vala
+++ b/src/librygel-core/rygel-plugin.vala
@@ -25,8 +25,14 @@ using Gee;
 using GUPnP;
 
 /**
- * Represents a Rygel plugin. Plugins are supposed to provide an object of this
- * class or a subclass.
+ * This represents a Rygel plugin.
+ *
+ * Plugin libraries should provide an object of this
+ * class or a subclass in their module_init() function.
+ *
+ * It is generally convenient to derive from 
+ * #RygelMediaRendererPlugin from librygel-renderer,
+ * or from #RygelMediaServerPlugin from librygel-server.
  */
 public class Rygel.Plugin : GUPnP.ResourceFactory {
     private static const string PNG_EXT = "png";
diff --git a/src/librygel-core/rygel-root-device-factory.vala b/src/librygel-core/rygel-root-device-factory.vala
index a9a304f..bd8ac37 100644
--- a/src/librygel-core/rygel-root-device-factory.vala
+++ b/src/librygel-core/rygel-root-device-factory.vala
@@ -33,8 +33,11 @@ public errordomain RootDeviceFactoryError {
 }
 
 /**
- * Factory for RootDevice objects. Give it a plugin and it will create a
- * Root device for that.
+ * This is a factory to create #RygelRootDevice objects for
+ * a given UPnP context.
+ *
+ * Call rygel_root_device_factory_create() with a plugin
+ * to create a root device for the plugin.
  */
 public class Rygel.RootDeviceFactory {
     public GUPnP.Context context;
diff --git a/src/librygel-core/rygel-root-device.vala b/src/librygel-core/rygel-root-device.vala
index d07b8ce..b3d5385 100644
--- a/src/librygel-core/rygel-root-device.vala
+++ b/src/librygel-core/rygel-root-device.vala
@@ -27,7 +27,15 @@ using GUPnP;
 using Gee;
 
 /**
- * Represents a Root device.
+ * This represents a UPnP root device.
+ *
+ * Each Rygel plugin corresponds to one UPnP root device, so
+ * each #RygelPlugin corresponds to one #RygelRootDevice.
+ *
+ * Rygel creates the #RygelRootDevice by calling
+ * rygel_root_device_factory_create() with the plugin,
+ * having first instantiated the #RygelRootDeviceFactory
+ * for a #GUPnPContext.
  */
 public class Rygel.RootDevice: GUPnP.RootDevice {
     public ArrayList<ServiceInfo> services { get; internal set; }   /* Services we implement */
diff --git a/src/librygel-renderer/rygel-media-player.vala b/src/librygel-renderer/rygel-media-player.vala
index 6017caa..b72138f 100644
--- a/src/librygel-renderer/rygel-media-player.vala
+++ b/src/librygel-renderer/rygel-media-player.vala
@@ -23,9 +23,11 @@
  */
 
 /**
- * Interface for mapping AVTransport:2 methods to the specific implementation.
+ * This interface maps UPnP AVTransport:2 methods to the plugin's specific implementation.
  *
- * This class is useful only when implementing Rygel plugins.
+ * This interface is useful only when implementing Rygel plugins.
+ * Instance of this interface are retrieved from 
+ * rygel_media_renderer_plugin_get_player().
  */
 public interface Rygel.MediaPlayer : GLib.Object {
     public abstract string playback_state { owned get; set; }
diff --git a/src/librygel-renderer/rygel-media-renderer-plugin.vala b/src/librygel-renderer/rygel-media-renderer-plugin.vala
index 800d4fb..0e36d2e 100644
--- a/src/librygel-renderer/rygel-media-renderer-plugin.vala
+++ b/src/librygel-renderer/rygel-media-renderer-plugin.vala
@@ -23,9 +23,12 @@
  */
 
 /**
- * Base class for every Rygel UPnP renderer plugin.
+ * This is the base class for every Rygel UPnP renderer plugin.
  *
- * This class is useful only when implementing Rygel plugins.
+ * This class is useful when implementing Rygel renderer plugins.
+ *
+ * Renderer plugins should also implement their own #RygelMediaPlayer
+ * and return an instance of it from their get_player() implementation.
  */
 public class Rygel.MediaRendererPlugin : Rygel.Plugin {
     private static const string MEDIA_RENDERER_DESC_PATH =