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
......@@ -991,7 +987,7 @@ parse_goption_arg (const gchar * opt,
* This function is therefore mostly used by testsuites and other memory
* profiling tools.
*
* After this call GStreamer (including this method) should not be used anymore.
* After this call GStreamer (including this method) should not be used anymore.
*/
void
gst_deinit (void)
......
......@@ -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,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.
*
......
......@@ -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
*
......@@ -1030,7 +1031,7 @@ gst_buffer_pool_config_get_params (GstStructure * config, GstCaps ** caps,
*
* Get the @allocator and @params from @config.
*
* Returns: %TRUE, if the values are set.
* Returns: %TRUE, if the values are set.
*/
gboolean
gst_buffer_pool_config_get_allocator (GstStructure * config,
......@@ -1160,7 +1161,7 @@ default_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
}
} else {
/* We're the first thread waiting, we got the wait token and have to
* write it again later
* write it again later
* OR
* We're a second thread and just consumed the flush token and block all
* other threads, in which case we must not wait and give it back
......
......@@ -143,7 +143,7 @@ struct _GstBufferPool {
* @release_buffer: release a buffer back in the pool. The default
* implementation will put the buffer back in the queue and notify any
* blocking acquire_buffer calls when the #GST_BUFFER_FLAG_TAG_MEMORY
* is not set on the buffer. If #GST_BUFFER_FLAG_TAG_MEMORY is set, the
* is not set on the buffer. If #GST_BUFFER_FLAG_TAG_MEMORY is set, the
* buffer will be freed with @free_buffer.
* @free_buffer: free a buffer. The default implementation unrefs the buffer.
* @flush_start: enter the flushing state. (Since 1.4)
......
......@@ -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,7 +20,8 @@
/**
* SECTION:gstcapsfeatures
* @short_description: A set of features in caps
* @title: GstCapsFeatures
* @short_description: A set of features in caps
* @see_also: #GstCaps
*
* #GstCapsFeatures can optionally be set on a #GstCaps to add requirements
......
......@@ -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
*
......@@ -74,7 +75,7 @@
* for unreffing the ids itself. This holds for both periodic and single shot
* notifications. The reason being that the owner of the #GstClockID has to
* keep a handle to the #GstClockID to unblock the wait on FLUSHING events or
* state changes and if the entry would be unreffed automatically, the handle
* state changes and if the entry would be unreffed automatically, the handle
* might become invalid without any notification.
*
* These clock operations do not operate on the running time, so the callbacks
......@@ -90,7 +91,7 @@
* plugins that have an internal clock but must operate with another clock
* selected by the #GstPipeline. They can track the offset and rate difference
* of their internal clock relative to the master clock by using the
* gst_clock_get_calibration() function.
* gst_clock_get_calibration() function.
*
* The master/slave synchronisation can be tuned with the #GstClock:timeout,
* #GstClock:window-size and #GstClock:window-threshold properties.
......@@ -490,23 +491,23 @@ gst_clock_id_get_time (GstClockID id)
* @jitter: (out) (allow-none): a pointer that will contain the jitter,
* can be %NULL.
*
* Perform a blocking wait on @id.
* Perform a blocking wait on @id.
* @id should have been created with gst_clock_new_single_shot_id()
* or gst_clock_new_periodic_id() and should not have been unscheduled
* with a call to gst_clock_id_unschedule().
* with a call to gst_clock_id_unschedule().
*
* If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK
* or #GST_CLOCK_EARLY, it will contain the difference
* against the clock and the time of @id when this method was
* called.
* called.
* Positive values indicate how late @id was relative to the clock
* (in which case this function will return #GST_CLOCK_EARLY).
* Negative values indicate how much time was spent waiting on the clock
* (in which case this function will return #GST_CLOCK_EARLY).
* Negative values indicate how much time was spent waiting on the clock
* before this function returned.
*
* Returns: the result of the blocking wait. #GST_CLOCK_EARLY will be returned
* if the current clock time is past the time of @id, #GST_CLOCK_OK if
* @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
* if the current clock time is past the time of @id, #GST_CLOCK_OK if
* @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
* unscheduled with gst_clock_id_unschedule().
*
* MT safe.
......@@ -1101,7 +1102,7 @@ gst_clock_get_time (GstClock * clock)
* @internal: a reference internal time
* @external: a reference external time
* @rate_num: the numerator of the rate of the clock relative to its
* internal time
* internal time
* @rate_denom: the denominator of the rate of the clock
*
* Adjusts the rate and time of @clock. A rate of 1/1 is the normal speed of
......@@ -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.
......@@ -1156,7 +1157,7 @@ gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
/**
* gst_clock_get_calibration:
* @clock: a #GstClock
* @clock: a #GstClock
* @internal: (out) (allow-none): a location to store the internal time
* @external: (out) (allow-none): a location to store the external time
* @rate_num: (out) (allow-none): a location to store the rate numerator
......@@ -1226,22 +1227,22 @@ gst_clock_slave_callback (GstClock * master, GstClockTime time,
/**
* gst_clock_set_master:
* @clock: a #GstClock
* @master: (allow-none): a master #GstClock
* @clock: a #GstClock
* @master: (allow-none): a master #GstClock
*
* Set @master as the master clock for @clock. @clock will be automatically
* calibrated so that gst_clock_get_time() reports the same time as the
* master clock.
*
* master clock.
*
* A clock provider that slaves its clock to a master can get the current
* calibration values with gst_clock_get_calibration().
*
* @master can be %NULL in which case @clock will not be slaved anymore. It will
* however keep reporting its time adjusted with the last configured rate
* however keep reporting its time adjusted with the last configured rate
* and time offsets.
*
* Returns: %TRUE if the clock is capable of being slaved to a master clock.
* Trying to set a master on a clock without the
* Returns: %TRUE if the clock is capable of being slaved to a master clock.
* Trying to set a master on a clock without the
* #GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE.
*
* MT safe.
......@@ -1314,7 +1315,7 @@ master_not_synced:
/**
* gst_clock_get_master:
* @clock: a #GstClock
* @clock: a #GstClock
*
* Get the master clock that @clock is slaved to or %NULL when the clock is
* not slaved to any master clock.
......@@ -1345,7 +1346,7 @@ gst_clock_get_master (GstClock * clock)
/**
* gst_clock_add_observation:
* @clock: a #GstClock
* @clock: a #GstClock
* @slave: a time on the slave
* @master: a time on the master
* @r_squared: (out): a pointer to hold the result
......@@ -1355,13 +1356,13 @@ gst_clock_get_master (GstClock * clock)
* are available, a linear regression algorithm is run on the
* observations and @clock is recalibrated.
*
* If this functions returns %TRUE, @r_squared will contain the
* If this functions returns %TRUE, @r_squared will contain the
* correlation coefficient of the interpolation. A value of 1.0
* means a perfect regression was performed. This value can
* be used to control the sampling frequency of the master and slave
* clocks.
*
* Returns: %TRUE if enough observations were added to run the
* Returns: %TRUE if enough observations were added to run the
* regression algorithm.
*
* MT safe.
......@@ -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
......@@ -321,7 +322,7 @@ gst_control_binding_get_value (GstControlBinding * binding,
* This function is useful if one wants to e.g. draw a graph of the control
* curve or apply a control curve sample by sample.
*
* The values are unboxed and ready to be used. The similar function
* The values are unboxed and ready to be used. The similar function
* gst_control_binding_get_g_value_array() returns the array as #GValues and is
* more suitable for bindings.
*
......
......@@ -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,