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 @@
/**
* 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
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstallocator
* @title: GstAllocator
* @short_description: allocate memory blocks
* @see_also: #GstMemory
*
......
......@@ -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.
*
......
......@@ -22,6 +22,7 @@
/**
* SECTION:gstbuffer
* @title: GstBuffer
* @short_description: Data-passing buffer type
* @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
*
......
......@@ -23,6 +23,7 @@
/**
* SECTION:gstbufferlist
* @title: GstBufferList
* @short_description: Lists of buffers for data-passing
* @see_also: #GstPad, #GstMiniObject
*
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstbufferpool
* @title: GstBufferPool
* @short_description: Pool for buffers
* @see_also: #GstBuffer
*
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstbus
* @title: GstBus
* @short_description: Asynchronous message bus subsystem
* @see_also: #GstMessage, #GstElement
*
......
......@@ -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
*/
......
......@@ -20,6 +20,7 @@
/**
* SECTION:gstcapsfeatures
* @title: GstCapsFeatures
* @short_description: A set of features in caps
* @see_also: #GstCaps
*
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstchildproxy
* @title: GstChildProxy
* @short_description: Interface for multi child elements.
* @see_also: #GstBin
*
......
......@@ -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.
*
......
......@@ -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 { \
......
......@@ -25,6 +25,7 @@
#define __GSTCOMPAT_H__
/**
* SECTION:gstcompat
* @title: GstCompat
* @short_description: Deprecated API entries
*
* Please do not use these in new code.
......
......@@ -23,6 +23,7 @@
/**
* SECTION:gstcontext
* @title: GstContext
* @short_description: Lightweight objects to represent element contexts
* @see_also: #GstMiniObject, #GstElement
*
......
......@@ -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
......
......@@ -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
......
......@@ -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.
*
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstdevice
* @title: GstDevice
* @short_description: Object representing a device
* @see_also: #GstDeviceProvider
*
......
......@@ -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
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstdeviceprovider
* @title: GstDeviceProvider
* @short_description: A device provider
* @see_also: #GstDevice, #GstDeviceMonitor
*
......@@ -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;"
*
* 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
*/
......@@ -288,7 +290,8 @@ gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
* foo.com&gt;"
*
* 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.
*
* Same as gst_device_provider_class_set_metadata(), but @longname, @classification,
* @description, and @author must be static strings or inlined strings, as
......
......@@ -23,6 +23,7 @@
/**
* SECTION:gstdeviceproviderfactory
* @title: GstDeviceProviderFactory
* @short_description: Create GstDeviceProviders from a factory
* @see_also: #GstDeviceProvider, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
*
......
......@@ -21,6 +21,7 @@
/**
* SECTION:gstdynamictypefactory
* @title: GstDynamicTypeFactory
* @short_description: Represents a registered dynamically loadable GType
* @see_also: #GstPlugin, #GstPluginFeature.
*
......@@ -33,17 +34,16 @@
* done, the type is stored in the registry, and ready as soon as the
* registry is loaded.
*
* <example>
* <title>Registering a type for dynamic loading</title>
* <programlisting language="c">
* ## Registering a type for dynamic loading
*
* |[<!-- language="C" -->
*
* static gboolean
* plugin_init (GstPlugin * plugin)
* {
* return gst_dynamic_type_register (plugin, GST_TYPE_CUSTOM_CAPS_FIELD);
* }
* </programlisting>
* </example>
* ]|
*/
#ifdef HAVE_CONFIG_H
......
......@@ -22,6 +22,7 @@
/**
* SECTION:gstelement
* @title: GstElement
* @short_description: Abstract base class for all pipeline elements
* @see_also: #GstElementFactory, #GstPad
*
......@@ -362,8 +363,8 @@ gst_element_release_request_pad (GstElement * element, GstPad * pad)
* @element: a #GstElement to query
*
* Get the clock provided by the given element.
* <note>An element is only required to provide a clock in the PAUSED
* state. Some elements can provide a clock in other states.</note>
* > An element is only required to provide a clock in the PAUSED
* > state. Some elements can provide a clock in other states.
*
* Returns: (transfer full) (nullable): the GstClock provided by the
* element or %NULL if no clock could be provided. Unref after usage.
......@@ -1365,7 +1366,7 @@ gst_element_class_add_static_metadata (GstElementClass * klass,
* multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
*
* Sets the detailed information for a #GstElementClass.
* <note>This function is for use in _class_init functions only.</note>
* > This function is for use in _class_init functions only.
*/
void
gst_element_class_set_metadata (GstElementClass * klass,
......@@ -1398,7 +1399,8 @@ gst_element_class_set_metadata (GstElementClass * klass,
* multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
*
* Sets the detailed information for a #GstElementClass.
* <note>This function is for use in _class_init functions only.</note>
*
* > This function is for use in _class_init functions only.
*
* Same as gst_element_class_set_metadata(), but @longname, @classification,
* @description, and @author must be static strings or inlined strings, as
......@@ -1459,9 +1461,9 @@ gst_element_class_get_metadata (GstElementClass * klass, const gchar * key)
*
* Retrieves a list of the pad templates associated with @element_class. The
* list must not be modified by the calling code.
* <note>If you use this function in the #GInstanceInitFunc of an object class
* that has subclasses, make sure to pass the g_class parameter of the
* #GInstanceInitFunc here.</note>
* > If you use this function in the #GInstanceInitFunc of an object class
* > that has subclasses, make sure to pass the g_class parameter of the
* > #GInstanceInitFunc here.
*
* Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
* pad templates.
......@@ -1480,9 +1482,9 @@ gst_element_class_get_pad_template_list (GstElementClass * element_class)
* @name: the name of the #GstPadTemplate to get.
*
* Retrieves a padtemplate from @element_class with the given name.
* <note>If you use this function in the #GInstanceInitFunc of an object class
* that has subclasses, make sure to pass the g_class parameter of the
* #GInstanceInitFunc here.</note>
* > If you use this function in the #GInstanceInitFunc of an object class
* > that has subclasses, make sure to pass the g_class parameter of the
* > #GInstanceInitFunc here.
*
* Returns: (transfer none) (nullable): the #GstPadTemplate with the
* given name, or %NULL if none was found. No unreferencing is
......
......@@ -176,126 +176,74 @@ typedef enum {
/**
* GstStateChange:
* @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
* #GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY.
*
* * 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.
* * The element opens the device (in case feature need to be probed).
*
* #GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED.
*
* * 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 %GST_STATE_CHANGE_ASYNC and complete
* * Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete
* the state change when they have enough information. It is a requirement
* for sinks to return %GST_STATE_CHANGE_ASYNC and complete the state change
* when they receive the first buffer or %GST_EVENT_EOS (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 %GST_STATE_CHANGE_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 #GstClock and distributes this to all the children
* * A pipeline resets the running_time to 0.
*
* * Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data.
*
* #GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING.
*
* * Most elements ignore this state change.
* * The pipeline selects a #GstClock and distributes this to all the children
* before setting them to PLAYING. This means that it is only allowed to
* synchronize on the #GstClock in the PLAYING state.
* </para></listitem>
* <listitem><para>
* The pipeline uses the #GstClock and the running_time to calculate the
* * The pipeline uses the #GstClock 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
* * Sink elements stop blocking on the preroll buffer or event and start
* rendering the data.
* </para></listitem>
* <listitem><para>
* Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed
* * Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed
* to post %GST_MESSAGE_EOS when not in the PLAYING state.
* </para></listitem>