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

gst/gst.c

@@ -22,6 +22,7 @@
 
 /**
  * SECTION:gst
+ * @title: GStreamer
  * @short_description: Media library supporting arbitrary formats and filter
  *                     graphs.
  *
@@ -40,9 +41,9 @@
  * and argv variables so that GStreamer can process its own command line
  * options, as shown in the following example.
  *
- * <example>
- * <title>Initializing the gstreamer library</title>
- * <programlisting language="c">
+ * ## Initializing the gstreamer library
+ *
+ * |[ <!-- language="C" -->
  * int
  * main (int argc, char *argv[])
  * {
@@ -50,17 +51,16 @@
  *   gst_init (&amp;argc, &amp;argv);
  *   ...
  * }
- * </programlisting>
- * </example>
+ * ]|
  *
  * It's allowed to pass two %NULL pointers to gst_init() in case you don't want
  * to pass the command line args to GStreamer.
  *
  * You can also use GOption to initialize your own parameters as shown in
  * the next code fragment:
- * <example>
- * <title>Initializing own parameters when initializing gstreamer</title>
- * <programlisting>
+ *
+ * ## Initializing own parameters when initializing gstreamer
+ * |[ <!-- language="C" -->
  * static gboolean stats = FALSE;
  * ...
  * int
@@ -81,16 +81,14 @@
  *  g_option_context_free (ctx);
  * ...
  * }
- * </programlisting>
- * </example>
+ * ]|
  *
  * Use gst_version() to query the library version at runtime or use the
  * GST_VERSION_* macros to find the version at compile time. Optionally
  * gst_version_string() returns a printable string.
  *
  * The gst_deinit() call is used to clean up all internal resources used
- * by <application>GStreamer</application>. It is mostly used in unit tests 
- * to check for leaks.
+ * by GStreamer. It is mostly used in unit tests to check for leaks.
  */
 
 #include "gst_private.h"
@@ -381,11 +379,9 @@ gst_init_check (int *argc, char **argv[], GError ** err)
  * <link linkend="gst-running">Running GStreamer Applications</link>
  * for how to disable automatic registry updates.
  *
- * <note><para>
- * This function will terminate your program if it was unable to initialize
- * GStreamer for some reason.  If you want your program to fall back,
- * use gst_init_check() instead.
- * </para></note>
+ * > This function will terminate your program if it was unable to initialize
+ * > GStreamer for some reason.  If you want your program to fall back,
+ * > use gst_init_check() instead.
  *
  * WARNING: This function does not work in the same way as corresponding
  * functions in other glib-style libraries, such as gtk_init\(\). In

gst/gstallocator.c

@@ -21,6 +21,7 @@
 
 /**
  * SECTION:gstallocator
+ * @title: GstAllocator
  * @short_description: allocate memory blocks
  * @see_also: #GstMemory
  *

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,42 +56,31 @@
  * 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
+ *
+ * * 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.</para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_SEGMENT_START</term>
- *     <listitem><para>just collected and never forwarded upwards.
+ * 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.</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
+ * 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.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_MESSAGE_CLOCK_LOST</term>
- *     <listitem><para> This message is posted by an element when it
+ *
+ * * 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
@@ -99,53 +89,34 @@
  * 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
+ *
+ * * 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.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>OTHERS</term>
- *     <listitem><para> posted upwards.</para></listitem>
- *   </varlistentry>
- * </variablelist>
  *
+ * * 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
+ *
+ * * 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.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>GST_QUERY_POSITION</term>
- *     <listitem><para>The query is sent to all sink elements in the bin and the
+ *
+ * * 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.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>OTHERS</term>
- *     <listitem><para>the query is forwarded to all sink elements, the result
+ *
+ * * 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.</para></listitem>
- *   </varlistentry>
- * </variablelist>
+ * 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.
  *

gst/gstbuffer.c

@@ -22,6 +22,7 @@
 
 /**
  * SECTION:gstbuffer
+ * @title: GstBuffer
  * @short_description: Data-passing buffer type
  * @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
  *

gst/gstbufferlist.c

@@ -23,6 +23,7 @@
 
 /**
  * SECTION:gstbufferlist
+ * @title: GstBufferList
  * @short_description: Lists of buffers for data-passing
  * @see_also: #GstPad, #GstMiniObject
  *

gst/gstbufferpool.c

@@ -21,6 +21,7 @@
 
 /**
  * SECTION:gstbufferpool
+ * @title: GstBufferPool
  * @short_description: Pool for buffers
  * @see_also: #GstBuffer
  *

gst/gstbus.c

@@ -21,6 +21,7 @@
 
 /**
  * SECTION:gstbus
+ * @title: GstBus
  * @short_description: Asynchronous message bus subsystem
  * @see_also: #GstMessage, #GstElement
  *

gst/gstcaps.c

@@ -19,6 +19,7 @@
 
 /**
  * SECTION:gstcaps
+ * @title: GstCaps
  * @short_description: Structure describing sets of media formats
  * @see_also: #GstStructure, #GstMiniObject
  *
@@ -1768,8 +1769,8 @@ gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
  * @subtrahend: #GstCaps to subtract
  *
  * Subtracts the @subtrahend from the @minuend.
- * <note>This function does not work reliably if optional properties for caps
- * are included on one caps and omitted on the other.</note>
+ * > This function does not work reliably if optional properties for caps
+ * > are included on one caps and omitted on the other.
  *
  * Returns: (transfer full): the resulting caps
  */

