Port gtk-doc comments to their equivalent markdown syntax

Modernizing our documentation and preparing a possible move to hotdoc.
This commits also adds missing @title metadatas to all SECTIONs

1 files changed, 61 insertions, 94 deletions

diff --git a/gst/gstbin.c b/gst/gstbin.c
index 9e6708930..3c0b2da38 100644
--- a/gst/gstbin.c
+++ b/gst/gstbin.c
@@ -25,6 +25,7 @@
 
 /**
  * SECTION:gstbin
+ * @title: GstBin
  * @short_description: Base class and element that can contain other elements
  *
  * #GstBin is an element that can contain other #GstElement, allowing them to be
@@ -55,97 +56,67 @@
  * the bin. Likewise the #GstBin::element-removed signal is fired whenever an
  * element is removed from the bin.
  *
- * <refsect2><title>Notes</title>
- * <para>
+ * ## Notes
+ *
  * A #GstBin internally intercepts every #GstMessage posted by its children and
  * implements the following default behaviour for each of them:
- * <variablelist>
- *   <varlistentry>
- *     <term>GST_MESSAGE_EOS</term>
- *     <listitem><para>This message is only posted by sinks in the PLAYING
- *     state. If all sinks posted the EOS message, this bin will post and EOS
- *     message upwards.</para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_SEGMENT_START</term>
- *     <listitem><para>just collected and never forwarded upwards.
- *     The messages are used to decide when all elements have completed playback
- *     of their segment.</para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_SEGMENT_DONE</term>
- *     <listitem><para> Is posted by #GstBin when all elements that posted
- *     a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_DURATION_CHANGED</term>
- *     <listitem><para> Is posted by an element that detected a change
- *     in the stream duration. The default bin behaviour is to clear any
- *     cached duration values so that the next duration query will perform
- *     a full duration recalculation. The duration change is posted to the
- *     application so that it can refetch the new duration with a duration
- *     query. Note that these messages can be posted before the bin is
- *     prerolled, in which case the duration query might fail.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_CLOCK_LOST</term>
- *     <listitem><para> This message is posted by an element when it
- *     can no longer provide a clock. The default bin behaviour is to
- *     check if the lost clock was the one provided by the bin. If so and
- *     the bin is currently in the PLAYING state, the message is forwarded to
- *     the bin parent.
- *     This message is also generated when a clock provider is removed from
- *     the bin. If this message is received by the application, it should
- *     PAUSE the pipeline and set it back to PLAYING to force a new clock
- *     distribution.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_CLOCK_PROVIDE</term>
- *     <listitem><para> This message is generated when an element
- *     can provide a clock. This mostly happens when a new clock
- *     provider is added to the bin. The default behaviour of the bin is to
- *     mark the currently selected clock as dirty, which will perform a clock
- *     recalculation the next time the bin is asked to provide a clock.
- *     This message is never sent tot the application but is forwarded to
- *     the parent of the bin.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>OTHERS</term>
- *     <listitem><para> posted upwards.</para></listitem>
- *   </varlistentry>
- * </variablelist>
  *
+ * * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING
+ * state. If all sinks posted the EOS message, this bin will post and EOS
+ * message upwards.
+ *
+ * * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards.
+ * The messages are used to decide when all elements have completed playback
+ * of their segment.
+ *
+ * * GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted
+ * a SEGMENT_START have posted a SEGMENT_DONE.
+ *
+ * * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change
+ * in the stream duration. The default bin behaviour is to clear any
+ * cached duration values so that the next duration query will perform
+ * a full duration recalculation. The duration change is posted to the
+ * application so that it can refetch the new duration with a duration
+ * query. Note that these messages can be posted before the bin is
+ * prerolled, in which case the duration query might fail.
+ *
+ * * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
+ * can no longer provide a clock. The default bin behaviour is to
+ * check if the lost clock was the one provided by the bin. If so and
+ * the bin is currently in the PLAYING state, the message is forwarded to
+ * the bin parent.
+ * This message is also generated when a clock provider is removed from
+ * the bin. If this message is received by the application, it should
+ * PAUSE the pipeline and set it back to PLAYING to force a new clock
+ * distribution.
+ *
+ * * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
+ * can provide a clock. This mostly happens when a new clock
+ * provider is added to the bin. The default behaviour of the bin is to
+ * mark the currently selected clock as dirty, which will perform a clock
+ * recalculation the next time the bin is asked to provide a clock.
+ * This message is never sent tot the application but is forwarded to
+ * the parent of the bin.
+ *
+ * * OTHERS: posted upwards.
  *
  * A #GstBin implements the following default behaviour for answering to a
  * #GstQuery:
- * <variablelist>
- *   <varlistentry>
- *     <term>GST_QUERY_DURATION</term>
- *     <listitem><para>If the query has been asked before with the same format
- *     and the bin is a toplevel bin (ie. has no parent),
- *     use the cached previous value. If no previous value was cached, the
- *     query is sent to all sink elements in the bin and the MAXIMUM of all
- *     values is returned. If the bin is a toplevel bin the value is cached.
- *     If no sinks are available in the bin, the query fails.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_QUERY_POSITION</term>
- *     <listitem><para>The query is sent to all sink elements in the bin and the
- *     MAXIMUM of all values is returned. If no sinks are available in the bin,
- *     the query fails.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>OTHERS</term>
- *     <listitem><para>the query is forwarded to all sink elements, the result
- *     of the first sink that answers the query successfully is returned. If no
- *     sink is in the bin, the query fails.</para></listitem>
- *   </varlistentry>
- * </variablelist>
+ *
+ * * GST_QUERY_DURATION:If the query has been asked before with the same format
+ * and the bin is a toplevel bin (ie. has no parent),
+ * use the cached previous value. If no previous value was cached, the
+ * query is sent to all sink elements in the bin and the MAXIMUM of all
+ * values is returned. If the bin is a toplevel bin the value is cached.
+ * If no sinks are available in the bin, the query fails.
+ *
+ * * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the
+ * MAXIMUM of all values is returned. If no sinks are available in the bin,
+ * the query fails.
+ *
+ * * OTHERS:the query is forwarded to all sink elements, the result
+ * of the first sink that answers the query successfully is returned. If no
+ * sink is in the bin, the query fails.
  *
  * A #GstBin will by default forward any event sent to it to all sink
  * (#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements
@@ -154,8 +125,6 @@
  * is returned. If no elements of the required type are in the bin, the event
  * handler will return %TRUE.
  *
- * </para>
- * </refsect2>
  */
 
 #include "gst_private.h"
@@ -1527,13 +1496,11 @@ gst_bin_deep_element_removed_func (GstBin * bin, GstBin * sub_bin,
  * 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>
+ * > 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.
  *
  * MT safe.
  *