[rygel] docs: Implement media engines: Add text.

[Murray Cumming <murrayc src gnome org>]

commit 117cf16290ff794c5dc8c8d41d2f1c57af86aa45
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Dec 18 09:42:58 2012 +0100

    docs: Implement media engines: Add text.
    
    Though this is mostly a duplicate of the RygelMediaEngine API docs.
    Still, it seems helpful to have it here.

 .../gtkdoc/implementing-media-engines.xml          |   20 ++++++++++++++++++++
 src/librygel-server/rygel-media-engine.vala        |    4 ++--
 .../simple/rygel-simple-data-source.vala           |    9 +++++++++
 .../simple/rygel-simple-media-engine.vala          |    7 +++++++
 4 files changed, 38 insertions(+), 2 deletions(-)
---
diff --git a/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml b/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
index cafabb2..c10b597 100644
--- a/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
+++ b/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
@@ -9,6 +9,26 @@
 <para>
 This library may be used to create Rygel media engines by 
 implementing the <link linkend="RygelMediaEngine">RygelMediaEngine</link> class.
+Rygel media engines contain knowledge about the streaming and (optionally) the 
+transcoding and seeking capabilites of the media library in use.</para>
+
+<para>The actual media engine used by Rygel at runtime is specified
+by the media-engine configuration key. For instance, in <literal>rygel.conf</literal>:
+<code>media-engine=librygel-media-engine-gst.so</code>
+</para>
+
+<para>Media engines should derive their own <link linkend="RygelDataSource">RygelDataSource</link>,
+returning an instance of it from create_data_source().</para>
+
+<para>Rygel itself provides two media engines:
 </para>
+<para>
+<orderedlist>
+<listitem><para><ulink url="http://git.gnome.org/browse/rygel/tree/src/media-engines/gstreamer";>gstreamer</ulink>: A media engine that uses GStreamer for transcoding and seeking.</para></listitem>
+<listitem><para><ulink url="http://git.gnome.org/browse/rygel/tree/src/media-engines/simple";>simple</ulink>: A media engine that uses no multimedia framework, and therefore offers no transcoding or time-based seeking.</para></listitem>
+</orderedlist>
+</para>
+
+<para>In addition, the external <ulink url="http://git.gnome.org/browse/rygel-gst-0-10-media-engine";>rygel-gst-0-10-media-engine</ulink> project provides a Rygel media engine that uses an older GStreamer version.</para>
 
 </section>
diff --git a/src/librygel-server/rygel-media-engine.vala b/src/librygel-server/rygel-media-engine.vala
index cc7f885..59fd79f 100644
--- a/src/librygel-server/rygel-media-engine.vala
+++ b/src/librygel-server/rygel-media-engine.vala
@@ -37,9 +37,9 @@ public errordomain Rygel.MediaEngineError {
  * For instance, in rygel.conf:
  * media-engine=librygel-media-engine-gst.so
  *
- * Media engines should also derive their own Rygel.DataSource,
+ * Media engines should also derive their own RygelDataSource,
  * returning an instance of it from create_data_source().
- **
+ *
  * See the
  * <link linkend="implementing-media-engines">Implementing Media Engines</link> section.
  */
diff --git a/src/media-engines/simple/rygel-simple-data-source.vala b/src/media-engines/simple/rygel-simple-data-source.vala
index 9ab1bdb..d0ccbd4 100644
--- a/src/media-engines/simple/rygel-simple-data-source.vala
+++ b/src/media-engines/simple/rygel-simple-data-source.vala
@@ -20,6 +20,15 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/**
+ * A simple data source for use with the simple media engine (RygelSimpleMediaEngine).
+ *
+ * This does not support time-base seeking with 
+ * rygel_data_source_start() because it does not
+ * use any multimedia framework. Therefore, calling start() with
+ * RYGEL_HTTP_SEEK_TYPE_TIME will fail with a 
+ * RYGEL_DATA_SOURCE_ERROR_SEEK_FAILED GError code,
+ */
 internal class Rygel.SimpleDataSource : DataSource, Object {
     private string uri;
     private Thread<void*> thread;
diff --git a/src/media-engines/simple/rygel-simple-media-engine.vala b/src/media-engines/simple/rygel-simple-media-engine.vala
index 00cba01..512a9f2 100644
--- a/src/media-engines/simple/rygel-simple-media-engine.vala
+++ b/src/media-engines/simple/rygel-simple-media-engine.vala
@@ -20,6 +20,13 @@
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  */
 
+/**
+ * The simple media engine does not use GStreamer or any other
+ * multimedia framework. Therefore its capabilities are limited.
+ *
+ * It does not support transcoding - get_transcoders() returns null.
+ * Also, its RygelSimpleDataSource does not support time-base seeking.
+ */
 internal class Rygel.SimpleMediaEngine : MediaEngine {
     private List<DLNAProfile> profiles = new List<DLNAProfile> ();