playback: Flesh out docs a bit for new elements

Add some more text to the docs for urisourcebin,
parsebin, decodebin3 and playbin3, including a warning
that they are unstable API for now

gst/playback/gstdecodebin3.c

@@ -34,6 +34,41 @@
 #include "gstplay-enum.h"
 #include "gstrawcaps.h"
 
+/**
+ * SECTION:element-decodebin3
+ *
+ * #GstBin that auto-magically constructs a decoding pipeline using available
+ * decoders and demuxers via auto-plugging. The output is raw audio, video
+ * or subtitle streams.
+ *
+ * decodebin3 differs from the previous decodebin (decodebin2) in important ways:
+ *
+ * <itemizedlist>
+ * <listitem>
+ * supports publication and selection of stream information via
+ * GstStreamCollection messages and #GST_EVENT_SELECT_STREAM events.
+ * </listitem>
+ * <listitem>
+ * dynamically switches stream connections internally, and
+ * reuses decoder elements when stream selections change, so that in
+ * the normal case it maintains 1 decoder of each type (video/audio/subtitle)
+ * and only creates new elements when streams change and an existing decoder
+ * is not capable of handling the new format.
+ * </listitem>
+ * <listitem>
+ * supports multiple input pads for the parallel decoding of auxilliary streams
+ * not muxed with the primary stream.
+ * </listitem>
+ * <listitem>
+ * does not handle network stream buffering. decodebin3 expects that network stream
+ * buffering is handled upstream, before data is passed to it.
+ * </listitem>
+ * </itemizedlist>
+ *
+ * <emphasis>decodebin3 is still experimental API and a technology preview.
+ * Its behaviour and exposed API is subject to change.</emphasis>
+ *
+ */
 
 /**
  * Global design

gst/playback/gstparsebin.c

@@ -31,6 +31,14 @@
  * #GstBin that auto-magically constructs a parsing pipeline
  * using available parsers and demuxers via auto-plugging.
  *
+ * parsebin unpacks the contents of the input stream to the
+ * level of parsed elementary streams, but unlike decodebin
+ * it doesn't connect decoder elements. The output pads
+ * produce packetised encoded data with timestamps where possible,
+ * or send missing-element messages where not.
+ *
+ * <emphasis>parsebin is still experimental API and a technology preview.
+ * Its behaviour and exposed API is subject to change.</emphasis>
  */
 
 /* Implementation notes:

gst/playback/gstplaybin3.c

@@ -24,16 +24,24 @@
 /**
  * SECTION:element-playbin3
  *
- * Playbin3 provides a stand-alone everything-in-one abstraction for an
+ * playbin3 provides a stand-alone everything-in-one abstraction for an
- * audio and/or video player.
+ * audio and/or video player. It differs from the previous playbin (playbin2)
+ * by supporting publication and selection of available streams via the
+ * #GstStreamCollection message and #GST_EVENT_SELECT_STREAMS event API.
  *
- * Playbin3 can handle both audio and video files and features
+ * <emphasis>playbin3 is still experimental API and a technology preview.
+ * Its behaviour and exposed API is subject to change.</emphasis>
+ *
+ * playbin3 can handle both audio and video files and features
  * <itemizedlist>
  * <listitem>
  * automatic file type recognition and based on that automatic
  * selection and usage of the right audio/video/subtitle demuxers/decoders
  * </listitem>
  * <listitem>
+ * auxilliary files - such as external subtitles and audio tracks
+ * </listitem>
+ * <listitem>
  * visualisations for audio files
  * </listitem>
  * <listitem>
@@ -60,7 +68,7 @@
  * <refsect2>
  * <title>Usage</title>
  * <para>
- * A playbi3n element can be created just like any other element using
+ * A playbin element can be created just like any other element using
  * gst_element_factory_make(). The file/URI to play should be set via the #GstPlayBin3:uri
  * property. This must be an absolute URI, relative file paths are not allowed.
  * Example URIs are file:///home/joe/movie.avi or http://www.joedoe.com/foo.ogg
@@ -913,10 +921,26 @@ gst_play_bin3_class_init (GstPlayBin3Class * klass)
       g_param_spec_object ("audio-filter", "Audio filter",
           "the audio filter(s) to apply, if possible",
           GST_TYPE_ELEMENT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+  /**
+   * GstPlayBin3:video-sink
+   *
+   * Get or set the video sink to use for video output. If set to
+   * NULL, one will be auto-selected. To disable video entirely, unset
+   * the VIDEO flag in the #GstPlayBin3:flags property.
+   *
+   */
   g_object_class_install_property (gobject_klass, PROP_VIDEO_SINK,
       g_param_spec_object ("video-sink", "Video Sink",
           "the video output element to use (NULL = default sink)",
           GST_TYPE_ELEMENT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+  /**
+   * GstPlayBin3:audio-sink
+   *
+   * Get or set the audio sink to use for audio output. If set to
+   * NULL, one will be auto-selected. To disable audio entirely, unset
+   * the AUDIO flag in the #GstPlayBin3:flags property.
+   *
+   */
   g_object_class_install_property (gobject_klass, PROP_AUDIO_SINK,
       g_param_spec_object ("audio-sink", "Audio Sink",
           "the audio output element to use (NULL = default sink)",

gst/playback/gsturisourcebin.c

@@ -21,9 +21,16 @@
 /**
  * SECTION:element-urisourcebin
  *
- * Handles selecting a URI source element and potentially buffering/download
+ * urisourcebin is an element for accessing URIs in a uniform manner.
- * for network sources. Produces one or more source pads for feeding to
+ *
- * decoding chains or decodebin.
+ * It handles selecting a URI source element and potentially download
+ * buffering for network sources. It roduces one or more source pads,
+ * depending on the input source, for feeding to decoding chains or decodebin.
+ *
+ * The main configuration is via the #GstURISourceBin:uri property.
+ *
+ * <emphasis>urisourcebin is still experimental API and a technology preview.
+ * Its behaviour and exposed API is subject to change.</emphasis>
  */
 
 /* FIXME 0.11: suppress warnings for deprecated API such as GValueArray