diff --git a/gst/playback/gstdecodebin.c b/gst/playback/gstdecodebin.c
index 13cc9e99ba..fc1f813e42 100644
--- a/gst/playback/gstdecodebin.c
+++ b/gst/playback/gstdecodebin.c
@@ -26,6 +26,13 @@
  * When using decodebin in your application, connect a signal handler to
  * #GstDecodeBin::new-decoded-pad and connect your sinks from within the
  * callback function.
+ *
+ * <note>
+ * This element is deprecated and no longer supported. You should use the
+ * #uridecodebin or #decodebin2 element instead (or, even better: #playbin2).
+ * </note>
+ *
+ * Deprecated: use uridecodebin or decodebin2 instead.
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/gst/playback/gstdecodebin2.c b/gst/playback/gstdecodebin2.c
index 7877c2164d..72beab5f59 100644
--- a/gst/playback/gstdecodebin2.c
+++ b/gst/playback/gstdecodebin2.c
@@ -24,12 +24,9 @@
  * #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 #GstDecodeBin for its internal auto-plugging.
+ * decodebin2 is considered stable now and replaces the old #decodebin element.
+ * #uridecodebin uses decodebin2 internally and is often more convenient to
+ * use, as it creates a suitable source element as well.
  */
 
 /* Implementation notes: