Add documentation for decodebin2 that indicates that the API is still unstable.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-base-plugins-docs.sgml:
* docs/plugins/gst-plugins-base-plugins-sections.txt:
* docs/plugins/inspect/plugin-decodebin2.xml:
* gst/playback/gstdecodebin2.c: (gst_decode_bin_class_init):
Add documentation for decodebin2 that indicates that the API
is still unstable.

6 files changed, 116 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index 36c6f8477..1cf34eb65 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2007-03-02  Jan Schmidt  <thaytan@mad.scientist.com>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-base-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-base-plugins-sections.txt:
+	* docs/plugins/inspect/plugin-decodebin2.xml:
+	* gst/playback/gstdecodebin2.c: (gst_decode_bin_class_init):
+	Add documentation for decodebin2 that indicates that the API
+	is still unstable.
+
 2007-03-01  Jan Schmidt  <thaytan@mad.scientist.com>
 
 	* configure.ac:
diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index 36670161d..3ac163d49 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -101,6 +101,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/gst/ffmpegcolorspace/gstffmpegcolorspace.h \
 	$(top_srcdir)/gst/gdp/gstgdpdepay.h \
 	$(top_srcdir)/gst/gdp/gstgdppay.h \
+	$(top_srcdir)/gst/playback/gstdecodebin2.c \
 	$(top_srcdir)/gst/tcp/gstmultifdsink.h \
 	$(top_srcdir)/gst/tcp/gsttcpserversink.h \
 	$(top_srcdir)/gst/videorate/gstvideorate.h \
diff --git a/docs/plugins/gst-plugins-base-plugins-docs.sgml b/docs/plugins/gst-plugins-base-plugins-docs.sgml
index db405c16e..93e2df22b 100644
--- a/docs/plugins/gst-plugins-base-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-base-plugins-docs.sgml
@@ -29,6 +29,7 @@
     <xi:include href="xml/element-multifdsink.xml" />
     <xi:include href="xml/element-oggdemux.xml" />
     <xi:include href="xml/element-playbin.xml" />
+    <xi:include href="xml/element-decodebin2.xml" />
     <xi:include href="xml/element-tcpserversink.xml" />
     <xi:include href="xml/element-theoradec.xml" />
     <xi:include href="xml/element-theoraenc.xml" />
@@ -57,6 +58,7 @@
     <xi:include href="xml/plugin-audiotestsrc.xml" />
     <xi:include href="xml/plugin-cdparanoia.xml" />
     <xi:include href="xml/plugin-decodebin.xml" />
+    <xi:include href="xml/plugin-decodebin2.xml" />
     <xi:include href="xml/plugin-ffmpegcolorspace.xml" />
     <xi:include href="xml/plugin-gdp.xml" />
     <xi:include href="xml/plugin-gnomevfs.xml" />
diff --git a/docs/plugins/gst-plugins-base-plugins-sections.txt b/docs/plugins/gst-plugins-base-plugins-sections.txt
index 9b2925afc..aeeb47c21 100644
--- a/docs/plugins/gst-plugins-base-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-base-plugins-sections.txt
@@ -130,6 +130,12 @@ gst_clock_overlay_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-decodebin2</FILE>
+<TITLE>decodebin2</TITLE>
+GstDecodeBin2
+</SECTION>
+
+<SECTION>
 <FILE>element-ffmpegcolorspace</FILE>
 <TITLE>ffmpegcolorspace</TITLE>
 GstFFMpegCsp
diff --git a/docs/plugins/inspect/plugin-decodebin2.xml b/docs/plugins/inspect/plugin-decodebin2.xml
new file mode 100644
index 000000000..1b729f2ab
--- /dev/null
+++ b/docs/plugins/inspect/plugin-decodebin2.xml
@@ -0,0 +1,20 @@
+<plugin>
+  <name>decodebin2</name>
+  <description>decoder bin newer version</description>
+  <filename>../../gst/playback/.libs/libgstdecodebin2.so</filename>
+  <basename>libgstdecodebin2.so</basename>
+  <version>0.10.11.1</version>
+  <license>LGPL</license>
+  <source>gst-plugins-base</source>
+  <package>GStreamer Base Plug-ins CVS/prerelease</package>
+  <origin>Unknown package origin</origin>
+  <elements>
+    <element>
+      <name>decodebin2</name>
+      <longname>Decoder Bin</longname>
+      <class>Generic/Bin/Decoder</class>
+      <description>Autoplug and decode to raw media</description>
+      <author>Edward Hervey &lt;edward@fluendo.com&gt;</author>
+    </element>
+  </elements>
+</plugin>
\ No newline at end of file
diff --git a/gst/playback/gstdecodebin2.c b/gst/playback/gstdecodebin2.c
index 399c60dd4..68eebca13 100644
--- a/gst/playback/gstdecodebin2.c
+++ b/gst/playback/gstdecodebin2.c
@@ -19,7 +19,17 @@
 
 /**
  * SECTION:element-decodebin2
+ * @short_description: Next-generation automatic decoding bin
  *
+ * #GstBin that auto-magically constructs a decoding pipeline using available
+ * decoders and demuxers via auto-plugging.
+ *
+ * At this stage, decodebin2 is considered UNSTABLE. The API provided in the
+ * signals is expected to change in the near future. 
+ *
+ * To try out decodebin2, you can set the USE_DECODEBIN2 environment 
+ * variable (USE_DECODEBIN2=1 for example). This will cause playbin to use
+ * decodebin2 instead of the older decodebin for its internal auto-plugging.
  */
 
 #ifdef HAVE_CONFIG_H
