diff --git a/gst/playback/gstplaybin.c b/gst/playback/gstplaybin.c
index eb1c823098..57b5dbe1f8 100644
--- a/gst/playback/gstplaybin.c
+++ b/gst/playback/gstplaybin.c
@@ -23,6 +23,11 @@
  * Playbin provides a stand-alone everything-in-one abstraction for an
  * audio and/or video player.
  *
+ * <note>
+ * This element is deprecated and no longer supported. You should use
+ * the #playbin2 element instead.
+ * </note>
+ *
  * It can handle both audio and video files and features
  * <itemizedlist>
  * <listitem>
@@ -217,6 +222,8 @@
  * ]| This will play back title 1 of a DVD in your disc drive (assuming
  * the drive is detected automatically by the plugin).
  * </refsect2>
+ *
+ * Deprecated: use playbin2 instead
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/gst/playback/gstplaybin2.c b/gst/playback/gstplaybin2.c
index 0b764d554c..12d72eb19d 100644
--- a/gst/playback/gstplaybin2.c
+++ b/gst/playback/gstplaybin2.c
@@ -23,9 +23,8 @@
  * Playbin2 provides a stand-alone everything-in-one abstraction for an
  * audio and/or video player.
  *
- * At this stage, playbin2 is considered UNSTABLE. The API provided in the
- * signals and properties may yet change in the near future. When playbin2
- * is stable, it will probably replace #playbin
+ * playbin2 is considered stable now. It is the prefered playback API now,
+ * and replaces the old #playbin element, which is no longer supported.
  *
  * It can handle both audio and video files and features
  * <itemizedlist>
@@ -60,7 +59,7 @@
  * <refsect2>
  * <title>Usage</title>
  * <para>
- * A playbin element can be created just like any other element using
+ * A playbin2 element can be created just like any other element using
  * gst_element_factory_make(). The file/URI to play should be set via the #GstPlayBin2: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