[rygel] docs: Explain modules, plugins, and players a bit more

[Murray Cumming <murrayc src gnome org>]

commit 6eda5c61b06e73d90e67d21689bcdfe48e815462
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Oct 18 14:22:30 2012 +0200

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

 src/librygel-core/rygel-plugin.vala                |   10 ++++++++--
 src/librygel-core/rygel-root-device-factory.vala   |    7 +++++--
 src/librygel-core/rygel-root-device.vala           |   10 +++++++++-
 src/librygel-renderer/rygel-media-player.vala      |    6 ++++--
 .../rygel-media-renderer-plugin.vala               |    7 +++++--
 5 files changed, 31 insertions(+), 9 deletions(-)
---
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 =