docs: mention that it's necessary to set the state of elements added to an already-running pipeline

https://bugzilla.gnome.org/show_bug.cgi?id=641631

docs/manual/basics-bins.xml

@@ -135,6 +135,10 @@ main (int   argc,
 [..]
 }
     </programlisting>
+    <para>
+      (This is a silly example of course, there already exists a much more
+      powerful and versatile custom bin like this: the playbin2 element.)
+    </para>
     <para>
       Custom bins can be created with a plugin or an XML description. You
       will find more information about creating custom bin in the <ulink
@@ -143,10 +147,31 @@ main (int   argc,
       Writers Guide</ulink>.
     </para>
     <para>
-      Examples of such custom bins are the playbin and decodebin elements from<ulink
+      Examples of such custom bins are the playbin2 and uridecodebin elements from<ulink
       type="http"
       url="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/index.html">
       gst-plugins-base</ulink>.
     </para>
   </sect1>
+  <sect1 id="section-bin-state-change-handling">
+    <title>Bins manage states of their children</title>
+    <para>
+      Bins manage the state of all elements contained in them. If you set
+      a bin (or a pipeline, which is a special top-level type of bin) to
+      a certain target state using <function>gst_element_set_state ()</function>,
+      it will make sure all elements contained within it will also be set
+      to this state. This means it's usually only necessary to set the state
+      of the top-level pipeline to start up the pipeline or shut it down.
+    </para>
+    <para>
+      Note, however, that if elements are added to a bin or pipeline that's
+      already running, , e.g. from within a "pad-added" or "new-decoded-pad"
+      signal callback, its state will not automatically be brought in line with
+      the current state or target state of the bin or pipeline it was added to.
+      Instead, you have to need to set it to the desired target state yourself
+      using <function>gst_element_set_state ()</function> or
+      <function>gst_element_sync_state_with_parent ()</function> when adding
+      elements to an already-running pipeline.
+    </para>
+  </sect1>
 </chapter>

docs/manual/basics-elements.xml

@@ -554,5 +554,16 @@ main (int   argc,
       url="&URLAPI;GstBus.html"><classname>GstBus</classname></ulink>. See
       <xref linkend="chapter-bus"/> for details.
     </para>
+    <para>
+      When you set a bin or pipeline to a certain target state, it will usually
+      propagate the state change to all elements within the bin or pipeline
+      automatically, so it's usually only necessary to set the state of the
+      top-level pipeline to start up the pipeline or shut it down. However,
+      when adding elements dynamically to an already-running pipeline, e.g.
+      from within a "pad-added" or "new-decoded-pad" signal callback, you
+      need to set it to the desired target state yourself using
+      <function>gst_element_set_state ()</function> or
+      <function>gst_element_sync_state_with_parent ()</function>.
+    </para>
   </sect1>
 </chapter>

docs/manual/basics-pads.xml

@@ -118,6 +118,14 @@ main (int   argc,
 <!-- example-begin pad.c d -->
 }
       <!-- example-end pad.c d --></programlisting>
+      <para>
+        It is not uncommon to add elements to the pipeline only from within
+        the "pad-added" or "new-decoded-pad" callback. If you do this, don't
+        forget to set the state of the newly-added elements to the target
+        state of the pipeline using
+        <function>gst_element_set_state ()</function> or
+        <function>gst_element_sync_state_with_parent ()</function>.
+      </para>
     </sect2>
 
     <sect2 id="section-pads-request">

gst/gstbin.c

@@ -1194,6 +1194,14 @@ had_parent:
  * If the element's pads are linked to other pads, the pads will be unlinked
  * before the element is added to the bin.
  *
+ * <note>
+ * When you add an element to an already-running pipeline, you will have to
+ * take care to set the state of the newly-added element to the desired
+ * state (usually PLAYING or PAUSED, same you set the pipeline to originally)
+ * with gst_element_set_state(), or use gst_element_sync_state_with_parent().
+ * The bin or pipeline will not take care of this for you.
+ * </note>
+ *
  * MT safe.
  *
  * Returns: TRUE if the element could be added, FALSE if

gst/gstelement.c

@@ -202,7 +202,11 @@ gst_element_class_init (GstElementClass * klass)
    * @gstelement: the object which received the signal
    * @new_pad: the pad that has been added
    *
-   * a new #GstPad has been added to the element.
+   * a new #GstPad has been added to the element. Note that this signal will
+   * usually be emitted from the context of the streaming thread. Also keep in
+   * mind that if you add new elements to the pipeline in the signal handler
+   * you will need to set them to the desired target state with
+   * gst_element_set() or gst_element_sync_state_with_parent().
    */
   gst_element_signals[PAD_ADDED] =
       g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
@@ -224,6 +228,8 @@ gst_element_class_init (GstElementClass * klass)
    * @gstelement: the object which received the signal
    *
    * This signals that the element will not generate more dynamic pads.
+   * Note that this signal will usually be emitted from the context of
+   * the streaming thread.
    */
   gst_element_signals[NO_MORE_PADS] =
       g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),