[rygel] server: Improve MediaEngine documentation.

[Murray Cumming <murrayc src gnome org>]

commit ddeb040b7b7c6578b652fbd63dcbdd316a40a12a
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Oct 16 12:10:55 2012 +0200

    server: Improve MediaEngine documentation.

 src/librygel-server/rygel-data-source.vala  |   18 ++++++++++--------
 src/librygel-server/rygel-media-engine.vala |   13 +++++++++++--
 2 files changed, 21 insertions(+), 10 deletions(-)
---
diff --git a/src/librygel-server/rygel-data-source.vala b/src/librygel-server/rygel-data-source.vala
index f45e7fe..07dfdef 100644
--- a/src/librygel-server/rygel-data-source.vala
+++ b/src/librygel-server/rygel-data-source.vala
@@ -26,14 +26,16 @@ public errordomain Rygel.DataSourceError {
 }
 
 /**
- * Interface for all data streams from a media engine. The data source is
- * responsible for providing the streamable byte-stream via its data_available
- * signal. End-of-stream is signalled through the done signal, while errors
- * are signalled by using the error signal.
+ * Interface for all data streams provided by a #RygelMediaEngine.
  *
- * # The only required URI scheme is file:/""/
- * # A DataSource should be able to stream any kind of binary data, regardless
- * of the format
+ * The data source is responsible for providing the streamable byte-stream
+ * via its data_available signal. End-of-stream is signalled by the 
+ * done signal, while errors are signalled by the error signal.
+ *
+ * Implementations should fulfil at least these requirements:
+ *
+ *  # It should support at least the file:/''''/ URI scheme.
+ *  # It should be able to stream any kind of binary data, regardless of the format.
  */
 public interface Rygel.DataSource : GLib.Object {
     /**
diff --git a/src/librygel-server/rygel-media-engine.vala b/src/librygel-server/rygel-media-engine.vala
index 46a40ae..97e7746 100644
--- a/src/librygel-server/rygel-media-engine.vala
+++ b/src/librygel-server/rygel-media-engine.vala
@@ -48,8 +48,17 @@ public errordomain Rygel.MediaEngineError {
 }
 
 /**
- * Base class for the media engine that will contain knowledge about streaming
- * and transcoding capabilites of the media library in use.
+ * This is the base class for media engines that contain knowledge about 
+ * streaming and transcoding capabilites of the media library in use.
+ *
+ * See, for instance, Rygel's "gstreamer" and "simple" media engines.
+ * The actual media engine used by Rygel at runtime is specified
+ * by the media-engine configuration key/
+ * For instance, in rygel.conf:
+ * media-engine=librygel-media-engine-gst.so
+ *
+ * Media engines should also derive their own Rygel.DataSource,
+ * returning an instance of it from create_data_source().
  */
 public abstract class Rygel.MediaEngine : GLib.Object {
     private static MediaEngine instance;