gst/gstcapsfeatures.c

@@ -20,6 +20,7 @@
 
 /**
  * SECTION:gstcapsfeatures
+ * @title: GstCapsFeatures
  * @short_description: A set of features in caps
  * @see_also: #GstCaps
  *

gst/gstchildproxy.c

@@ -21,6 +21,7 @@
 
 /**
  * SECTION:gstchildproxy
+ * @title: GstChildProxy
  * @short_description: Interface for multi child elements.
  * @see_also: #GstBin
  *

gst/gstclock.c

@@ -23,6 +23,7 @@
 
 /**
  * SECTION:gstclock
+ * @title: GstClock
  * @short_description: Abstract class for global clocks
  * @see_also: #GstSystemClock, #GstPipeline
  *
@@ -1115,9 +1116,9 @@ gst_clock_get_time (GstClock * clock)
  * Subsequent calls to gst_clock_get_time() will return clock times computed as
  * follows:
  *
- * <programlisting>
+ * |[
  *   time = (internal_time - internal) * rate_num / rate_denom + external
- * </programlisting>
+ * ]|
  *
  * This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
  * tries to do the integer arithmetic as precisely as possible.
@@ -1588,7 +1589,6 @@ gst_clock_get_property (GObject * object, guint prop_id,
  *
  * For asynchronous waiting, the GstClock::synced signal can be used.
  *
- *
  * This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
  * is not set on the clock, or if the clock is already synced.
  *

gst/gstclock.h

@@ -176,9 +176,9 @@ typedef gpointer GstClockID;
  *
  * Convert a #GstClockTime to a #GTimeVal
  *
- * <note>on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
- * which is about 68 years.  Expect trouble if you want to schedule stuff
- * in your pipeline for 2038.</note>
+ * > on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
+ * > which is about 68 years.  Expect trouble if you want to schedule stuff
+ * > in your pipeline for 2038.
  */
 #define GST_TIME_TO_TIMEVAL(t,tv)                               \
 G_STMT_START {                                                  \

gst/gstcompat.h

@@ -25,6 +25,7 @@
 #define __GSTCOMPAT_H__
 /**
  * SECTION:gstcompat
+ * @title: GstCompat
  * @short_description: Deprecated API entries
  *
  * Please do not use these in new code.

gst/gstcontext.c

@@ -23,6 +23,7 @@
 
 /**
  * SECTION:gstcontext
+ * @title: GstContext
  * @short_description: Lightweight objects to represent element contexts
  * @see_also: #GstMiniObject, #GstElement
  *

gst/gstcontrolbinding.c

@@ -21,6 +21,7 @@
  */
 /**
  * SECTION:gstcontrolbinding
+ * @title: GstControlBinding
  * @short_description: attachment for control source sources
  *
  * A base class for value mapping objects that attaches control sources to gobject

gst/gstcontrolsource.c

@@ -22,6 +22,7 @@
 
 /**
  * SECTION:gstcontrolsource
+ * @title: GstControlSource
  * @short_description: base class for control source sources
  *
  * The #GstControlSource is a base class for control value sources that could

gst/gstdebugutils.h

@@ -74,9 +74,9 @@ void gst_debug_bin_to_dot_file_with_ts (GstBin *bin, GstDebugGraphDetails detail
  * To aid debugging applications one can use this method to write out the whole
  * network of gstreamer elements that form the pipeline into an dot file.
  * This file can be processed with graphviz to get an image, like this:
- * <informalexample><programlisting>
+ * |[
  *  dot -Tpng -oimage.png graph_lowlevel.dot
- * </programlisting></informalexample>
+ * ]|
  * There is also a utility called xdot which allows you to view the dot file
  * directly without converting it first.
  *

gst/gstdevice.c

@@ -21,6 +21,7 @@
 
 /**
  * SECTION:gstdevice
+ * @title: GstDevice
  * @short_description: Object representing a device
  * @see_also: #GstDeviceProvider
  *

gst/gstdevicemonitor.c

@@ -21,6 +21,7 @@
 
 /**
  * SECTION:gstdevicemonitor
+ * @title: GstDeviceMonitor
  * @short_description: A device monitor and prober
  * @see_also: #GstDevice, #GstDeviceProvider
  *
@@ -34,7 +35,6 @@
  * The device monitor will monitor all devices matching the filters that
  * the application has set.
  *
- *
  * The basic use pattern of a device monitor is as follows:
  * |[
  *   static gboolean