diff --git a/ChangeLog b/ChangeLog
index 0ddf9c6dc2..90911e2df8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2007-11-09  Wim Taymans  <wim.taymans@gmail.com>
+
+	* docs/design/design-decodebin.txt:
+	* gst/playback/gstdecodebin2.c: (analyze_new_pad):
+	Update some more docs and comments.
+
 2007-11-06  Tim-Philipp Müller  <tim at centricular dot net>
 
 	Patch by: Sebastien Moutte  <sebastien moutte net>
diff --git a/docs/design/design-decodebin.txt b/docs/design/design-decodebin.txt
index cd23727569..34919455df 100644
--- a/docs/design/design-decodebin.txt
+++ b/docs/design/design-decodebin.txt
@@ -43,29 +43,40 @@ fine-tune the process.
 
   _ 'autoplug-continue' :
 
-    gboolean user_function (GstElement * decodebin, GstCaps * caps)
+    gboolean user_function (GstElement * decodebin, GstPad *pad, GstCaps * caps)
 
     This signal is fired at the very beginning with the source pad GstCaps. If
   the callback returns TRUE, the process continues normally. If the callback
   returns FALSE, then the GstCaps are considered as a target caps and the
   autoplugging process stops.
 
-  - 'autoplug-sort' :
+  - 'autoplug-factories' :
 
-    gboolean user_function (GstElement * decodebin, GstCaps * caps, GList
-    **list)
+    GValueArray user_function (GstElement* decodebin, GstPad* pad, 
+         GstCaps* caps);
+
+    Get a list of elementfactories for @pad with @caps. This function is used to
+    instruct decodebin2 of the elements it should try to autoplug. The default
+    behaviour when this function is not overridern is to get all elements that
+    can handle @caps from the registry sorted by rank.
+
+  - 'autoplug-select' :
+
+    gint user_function (GstElement* decodebin, GstPad* pad, GstCaps* caps,
+                GValueArray* factories);
 
     This signal is fired once autoplugging has got a list of compatible
   GstElementFactory. The signal is emitted with the GstCaps of the source pad
-  and a pointer on the GList* of compatible factories.
+  and a pointer on the GValueArray of compatible factories.
 
-    The callback can re-order the given list of factories in order to put the
-  preferred factory at the beginning of the GList *.
+    The callback should return the index of the elementfactory in @factories
+    that should be tried next.
 
-    If the callback returns TRUE, then the autoplugging process will create an
-  element to link using the first GstElementFactory of that list. If the
-  callback returns FALSE, then the autoplugging process will stop as if no
-  compatible factories was found.
+    If the callback returns -1, the autoplugging process will stop as if no
+  compatible factories were found.
+
+  The default implementation of this function will try to autoplug the first
+  factory of the list.
 
 * Target Caps
 
diff --git a/gst/playback/gstdecodebin2.c b/gst/playback/gstdecodebin2.c
index 56b8ed6f1e..33984ee7c7 100644
--- a/gst/playback/gstdecodebin2.c
+++ b/gst/playback/gstdecodebin2.c
@@ -838,6 +838,18 @@ static void no_more_pads_cb (GstElement * element, GstDecodeBin * dbin);
 
 static GstDecodeGroup *get_current_group (GstDecodeBin * dbin);
 
+/* called when a new pad is discovered. It will perform some basic actions
+ * before trying to link something to it.
+ *
+ *  - Check the caps, don't do anything when there are no caps or when they have
+ *    no good type.
+ *  - signal AUTOPLUG_CONTINUE to check if we need to continue autoplugging this
+ *    pad.
+ *  - if the caps are non-fixed, setup a handler to continue autoplugging when
+ *    the caps become fixed (connect to notify::caps).
+ *  - get list of factories to autoplug.
+ *  - continue autoplugging to one of the factories.
+ */
 static void
 analyze_new_pad (GstDecodeBin * dbin, GstElement * src, GstPad * pad,
     GstCaps * caps, GstDecodeGroup * group)
@@ -869,7 +881,8 @@ analyze_new_pad (GstDecodeBin * dbin, GstElement * src, GstPad * pad,
   if (!gst_caps_is_fixed (caps))
     goto non_fixed;
 
-  /* 1.c else if there's no compatible factory goto unknown_type */
+  /* 1.c else get the factories and if there's no compatible factory goto
+   * unknown_type */
   g_signal_emit (G_OBJECT (dbin),
       gst_decode_bin_signals[SIGNAL_AUTOPLUG_FACTORIES], 0, pad, caps,
       &factories);
@@ -878,10 +891,10 @@ analyze_new_pad (GstDecodeBin * dbin, GstElement * src, GstPad * pad,
     goto unknown_type;
   }
 
-  /* 1.d else goto pad_is_valid */
+  /* 1.d else continue autoplugging something from the list. */
   GST_LOG_OBJECT (pad, "Let's continue discovery on this pad");
-
   connect_pad (dbin, src, pad, caps, factories, group);
+
   g_value_array_free (factories);
 
   return;
@@ -954,7 +967,6 @@ setup_caps_delay:
  *
  * Returns TRUE if an element was properly created and linked
  */
-
 static gboolean
 connect_pad (GstDecodeBin * dbin, GstElement * src, GstPad * pad,
     GstCaps * caps, GValueArray * factories, GstDecodeGroup * group)