@@ -51,6 +61,7 @@ GST_DEBUG_CATEGORY_STATIC (gst_decode_bin_debug);
 typedef struct _GstDecodeGroup GstDecodeGroup;
 typedef struct _GstDecodePad GstDecodePad;
 typedef struct _GstDecodeBin GstDecodeBin;
+typedef struct _GstDecodeBin GstDecodeBin2;
 typedef struct _GstDecodeBinClass GstDecodeBinClass;
 
 #define GST_TYPE_DECODE_BIN             (gst_decode_bin_get_type())
@@ -60,6 +71,11 @@ typedef struct _GstDecodeBinClass GstDecodeBinClass;
 #define GST_IS_DECODE_BIN(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_DECODE_BIN))
 #define GST_IS_DECODE_BIN_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_DECODE_BIN))
 
+/**
+ *  GstDecodeBin2:
+ *
+ *  The opaque #DecodeBin2 data structure
+ */
 struct _GstDecodeBin
 {
   GstBin bin;                   /* we extend GstBin */
@@ -310,27 +326,85 @@ gst_decode_bin_class_init (GstDecodeBinClass * klass)
   gobject_klass->set_property = GST_DEBUG_FUNCPTR (gst_decode_bin_set_property);
   gobject_klass->get_property = GST_DEBUG_FUNCPTR (gst_decode_bin_get_property);
 
+  /**
+   * GstDecodeBin2::new-decoded-pad:
+   * @pad: the newly created pad
+   * @islast: #TRUE if this is the last pad to be added. Deprecated.
+   *
+   * This signal gets emitted as soon as a new pad of the same type as one of
+   * the valid 'raw' types is added.
+   */
+
   gst_decode_bin_signals[SIGNAL_NEW_DECODED_PAD] =
       g_signal_new ("new-decoded-pad", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST,
       G_STRUCT_OFFSET (GstDecodeBinClass, new_decoded_pad), NULL, NULL,
       gst_play_marshal_VOID__OBJECT_BOOLEAN, G_TYPE_NONE, 2, GST_TYPE_PAD,
       G_TYPE_BOOLEAN);
+
+  /**
+   * GstDecodeBin2::removed-decoded-pad:
+   * @pad: the pad that was removed
+   *
+   * This signal is emitted when a 'final' caps pad has been removed.
+   */
+
   gst_decode_bin_signals[SIGNAL_REMOVED_DECODED_PAD] =
       g_signal_new ("removed-decoded-pad", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST,
       G_STRUCT_OFFSET (GstDecodeBinClass, removed_decoded_pad), NULL, NULL,
       gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
+
+  /**
+   * GstDecodeBin2::unknown-type:
+   * @pad: the new pad containing caps that cannot be resolved to a 'final' stream type.
+   * @caps: the #GstCaps of the pad that cannot be resolved.
+   *
+   * This signal is emitted when a pad for which there is no further possible
+   * decoding is added to the decodebin.
+   */
+
   gst_decode_bin_signals[SIGNAL_UNKNOWN_TYPE] =
       g_signal_new ("unknown-type", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstDecodeBinClass, unknown_type),
       NULL, NULL, gst_marshal_VOID__OBJECT_OBJECT, G_TYPE_NONE, 2,
       GST_TYPE_PAD, GST_TYPE_CAPS);
+
+  /**
+   * GstDecodeBin2::autoplug-continue:
+   * @caps: The #GstCaps found.
+   *
+   * This signal is emitted whenever decodebin2 finds a new stream. It is
+   * emitted before looking for any elements that can handle that stream.
+   *
+   * Returns: #TRUE if you wish decodebin2 to look for elements that can
+   * handle the given @caps. If #FALSE, those caps will be considered as
+   * final and the pad will be exposed as such (see 'new-decoded-pad'
+   * signal).
+   */
+
   gst_decode_bin_signals[SIGNAL_AUTOPLUG_CONTINUE] =
       g_signal_new ("autoplug-continue", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstDecodeBinClass, autoplug_continue),
       _gst_boolean_accumulator, NULL, gst_play_marshal_BOOLEAN__OBJECT,
       G_TYPE_BOOLEAN, 1, GST_TYPE_CAPS);
+
+  /**
+   * GstDecodeBin2::autoplug-sort:
+   * @caps: The #GstCaps.
+   * @factories: A #GList of possible #GstElementFactory to use.
+   *
+   * This signal is emitted once decodebin2 has found all the possible
+   * #GstElementFactory that can be used to handle the given @caps.
+   *
+   * UNSTABLE API. Will change soon.
+   *
+   * Returns: #TRUE if you wish decodebin2 to start trying to decode
+   * the given @caps with the list of factories. #FALSE if you do not want
+   * these #GstCaps, if so the pad will be exposed as unknown (see
+   * 'unknown-type' signal).
+   */
+
   gst_decode_bin_signals[SIGNAL_AUTOPLUG_SORT] =
       g_signal_new ("autoplug-sort", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstDecodeBinClass, autoplug_sort),
@@ -747,7 +821,7 @@ any_caps:
 }
 
 
-/** connect_pad:
+/* connect_pad:
  *
  * Try to connect the given pad to an element created from one of the factories,
  * and recursively.
@@ -1859,7 +1933,7 @@ source_pad_event_probe (GstPad * pad, GstEvent * event, GstDecodePad * dpad)
   return TRUE;
 }
 
-/** gst_decode_pad_new:
+/*gst_decode_pad_new:
  *
  * Creates a new GstDecodePad for the given pad.
  * If block is TRUE, Sets the pad blocking asynchronously
@@ -1961,7 +2035,7 @@ remove_fakesink (GstDecodeBin * decode_bin)
  * convenience functions
  *****/
 
-/** find_sink_pad
+/* find_sink_pad
  *
  * Returns the first sink pad of the given element, or NULL if it doesn't have
  * any.