[rygel] docs: RygelMediaEngine: More hints about optional features.

[Murray Cumming <murrayc src gnome org>]

commit 140d0b057eba813d89db740ac7d20ac8d35085f3
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Jan 7 12:00:59 2013 +0100

    docs: RygelMediaEngine: More hints about optional features.
    
    Mention the external C example and describe more about
    get_transcoders() and get_dlna_profiles().

 .../gtkdoc/implementing-media-engines.xml          |    8 +++++---
 src/librygel-server/rygel-media-engine.vala        |    5 ++++-
 .../gstreamer/rygel-gst-media-engine.vala          |    8 ++++++++
 3 files changed, 17 insertions(+), 4 deletions(-)
---
diff --git a/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml b/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
index c10b597..109eea3 100644
--- a/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
+++ b/doc/reference/librygel-server/gtkdoc/implementing-media-engines.xml
@@ -17,8 +17,10 @@ by the media-engine configuration key. For instance, in <literal>rygel.conf</lit
 <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>A media engines should derive its own <link linkend="RygelDataSource">RygelDataSource</link>,
+returning an instance of it from its create_data_source() implementation.</para>
+
+<para>Optionally, a derived RygelMediaEngine may implement the get_dlna_profiles() and get_transcoders() virtual functions.</para>
 
 <para>Rygel itself provides two media engines:
 </para>
@@ -29,6 +31,6 @@ returning an instance of it from create_data_source().</para>
 </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>
+<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 and is an example of an external Rygel media-engine implemented in C.</para>
 
 </section>
diff --git a/src/librygel-server/rygel-media-engine.vala b/src/librygel-server/rygel-media-engine.vala
index ebfe0dc..49a26a3 100644
--- a/src/librygel-server/rygel-media-engine.vala
+++ b/src/librygel-server/rygel-media-engine.vala
@@ -71,7 +71,10 @@ public abstract class Rygel.MediaEngine : GLib.Object {
 
     /**
      * Get a list of the DLNA profiles that are supported by this media
-     * engine.
+     * engine when calling rygel_media_engine_create_data_source().
+     *
+     * Other DLNA profiles may be supported as transcoding targets -
+     * see rygel_media_engine_get_transcoders().
      *
      * @return A list of #RygelDLNAProfile<!-- -->s
      */
diff --git a/src/media-engines/gstreamer/rygel-gst-media-engine.vala b/src/media-engines/gstreamer/rygel-gst-media-engine.vala
index de7bfe8..f2555df 100644
--- a/src/media-engines/gstreamer/rygel-gst-media-engine.vala
+++ b/src/media-engines/gstreamer/rygel-gst-media-engine.vala
@@ -40,11 +40,19 @@ public class Rygel.GstMediaEngine : Rygel.MediaEngine {
         Gst.init (ref args);
         gst_preset_set_app_dir (PRESET_DIR);
 
+        /* Get the possible DLNA profiles
+         * to add to the list of DLNA profiles supported by
+         * this media engine, for get_dlna_profiles():
+         */
         var discoverer = new GUPnPDLNA.Discoverer ((ClockTime) SECOND,
                                                    true,
                                                    false);
         foreach (var profile in discoverer.list_profiles ()) {
             var p = new DLNAProfile (profile.name, profile.mime);
+
+            /* TODO: Check that we (via GStreamer) really support this profile
+             * instead of just claiming to support everything.
+             */
             this.dlna_profiles.prepend (p);
         }
         this.dlna_profiles.prepend (new DLNAProfile ("DIDL_S", "text/xml"));