[rygel] renderer: Add MediaPlayer documentation

[Murray Cumming <murrayc src gnome org>]

commit 6c937ac5cd77574e049aab6bf282adb9a8389673
Author: Murray Cumming <murrayc murrayc com>
Date:   Mon Oct 22 13:46:34 2012 +0200

    renderer: Add MediaPlayer documentation

 src/librygel-renderer/rygel-media-player.vala |   41 +++++++++++++++++++++++-
 1 files changed, 39 insertions(+), 2 deletions(-)
---
diff --git a/src/librygel-renderer/rygel-media-player.vala b/src/librygel-renderer/rygel-media-player.vala
index b72138f..81a0acd 100644
--- a/src/librygel-renderer/rygel-media-player.vala
+++ b/src/librygel-renderer/rygel-media-player.vala
@@ -25,20 +25,44 @@
 /**
  * This interface maps UPnP AVTransport:2 methods to the plugin's specific implementation.
  *
- * This interface is useful only when implementing Rygel plugins.
- * Instance of this interface are retrieved from 
+ * This interface is useful only when implementing Rygel renderer plugins.
+ * Instances of this interface are retrieved from
  * rygel_media_renderer_plugin_get_player().
  */
 public interface Rygel.MediaPlayer : GLib.Object {
+
+    /* TODO: Use an enum instead. */
+    /// The state as a UPnP playback state string such as PAUSED_PLAYBACK, "STOPPED" or "PLAYING"
     public abstract string playback_state { owned get; set; }
+
+    /// The URI of the current media.
     public abstract string? uri { owned get; set; }
+
+    /// The volume as a value between 0.0 and 1.0
     public abstract double volume { get; set; }
 
     /// Duration of the current media in microseconds
     public abstract int64 duration { get; }
+
+    /**
+     * A DIDLLite document describing the current media URI or null.
+     * The document is either the one received from a UPnP control point or
+     * one generated by the implementing class.
+     */
     public abstract string? metadata { owned get; set; }
+
+    /// The mime-type of the currently-playing media
     public abstract string? mime_type { owned get; set; }
+
+    /**
+     * The contents of the contentFeatures.dlna.org HTTP header,
+     * containing the 4th field of the protocol info for the current
+     * media URI. Or null if the header does not exist or the media
+     * does not have DLNA information attached.
+     */
     public abstract string? content_features { owned get; set; }
+
+    /// The duration as a human-readable string, in HH:MM:SS format
     public string duration_as_str {
         owned get {
             return TimeUtils.time_to_string (duration);
@@ -47,13 +71,26 @@ public interface Rygel.MediaPlayer : GLib.Object {
 
     /// Position in the current media in microseconds
     public abstract int64 position { get; }
+
+    /// The position as a human-readable string, in HH:MM:SS format
     public string position_as_str {
         owned get {
             return TimeUtils.time_to_string (position);
         }
     }
 
+    /**
+     * Seek to a point in the current media that is
+     * this many microseconds after the start.
+     */
     public abstract bool seek (int64 time);
+
+    /**
+     * Return the protocols supported by this renderer,
+     * such as "http-get" and "rtsp".
+     */
     public abstract string[] get_protocols ();
+
+    /// Return the MIME types supported by this renderer.
     public abstract string[] get_mime_types ();
 }