Commit a87b4551 authored by Thibault Saunier's avatar Thibault Saunier

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
parent 76f049bc
...@@ -22,6 +22,7 @@ ...@@ -22,6 +22,7 @@
/** /**
* SECTION:gst * SECTION:gst
* @title: GStreamer
* @short_description: Media library supporting arbitrary formats and filter * @short_description: Media library supporting arbitrary formats and filter
* graphs. * graphs.
* *
...@@ -40,9 +41,9 @@ ...@@ -40,9 +41,9 @@
* and argv variables so that GStreamer can process its own command line * and argv variables so that GStreamer can process its own command line
* options, as shown in the following example. * options, as shown in the following example.
* *
* <example> * ## Initializing the gstreamer library
* <title>Initializing the gstreamer library</title> *
* <programlisting language="c"> * |[ <!-- language="C" -->
* int * int
* main (int argc, char *argv[]) * main (int argc, char *argv[])
* { * {
...@@ -50,17 +51,16 @@ ...@@ -50,17 +51,16 @@
* gst_init (&amp;argc, &amp;argv); * 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 * 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. * to pass the command line args to GStreamer.
* *
* You can also use GOption to initialize your own parameters as shown in * You can also use GOption to initialize your own parameters as shown in
* the next code fragment: * the next code fragment:
* <example> *
* <title>Initializing own parameters when initializing gstreamer</title> * ## Initializing own parameters when initializing gstreamer
* <programlisting> * |[ <!-- language="C" -->
* static gboolean stats = FALSE; * static gboolean stats = FALSE;
* ... * ...
* int * int
...@@ -81,16 +81,14 @@ ...@@ -81,16 +81,14 @@
* g_option_context_free (ctx); * g_option_context_free (ctx);
* ... * ...
* } * }
* </programlisting> * ]|
* </example>
* *
* Use gst_version() to query the library version at runtime or use the * 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_* macros to find the version at compile time. Optionally
* gst_version_string() returns a printable string. * gst_version_string() returns a printable string.
* *
* The gst_deinit() call is used to clean up all internal resources used * The gst_deinit() call is used to clean up all internal resources used
* by <application>GStreamer</application>. It is mostly used in unit tests * by GStreamer. It is mostly used in unit tests to check for leaks.
* to check for leaks.
*/ */
#include "gst_private.h" #include "gst_private.h"
...@@ -381,11 +379,9 @@ gst_init_check (int *argc, char **argv[], GError ** err) ...@@ -381,11 +379,9 @@ gst_init_check (int *argc, char **argv[], GError ** err)
* <link linkend="gst-running">Running GStreamer Applications</link> * <link linkend="gst-running">Running GStreamer Applications</link>
* for how to disable automatic registry updates. * for how to disable automatic registry updates.
* *
* <note><para> * > This function will terminate your program if it was unable to initialize
* This function will terminate your program if it was unable to initialize * > GStreamer for some reason. If you want your program to fall back,
* GStreamer for some reason. If you want your program to fall back, * > use gst_init_check() instead.
* use gst_init_check() instead.
* </para></note>
* *
* WARNING: This function does not work in the same way as corresponding * WARNING: This function does not work in the same way as corresponding
* functions in other glib-style libraries, such as gtk_init\(\). In * functions in other glib-style libraries, such as gtk_init\(\). In
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstallocator * SECTION:gstallocator
* @title: GstAllocator
* @short_description: allocate memory blocks * @short_description: allocate memory blocks
* @see_also: #GstMemory * @see_also: #GstMemory
* *
......
...@@ -25,6 +25,7 @@ ...@@ -25,6 +25,7 @@
/** /**
* SECTION:gstbin * SECTION:gstbin
* @title: GstBin
* @short_description: Base class and element that can contain other elements * @short_description: Base class and element that can contain other elements
* *
* #GstBin is an element that can contain other #GstElement, allowing them to be * #GstBin is an element that can contain other #GstElement, allowing them to be
...@@ -55,42 +56,31 @@ ...@@ -55,42 +56,31 @@
* the bin. Likewise the #GstBin::element-removed signal is fired whenever an * the bin. Likewise the #GstBin::element-removed signal is fired whenever an
* element is removed from the bin. * element is removed from the bin.
* *
* <refsect2><title>Notes</title> * ## Notes
* <para> *
* A #GstBin internally intercepts every #GstMessage posted by its children and * A #GstBin internally intercepts every #GstMessage posted by its children and
* implements the following default behaviour for each of them: * implements the following default behaviour for each of them:
* <variablelist> *
* <varlistentry> * * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING
* <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 * state. If all sinks posted the EOS message, this bin will post and EOS
* message upwards.</para></listitem> * message upwards.
* </varlistentry> *
* <varlistentry> * * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards.
* <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 * The messages are used to decide when all elements have completed playback
* of their segment.</para></listitem> * of their segment.
* </varlistentry> *
* <varlistentry> * * GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted
* <term>GST_MESSAGE_SEGMENT_DONE</term> * a SEGMENT_START have posted a SEGMENT_DONE.
* <listitem><para> Is posted by #GstBin when all elements that posted *
* a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem> * * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change
* </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 * in the stream duration. The default bin behaviour is to clear any
* cached duration values so that the next duration query will perform * cached duration values so that the next duration query will perform
* a full duration recalculation. The duration change is posted to the * a full duration recalculation. The duration change is posted to the
* application so that it can refetch the new duration with a duration * application so that it can refetch the new duration with a duration
* query. Note that these messages can be posted before the bin is * query. Note that these messages can be posted before the bin is
* prerolled, in which case the duration query might fail. * prerolled, in which case the duration query might fail.
* </para></listitem> *
* </varlistentry> * * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
* <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 * 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 * 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 is currently in the PLAYING state, the message is forwarded to
...@@ -99,53 +89,34 @@ ...@@ -99,53 +89,34 @@
* the bin. If this message is received by the application, it should * 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 * PAUSE the pipeline and set it back to PLAYING to force a new clock
* distribution. * distribution.
* </para></listitem> *
* </varlistentry> * * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
* <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 * 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 * 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 * mark the currently selected clock as dirty, which will perform a clock
* recalculation the next time the bin is asked to provide 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 * This message is never sent tot the application but is forwarded to
* the parent of the bin. * 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 * A #GstBin implements the following default behaviour for answering to a
* #GstQuery: * #GstQuery:
* <variablelist> *
* <varlistentry> * * GST_QUERY_DURATION:If the query has been asked before with the same format
* <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), * and the bin is a toplevel bin (ie. has no parent),
* use the cached previous value. If no previous value was cached, the * 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 * 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. * 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. * If no sinks are available in the bin, the query fails.
* </para></listitem> *
* </varlistentry> * * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the
* <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, * MAXIMUM of all values is returned. If no sinks are available in the bin,
* the query fails. * the query fails.
* </para></listitem> *
* </varlistentry> * * OTHERS:the query is forwarded to all sink elements, the result
* <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 * of the first sink that answers the query successfully is returned. If no
* sink is in the bin, the query fails.</para></listitem> * sink is in the bin, the query fails.
* </varlistentry>
* </variablelist>
* *
* A #GstBin will by default forward any event sent to it to all sink * 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 * (#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements
...@@ -154,8 +125,6 @@ ...@@ -154,8 +125,6 @@
* is returned. If no elements of the required type are in the bin, the event * is returned. If no elements of the required type are in the bin, the event
* handler will return %TRUE. * handler will return %TRUE.
* *
* </para>
* </refsect2>
*/ */
#include "gst_private.h" #include "gst_private.h"
...@@ -1527,13 +1496,11 @@ gst_bin_deep_element_removed_func (GstBin * bin, GstBin * sub_bin, ...@@ -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 * If the element's pads are linked to other pads, the pads will be unlinked
* before the element is added to the bin. * before the element is added to the bin.
* *
* <note> * > When you add an element to an already-running pipeline, you will have to
* 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
* 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)
* 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().
* 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.
* The bin or pipeline will not take care of this for you.
* </note>
* *
* MT safe. * MT safe.
* *
......
...@@ -22,6 +22,7 @@ ...@@ -22,6 +22,7 @@
/** /**
* SECTION:gstbuffer * SECTION:gstbuffer
* @title: GstBuffer
* @short_description: Data-passing buffer type * @short_description: Data-passing buffer type
* @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool * @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
* *
......
...@@ -23,6 +23,7 @@ ...@@ -23,6 +23,7 @@
/** /**
* SECTION:gstbufferlist * SECTION:gstbufferlist
* @title: GstBufferList
* @short_description: Lists of buffers for data-passing * @short_description: Lists of buffers for data-passing
* @see_also: #GstPad, #GstMiniObject * @see_also: #GstPad, #GstMiniObject
* *
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstbufferpool * SECTION:gstbufferpool
* @title: GstBufferPool
* @short_description: Pool for buffers * @short_description: Pool for buffers
* @see_also: #GstBuffer * @see_also: #GstBuffer
* *
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstbus * SECTION:gstbus
* @title: GstBus
* @short_description: Asynchronous message bus subsystem * @short_description: Asynchronous message bus subsystem
* @see_also: #GstMessage, #GstElement * @see_also: #GstMessage, #GstElement
* *
......
...@@ -19,6 +19,7 @@ ...@@ -19,6 +19,7 @@
/** /**
* SECTION:gstcaps * SECTION:gstcaps
* @title: GstCaps
* @short_description: Structure describing sets of media formats * @short_description: Structure describing sets of media formats
* @see_also: #GstStructure, #GstMiniObject * @see_also: #GstStructure, #GstMiniObject
* *
...@@ -1768,8 +1769,8 @@ gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend, ...@@ -1768,8 +1769,8 @@ gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
* @subtrahend: #GstCaps to subtract * @subtrahend: #GstCaps to subtract
* *
* Subtracts the @subtrahend from the @minuend. * Subtracts the @subtrahend from the @minuend.
* <note>This function does not work reliably if optional properties for caps * > This function does not work reliably if optional properties for caps
* are included on one caps and omitted on the other.</note> * > are included on one caps and omitted on the other.
* *
* Returns: (transfer full): the resulting caps * Returns: (transfer full): the resulting caps
*/ */
......
...@@ -20,6 +20,7 @@ ...@@ -20,6 +20,7 @@
/** /**
* SECTION:gstcapsfeatures * SECTION:gstcapsfeatures
* @title: GstCapsFeatures
* @short_description: A set of features in caps * @short_description: A set of features in caps
* @see_also: #GstCaps * @see_also: #GstCaps
* *
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstchildproxy * SECTION:gstchildproxy
* @title: GstChildProxy
* @short_description: Interface for multi child elements. * @short_description: Interface for multi child elements.
* @see_also: #GstBin * @see_also: #GstBin
* *
......
...@@ -23,6 +23,7 @@ ...@@ -23,6 +23,7 @@
/** /**
* SECTION:gstclock * SECTION:gstclock
* @title: GstClock
* @short_description: Abstract class for global clocks * @short_description: Abstract class for global clocks
* @see_also: #GstSystemClock, #GstPipeline * @see_also: #GstSystemClock, #GstPipeline
* *
...@@ -1115,9 +1116,9 @@ gst_clock_get_time (GstClock * clock) ...@@ -1115,9 +1116,9 @@ gst_clock_get_time (GstClock * clock)
* Subsequent calls to gst_clock_get_time() will return clock times computed as * Subsequent calls to gst_clock_get_time() will return clock times computed as
* follows: * follows:
* *
* <programlisting> * |[
* time = (internal_time - internal) * rate_num / rate_denom + external * time = (internal_time - internal) * rate_num / rate_denom + external
* </programlisting> * ]|
* *
* This formula is implemented in gst_clock_adjust_unlocked(). Of course, it * This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
* tries to do the integer arithmetic as precisely as possible. * tries to do the integer arithmetic as precisely as possible.
...@@ -1588,7 +1589,6 @@ gst_clock_get_property (GObject * object, guint prop_id, ...@@ -1588,7 +1589,6 @@ gst_clock_get_property (GObject * object, guint prop_id,
* *
* For asynchronous waiting, the GstClock::synced signal can be used. * For asynchronous waiting, the GstClock::synced signal can be used.
* *
*
* This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC * 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. * is not set on the clock, or if the clock is already synced.
* *
......
...@@ -176,9 +176,9 @@ typedef gpointer GstClockID; ...@@ -176,9 +176,9 @@ typedef gpointer GstClockID;
* *
* Convert a #GstClockTime to a #GTimeVal * Convert a #GstClockTime to a #GTimeVal
* *
* <note>on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds, * > 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 * > which is about 68 years. Expect trouble if you want to schedule stuff
* in your pipeline for 2038.</note> * > in your pipeline for 2038.
*/ */
#define GST_TIME_TO_TIMEVAL(t,tv) \ #define GST_TIME_TO_TIMEVAL(t,tv) \
G_STMT_START { \ G_STMT_START { \
......
...@@ -25,6 +25,7 @@ ...@@ -25,6 +25,7 @@
#define __GSTCOMPAT_H__ #define __GSTCOMPAT_H__
/** /**
* SECTION:gstcompat * SECTION:gstcompat
* @title: GstCompat
* @short_description: Deprecated API entries * @short_description: Deprecated API entries
* *
* Please do not use these in new code. * Please do not use these in new code.
......
...@@ -23,6 +23,7 @@ ...@@ -23,6 +23,7 @@
/** /**
* SECTION:gstcontext * SECTION:gstcontext
* @title: GstContext
* @short_description: Lightweight objects to represent element contexts * @short_description: Lightweight objects to represent element contexts
* @see_also: #GstMiniObject, #GstElement * @see_also: #GstMiniObject, #GstElement
* *
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
*/ */
/** /**
* SECTION:gstcontrolbinding * SECTION:gstcontrolbinding
* @title: GstControlBinding
* @short_description: attachment for control source sources * @short_description: attachment for control source sources
* *
* A base class for value mapping objects that attaches control sources to gobject * A base class for value mapping objects that attaches control sources to gobject
......
...@@ -22,6 +22,7 @@ ...@@ -22,6 +22,7 @@
/** /**
* SECTION:gstcontrolsource * SECTION:gstcontrolsource
* @title: GstControlSource
* @short_description: base class for control source sources * @short_description: base class for control source sources
* *
* The #GstControlSource is a base class for control value sources that could * The #GstControlSource is a base class for control value sources that could
......
...@@ -74,9 +74,9 @@ void gst_debug_bin_to_dot_file_with_ts (GstBin *bin, GstDebugGraphDetails detail ...@@ -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 * 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. * 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: * This file can be processed with graphviz to get an image, like this:
* <informalexample><programlisting> * |[
* dot -Tpng -oimage.png graph_lowlevel.dot * dot -Tpng -oimage.png graph_lowlevel.dot
* </programlisting></informalexample> * ]|
* There is also a utility called xdot which allows you to view the dot file * There is also a utility called xdot which allows you to view the dot file
* directly without converting it first. * directly without converting it first.
* *
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstdevice * SECTION:gstdevice
* @title: GstDevice
* @short_description: Object representing a device * @short_description: Object representing a device
* @see_also: #GstDeviceProvider * @see_also: #GstDeviceProvider
* *
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstdevicemonitor * SECTION:gstdevicemonitor
* @title: GstDeviceMonitor
* @short_description: A device monitor and prober * @short_description: A device monitor and prober
* @see_also: #GstDevice, #GstDeviceProvider * @see_also: #GstDevice, #GstDeviceProvider
* *
...@@ -34,7 +35,6 @@ ...@@ -34,7 +35,6 @@
* The device monitor will monitor all devices matching the filters that * The device monitor will monitor all devices matching the filters that
* the application has set. * the application has set.
* *
*
* The basic use pattern of a device monitor is as follows: * The basic use pattern of a device monitor is as follows:
* |[ * |[
* static gboolean * static gboolean
......
...@@ -21,6 +21,7 @@ ...@@ -21,6 +21,7 @@
/** /**
* SECTION:gstdeviceprovider * SECTION:gstdeviceprovider
* @title: GstDeviceProvider
* @short_description: A device provider * @short_description: A device provider
* @see_also: #GstDevice, #GstDeviceMonitor * @see_also: #GstDevice, #GstDeviceMonitor
* *
...@@ -252,7 +253,8 @@ gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass, ...@@ -252,7 +253,8 @@ gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass,
* multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;" * multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
* *
* Sets the detailed information for a #GstDeviceProviderClass. * Sets the detailed information for a #GstDeviceProviderClass.
* <note>This function is for use in _class_init functions only.</note> *
* > This function is for use in _class_init functions only.
* *
* Since: 1.4 * Since: 1.4
*/ */
...@@ -288,7 +290,8 @@ gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass, ...@@ -288,7 +290,8 @@ gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
* foo.com&gt;" * foo.com&gt;"