docs: add more docs around GstState and GstStateChange

Take reviewed docs from docs/design/part-state to have that more prominent
inside the api docs. Add a few sentences to link things better together.

gst/gstelement.c

@@ -56,8 +56,8 @@
  *
  * Each element has a state (see #GstState).  You can get and set the state
  * of an element with gst_element_get_state() and gst_element_set_state().
- * To get a string representation of a #GstState, use
- * gst_element_state_get_name().
+ * Setting a state triggers a #GstStateChange. To get a string representation
+ * of a #GstState, use gst_element_state_get_name().
  *
  * You can get and set a #GstClock on an element using gst_element_get_clock()
  * and gst_element_set_clock().
@@ -2063,8 +2063,8 @@ interrupted:
  *
  * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
  * successfully changed its state but is not able to provide data yet.
- * This mostly happens for live sources that only produce data in the PLAYING
- * state. While the state change return is equivalent to
+ * This mostly happens for live sources that only produce data in 
+ * %GST_STATE_PLAYING. While the state change return is equivalent to
  * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
  * some sink elements might not be able to complete their state change because
  * an element is not producing data to complete the preroll. When setting the

gst/gstelement.h

@@ -31,13 +31,17 @@ typedef struct _GstElementClass GstElementClass;
 /* gstmessage.h needs State */
 /**
  * GstState:
- * @GST_STATE_VOID_PENDING     : no pending state.
- * @GST_STATE_NULL             : the NULL state or initial state of an element
- * @GST_STATE_READY            : the element is ready to go to PAUSED
- * @GST_STATE_PAUSED           : the element is PAUSED
- * @GST_STATE_PLAYING          : the element is PLAYING
- *
- * The posible states an element can be in.
+ * @GST_STATE_VOID_PENDING: no pending state.
+ * @GST_STATE_NULL        : the NULL state or initial state of an element.
+ * @GST_STATE_READY       : the element is ready to go to PAUSED.
+ * @GST_STATE_PAUSED      : the element is PAUSED, it is ready to accept and
+ *                          process data. Sink elements however only accept one
+ *                          buffer and then block.
+ * @GST_STATE_PLAYING     : the element is PLAYING, the #GstClock is running and
+ *                          the data is flowing.
+ *
+ * The posible states an element can be in. States can be chaged using
+ * gst_element_set_state() and checked using gst_element_get_state().
  */
 typedef enum {
   GST_STATE_VOID_PENDING        = 0,
@@ -78,8 +82,8 @@ G_BEGIN_DECLS
  * @GST_STATE_CHANGE_SUCCESS   : the state change succeeded
  * @GST_STATE_CHANGE_ASYNC     : the state change will happen asynchronously
  * @GST_STATE_CHANGE_NO_PREROLL: the state change succeeded but the element
- *                               cannot produce data in PAUSED. This typically
- *                               happens with live sources.
+ *                               cannot produce data in %GST_STATE_PAUSED.
+ *                               This typically happens with live sources.
  *
  * The possible return values from a state change function. Only
  * @GST_STATE_CHANGE_FAILURE is a real failure.
@@ -173,15 +177,129 @@ typedef enum {
 
 /**
  * GstStateChange:
- * @GST_STATE_CHANGE_NULL_TO_READY    : state change from NULL to READY
- * @GST_STATE_CHANGE_READY_TO_PAUSED  : state change from READY to PAUSED
- * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING
- * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED
- * @GST_STATE_CHANGE_PAUSED_TO_READY  : state change from PAUSED to READY
- * @GST_STATE_CHANGE_READY_TO_NULL    : state change from READY to NULL
- *
- * The different (interesting) state changes that are passed to the
- * state change functions of elements.
+ * @GST_STATE_CHANGE_NULL_TO_READY    : state change from NULL to READY.
+ * <itemizedlist>
+ *   <listitem><para>
+ *     The element must check if the resources it needs are available. Device
+ *     sinks and -sources typically try to probe the device to constrain their
+ *     caps.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     The element opens the device (in case feature need to be probed).
+ *   </para></listitem>
+ * </itemizedlist>
+ * @GST_STATE_CHANGE_READY_TO_PAUSED  : state change from READY to PAUSED.
+ * <itemizedlist>
+ *   <listitem><para>
+ *     The element pads are activated in order to receive data in PAUSED.
+ *     Streaming threads are started.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Some elements might need to return ASYNC and complete the state change
+ *     when they have enough information. It is a requirement for sinks to
+ *     return ASYNC and complete the state change when they receive the first
+ *     buffer or EOS event (preroll). Sinks also block the dataflow when in
+ *     PAUSED.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     A pipeline resets the running_time to 0.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Live sources return NO_PREROLL and don't generate data.
+ *   </para></listitem>
+ * </itemizedlist>
+ * @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING.
+ * <itemizedlist>
+ *   <listitem><para>
+ *     Most elements ignore this state change.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     The pipeline selects a clock and distributes this to all the children
+ *     before setting them to PLAYING. This means that it is only alowed to
+ *     synchronize on the clock in the PLAYING state.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     The pipeline uses the clock and the running_time to calculate the
+ *     base_time. The base_time is distributed to all children when performing
+ *     the state change.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Sink elements stop blocking on the preroll buffer or event and start
+ *     rendering the data.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Sinks can post the EOS message in the PLAYING state. It is not allowed to
+ *     post EOS when not in the PLAYING state.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     While streaming in PAUSED or PLAYING elements can create and remove
+ *     sometimes pads.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Live sources start generating data and return SUCCESS.
+ *   </para></listitem>
+ * </itemizedlist>
+ * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED.
+ * <itemizedlist>
+ *   <listitem><para>
+ *     Most elements ignore this state change.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     The pipeline calculates the running_time based on the last selected clock
+ *     and the base_time. It stores this information to continue playback when
+ *     going back to the PLAYING state.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Sinks unblock any clock wait calls.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     When a sink does not have a pending buffer to play, it returns ASYNC from
+ *     this state change and completes the state change when it receives a new
+ *     buffer or an EOS event.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Any queued EOS messages are removed since they will be reposted when going
+ *     back to the PLAYING state. The EOS messages are queued in GstBins.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Live sources stop generating data and return NO_PREROLL.
+ *   </para></listitem>
+ * </itemizedlist>
+ * @GST_STATE_CHANGE_PAUSED_TO_READY  : state change from PAUSED to READY.
+ * <itemizedlist>
+ *   <listitem><para>
+ *     Sinks unblock any waits in the preroll.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Elements unblock any waits on devices
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Chain or get_range functions return WRONG_STATE.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     The element pads are deactivated so that streaming becomes impossible and
+ *     all streaming threads are stopped.
+ *   </para></listitem>
+ *   <listitem><para>
+ *     The sink forgets all negotiated formats
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Elements remove all sometimes pads
+ *   </para></listitem>
+ * </itemizedlist>
+ * @GST_STATE_CHANGE_READY_TO_NULL    : state change from READY to NULL.
+ * <itemizedlist>
+ *   <listitem><para>
+ *     Elements close devices
+ *   </para></listitem>
+ *   <listitem><para>
+ *     Elements reset any internal state.
+ *   </para></listitem>
+ * </itemizedlist>
+ *
+ * These are the different state changes an element goes through.
+ * %GST_STATE_NULL &rArr; %GST_STATE_PLAYING is called an upwards state change
+ * and %GST_STATE_PLAYING &rArr; %GST_STATE_NULL a downwards state change.
  */
 typedef enum /*< flags=0 >*/
 {