diff options
| author | Thibault Saunier <thibault.saunier@osg.samsung.com> | 2017-01-16 11:26:16 -0300 |
|---|---|---|
| committer | Thibault Saunier <thibault.saunier@osg.samsung.com> | 2017-01-27 16:36:38 -0300 |
| commit | a87b4551a6090663a1714f263d4e20fe75eb46ca (patch) | |
| tree | 4367eb5b3027851743c464bd159abb6c7325f694 | |
| parent | 76f049bc49fc6fc56ca19d64749cfbe2f601c3c9 (diff) | |
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
129 files changed, 823 insertions, 1042 deletions
@@ -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 (&argc, &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) diff --git a/gst/gstallocator.c b/gst/gstallocator.c index 367fc2a93..fcab8a187 100644 --- a/gst/gstallocator.c +++ b/gst/gstallocator.c @@ -21,6 +21,7 @@ /** * SECTION:gstallocator + * @title: GstAllocator * @short_description: allocate memory blocks * @see_also: #GstMemory * 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. * diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c index 8252b447e..7d51c6d2e 100644 --- a/gst/gstbuffer.c +++ b/gst/gstbuffer.c @@ -22,6 +22,7 @@ /** * SECTION:gstbuffer + * @title: GstBuffer * @short_description: Data-passing buffer type * @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool * diff --git a/gst/gstbufferlist.c b/gst/gstbufferlist.c index dabcd6a98..ec926457b 100644 --- a/gst/gstbufferlist.c +++ b/gst/gstbufferlist.c @@ -23,6 +23,7 @@ /** * SECTION:gstbufferlist + * @title: GstBufferList * @short_description: Lists of buffers for data-passing * @see_also: #GstPad, #GstMiniObject * diff --git a/gst/gstbufferpool.c b/gst/gstbufferpool.c index 133859d2d..f984a26e4 100644 --- a/gst/gstbufferpool.c +++ b/gst/gstbufferpool.c @@ -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 diff --git a/gst/gstbufferpool.h b/gst/gstbufferpool.h index 38c59e2a1..2c277ad23 100644 --- a/gst/gstbufferpool.h +++ b/gst/gstbufferpool.h @@ -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) diff --git a/gst/gstbus.c b/gst/gstbus.c index f94c18cf1..7bf71b649 100644 --- a/gst/gstbus.c +++ b/gst/gstbus.c @@ -21,6 +21,7 @@ /** * SECTION:gstbus + * @title: GstBus * @short_description: Asynchronous message bus subsystem * @see_also: #GstMessage, #GstElement * diff --git a/gst/gstcaps.c b/gst/gstcaps.c index c947f372a..a63731123 100644 --- a/gst/gstcaps.c +++ b/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 */ diff --git a/gst/gstcapsfeatures.c b/gst/gstcapsfeatures.c index 95e4baea4..e501b934d 100644 --- a/gst/gstcapsfeatures.c +++ b/gst/gstcapsfeatures.c @@ -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 diff --git a/gst/gstchildproxy.c b/gst/gstchildproxy.c index f2a259569..c8581a2ee 100644 --- a/gst/gstchildproxy.c +++ b/gst/gstchildproxy.c @@ -21,6 +21,7 @@ /** * SECTION:gstchildproxy + * @title: GstChildProxy * @short_description: Interface for multi child elements. * @see_also: #GstBin * diff --git a/gst/gstclock.c b/gst/gstclock.c index d3534c198..f167bad5a 100644 --- a/gst/gstclock.c +++ b/gst/gstclock.c @@ -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. * diff --git a/gst/gstclock.h b/gst/gstclock.h index 7b0d6c4b5..6ec461ada 100644 --- a/gst/gstclock.h +++ b/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 { \ diff --git a/gst/gstcompat.h b/gst/gstcompat.h index b61124681..1349ab4cd 100644 --- a/gst/gstcompat.h +++ b/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. diff --git a/gst/gstcontext.c b/gst/gstcontext.c index a90bd9c22..73cace4f3 100644 --- a/gst/gstcontext.c +++ b/gst/gstcontext.c @@ -23,6 +23,7 @@ /** * SECTION:gstcontext + * @title: GstContext * @short_description: Lightweight objects to represent element contexts * @see_also: #GstMiniObject, #GstElement * diff --git a/gst/gstcontrolbinding.c b/gst/gstcontrolbinding.c index e758ad1fb..0d73948f6 100644 --- a/gst/gstcontrolbinding.c +++ b/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 @@ -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. * diff --git a/gst/gstcontrolsource.c b/gst/gstcontrolsource.c index d9b35c72e..30d43993f 100644 --- a/gst/gstcontrolsource.c +++ b/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 diff --git a/gst/gstdebugutils.h b/gst/gstdebugutils.h index 8363e2dc9..8a1534261 100644 --- a/gst/gstdebugutils.h +++ b/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. * diff --git a/gst/gstdevice.c b/gst/gstdevice.c index 678fe14ae..c30d021ef 100644 --- a/gst/gstdevice.c +++ b/gst/gstdevice.c @@ -21,6 +21,7 @@ /** * SECTION:gstdevice + * @title: GstDevice * @short_description: Object representing a device * @see_also: #GstDeviceProvider * diff --git a/gst/gstdevicemonitor.c b/gst/gstdevicemonitor.c index d03a8139b..79c65ceb1 100644 --- a/gst/gstdevicemonitor.c +++ b/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 diff --git a/gst/gstdeviceprovider.c b/gst/gstdeviceprovider.c index e7972bbdf..f5ba92ef7 100644 --- a/gst/gstdeviceprovider.c +++ b/gst/gstdeviceprovider.c @@ -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 <joe.blogs at foo.com>" * * 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>" * * 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 diff --git a/gst/gstdeviceproviderfactory.c b/gst/gstdeviceproviderfactory.c index 305e214b5..cb4b459b3 100644 --- a/gst/gstdeviceproviderfactory.c +++ b/gst/gstdeviceproviderfactory.c @@ -23,6 +23,7 @@ /** * SECTION:gstdeviceproviderfactory + * @title: GstDeviceProviderFactory * @short_description: Create GstDeviceProviders from a factory * @see_also: #GstDeviceProvider, #GstPlugin, #GstPluginFeature, #GstPadTemplate. * diff --git a/gst/gstdynamictypefactory.c b/gst/gstdynamictypefactory.c index e6b304eea..5f52ac23f 100644 --- a/gst/gstdynamictypefactory.c +++ b/gst/gstdynamictypefactory.c @@ -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 diff --git a/gst/gstelement.c b/gst/gstelement.c index a7aa59162..bf579b48f 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -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 <joe.blogs at foo.com>" * * 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 <joe.blogs at foo.com>" * * 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 diff --git a/gst/gstelement.h b/gst/gstelement.h index ed9bf6452..ef81c1df3 100644 --- a/gst/gstelement.h +++ b/gst/gstelement.h @@ -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> - * <listitem><para> - * While streaming in PAUSED or PLAYING elements can create and remove + * * While streaming in PAUSED or PLAYING elements can create and remove * sometimes pads. - * </para></listitem> - * <listitem><para> - * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS. - * </para></listitem> - * </itemizedlist> - * @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED. - * <itemizedlist> - * <listitem><para> - * Most elements ignore this state change. - * </para></listitem> - * <listitem><para> - * The pipeline calculates the running_time based on the last selected + * * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS. + * + * #GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED. + * + * * Most elements ignore this state change. + * * The pipeline calculates the running_time based on the last selected * #GstClock and the base_time. It stores this information to continue * playback when going back to the PLAYING state. - * </para></listitem> - * <listitem><para> - * Sinks unblock any #GstClock wait calls. - * </para></listitem> - * <listitem><para> - * When a sink does not have a pending buffer to play, it returns - * %GST_STATE_CHANGE_ASYNC from this state change and completes the state + * + * * Sinks unblock any #GstClock wait calls. + * * When a sink does not have a pending buffer to play, it returns + * #GST_STATE_CHANGE_ASYNC from this state change and completes the state * change when it receives a new buffer or an %GST_EVENT_EOS. - * </para></listitem> - * <listitem><para> - * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted + * * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted * when going back to the PLAYING state. The EOS messages are queued in * #GstBin containers. - * </para></listitem> - * <listitem><para> - * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL. - * </para></listitem> - * </itemizedlist> - * @GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY. - * <itemizedlist> - * <listitem><para> - * Sinks unblock any waits in the preroll. - * </para></listitem> - * <listitem><para> - * Elements unblock any waits on devices - * </para></listitem> - * <listitem><para> - * Chain or get_range functions return %GST_FLOW_FLUSHING. - * </para></listitem> - * <listitem><para> - * The element pads are deactivated so that streaming becomes impossible and + * + * * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL. + * + * #GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY. + * + * * Sinks unblock any waits in the preroll. + * * Elements unblock any waits on devices + * * Chain or get_range functions return %GST_FLOW_FLUSHING. + * * The element pads are deactivated so that streaming becomes impossible and * all streaming threads are stopped. - * </para></listitem> - * <listitem><para> - * The sink forgets all negotiated formats - * </para></listitem> - * <listitem><para> - * Elements remove all sometimes pads - * </para></listitem> - * </itemizedlist> - * @GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL. - * <itemizedlist> - * <listitem><para> - * Elements close devices - * </para></listitem> - * <listitem><para> - * Elements reset any internal state. - * </para></listitem> - * </itemizedlist> + * * The sink forgets all negotiated formats + * * Elements remove all sometimes pads + * + * #GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL. + * + * * Elements close devices + * * Elements reset any internal state. * * These are the different state changes an element goes through. * %GST_STATE_NULL ⇒ %GST_STATE_PLAYING is called an upwards state change diff --git a/gst/gstelementfactory.c b/gst/gstelementfactory.c index 8cc4dc602..7d54d45cf 100644 --- a/gst/gstelementfactory.c +++ b/gst/gstelementfactory.c @@ -23,6 +23,7 @@ /** * SECTION:gstelementfactory + * @title: GstElementFactory * @short_description: Create GstElements from a factory * @see_also: #GstElement, #GstPlugin, #GstPluginFeature, #GstPadTemplate. * @@ -36,9 +37,8 @@ * * The following code example shows you how to create a GstFileSrc element. * - * <example> - * <title>Using an element factory</title> - * <programlisting language="c"> + * ## Using an element factory + * |[<!-- language="C" --> * #include <gst/gst.h> * * GstElement *src; @@ -51,8 +51,7 @@ * src = gst_element_factory_create (srcfactory, "src"); * g_return_if_fail (src != NULL); * ... - * </programlisting> - * </example> + * ]| */ #include "gst_private.h" diff --git a/gst/gsterror.c b/gst/gsterror.c index 6c0ef77f4..820b51e0e 100644 --- a/gst/gsterror.c +++ b/gst/gsterror.c @@ -19,6 +19,7 @@ /** * SECTION:gsterror + * @title: GstError * @short_description: Categorized error messages * @see_also: #GstMessage * @@ -66,34 +67,33 @@ * * Elements throw errors using the #GST_ELEMENT_ERROR convenience macro: * - * <example> - * <title>Throwing an error</title> - * <programlisting> + * ## Throwing an error + * + * |[ * GST_ELEMENT_ERROR (src, RESOURCE, NOT_FOUND, * (_("No file name specified for reading.")), (NULL)); - * </programlisting> - * </example> + * ]| * * Things to keep in mind: - * <itemizedlist> - * <listitem><para>Don't go off inventing new error codes. The ones + * + * * Don't go off inventing new error codes. The ones * currently provided should be enough. If you find your type of error - * does not fit the current codes, you should use FAILED.</para></listitem> - * <listitem><para>Don't provide a message if the default one suffices. + * does not fit the current codes, you should use FAILED. + * * Don't provide a message if the default one suffices. * this keeps messages more uniform. Use (%NULL) - not forgetting the - * parentheses.</para></listitem> - * <listitem><para>If you do supply a custom message, it should be + * parentheses. + * * If you do supply a custom message, it should be * marked for translation. The message should start with a capital * and end with a period. The message should describe the error in short, * in a human-readable form, and without any complex technical terms. * A user interface will present this message as the first thing a user * sees. Details, technical info, ... should go in the debug string. - * </para></listitem> - * <listitem><para>The debug string can be as you like. Again, use (%NULL) + * + * * The debug string can be as you like. Again, use (%NULL) * if there's nothing to add - file and line number will still be * passed. #GST_ERROR_SYSTEM can be used as a shortcut to give - * debug information on a system call error.</para></listitem> - * </itemizedlist> + * debug information on a system call error. + * */ /* FIXME 2.0: the entire error system needs an overhaul - it's not very diff --git a/gst/gstevent.c b/gst/gstevent.c index bf1d4da1f..815898f59 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -23,6 +23,7 @@ /** * SECTION:gstevent + * @title: GstEvent * @short_description: Structure describing events that are passed up and down * a pipeline * @see_also: #GstPad, #GstElement @@ -57,8 +58,8 @@ * ... * // construct a seek event to play the media from second 2 to 5, flush * // the pipeline to decrease latency. - * event = gst_event_new_seek (1.0, - * GST_FORMAT_TIME, + * event = gst_event_new_seek (1.0, + * GST_FORMAT_TIME, * GST_SEEK_FLAG_FLUSH, * GST_SEEK_TYPE_SET, 2 * GST_SECOND, * GST_SEEK_TYPE_SET, 5 * GST_SECOND); @@ -589,7 +590,7 @@ gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time) * * The list of @streams corresponds to the "Stream ID" of each stream to be * activated. Those ID can be obtained via the #GstStream objects present - * in #GST_EVENT_STREAM_START, #GST_EVENT_STREAM_COLLECTION or + * in #GST_EVENT_STREAM_START, #GST_EVENT_STREAM_COLLECTION or * #GST_MESSSAGE_STREAM_COLLECTION. * * Returns: (transfer full): a new select-streams event. @@ -1089,7 +1090,7 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format, * @type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is * used when a buffer arrived in time or when the sink cannot keep up with * the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not - * receiving buffers fast enough and thus has to drop late buffers. + * receiving buffers fast enough and thus has to drop late buffers. * #GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited * by the application, for example to reduce power consumption. * @@ -1229,15 +1230,15 @@ gst_event_parse_qos (GstEvent * event, GstQOSType * type, * * A pipeline has a default playback segment configured with a start * position of 0, a stop position of -1 and a rate of 1.0. The currently - * configured playback segment can be queried with #GST_QUERY_SEGMENT. + * configured playback segment can be queried with #GST_QUERY_SEGMENT. * - * @start_type and @stop_type specify how to adjust the currently configured + * @start_type and @stop_type specify how to adjust the currently configured * start and stop fields in playback segment. Adjustments can be made relative * or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE * means that the position should not be updated. * * When the rate is positive and @start has been updated, playback will start - * from the newly configured start position. + * from the newly configured start position. * * For negative rates, playback will start from the newly configured stop * position (if any). If the stop position is updated, it must be different from @@ -1641,7 +1642,7 @@ gst_event_parse_stream_start (GstEvent * event, const gchar ** stream_id) * @event: a stream-start event * @stream: (transfer none): the stream object to set * - * Set the @stream on the stream-start @event + * Set the @stream on the stream-start @event * * Since: 1.10 */ diff --git a/gst/gstformat.c b/gst/gstformat.c index aeae6c607..130fc77f1 100644 --- a/gst/gstformat.c +++ b/gst/gstformat.c @@ -23,6 +23,7 @@ /** * SECTION:gstformat + * @title: GstFormat * @short_description: Dynamically register new data formats * @see_also: #GstPad, #GstElement * diff --git a/gst/gstghostpad.c b/gst/gstghostpad.c index 04894325f..b03ae7dbd 100644 --- a/gst/gstghostpad.c +++ b/gst/gstghostpad.c @@ -24,6 +24,7 @@ /** * SECTION:gstghostpad + * @title: GstGhostPad * @short_description: Pseudo link pads * @see_also: #GstPad * diff --git a/gst/gstinfo.c b/gst/gstinfo.c index 735caefa0..4696f9e02 100644 --- a/gst/gstinfo.c +++ b/gst/gstinfo.c @@ -24,6 +24,7 @@ /** * SECTION:gstinfo + * @title: GstInfo * @short_description: Debugging and logging facilities * @see_also: #gst-running for command line parameters * and environment variables that affect the debugging output. @@ -1524,8 +1525,8 @@ gst_debug_get_color_mode (void) * If activated, debugging messages are sent to the debugging * handlers. * It makes sense to deactivate it for speed issues. - * <note><para>This function is not threadsafe. It makes sense to only call it - * during initialization.</para></note> + * > This function is not threadsafe. It makes sense to only call it + * during initialization. */ void gst_debug_set_active (gboolean active) @@ -1761,11 +1762,9 @@ gst_debug_category_free (GstDebugCategory * category) * Sets the threshold of the category to the given level. Debug information will * only be output if the threshold is lower or equal to the level of the * debugging message. - * <note><para> - * Do not use this function in production code, because other functions may - * change the threshold of categories as side effect. It is however a nice - * function to use when debugging (even from gdb). - * </para></note> + * > Do not use this function in production code, because other functions may + * > change the threshold of categories as side effect. It is however a nice + * > function to use when debugging (even from gdb). */ void gst_debug_category_set_threshold (GstDebugCategory * category, diff --git a/gst/gstinfo.h b/gst/gstinfo.h index c08b30561..f8be4d26e 100644 --- a/gst/gstinfo.h +++ b/gst/gstinfo.h @@ -482,30 +482,24 @@ G_STMT_START{ \ * Initializes a new #GstDebugCategory with the given properties and set to * the default threshold. * - * <note> - * <para> - * This macro expands to nothing if debugging is disabled. - * </para> - * <para> - * When naming your category, please follow the following conventions to ensure - * that the pattern matching for categories works as expected. It is not - * earth-shattering if you don't follow these conventions, but it would be nice - * for everyone. - * </para> - * <para> - * If you define a category for a plugin or a feature of it, name the category - * like the feature. So if you wanted to write a "filesrc" element, you would - * name the category "filesrc". Use lowercase letters only. - * If you define more than one category for the same element, append an - * underscore and an identifier to your categories, like this: "filesrc_cache" - * </para> - * <para> - * If you create a library or an application using debugging categories, use a - * common prefix followed by an underscore for all your categories. GStreamer - * uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure - * to include uppercase letters. - * </para> - * </note> + * > This macro expands to nothing if debugging is disabled. + * > + * > When naming your category, please follow the following conventions to ensure + * > that the pattern matching for categories works as expected. It is not + * > earth-shattering if you don't follow these conventions, but it would be nice + * > for everyone. + * > + * > If you define a category for a plugin or a feature of it, name the category + * > like the feature. So if you wanted to write a "filesrc" element, you would + * > name the category "filesrc". Use lowercase letters only. + * > If you define more than one category for the same element, append an + * > underscore and an identifier to your categories, like this: "filesrc_cache" + * > + * > If you create a library or an application using debugging categories, use a + * > common prefix followed by an underscore for all your categories. GStreamer + * > uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure + * > to include uppercase letters. + * */ #define GST_DEBUG_CATEGORY_INIT(cat,name,color,description) G_STMT_START{\ if (cat == NULL) \ diff --git a/gst/gstiterator.c b/gst/gstiterator.c index b15b20271..e7e5875dd 100644 --- a/gst/gstiterator.c +++ b/gst/gstiterator.c @@ -22,6 +22,7 @@ /** * SECTION:gstiterator + * @title: GstIterator * @short_description: Object to retrieve multiple elements in a threadsafe * way. * @see_also: #GstElement, #GstBin @@ -227,7 +228,7 @@ gst_list_iterator_free (GstListIterator * it) * Create a new iterator designed for iterating @list. * * The list you iterate is usually part of a data structure @owner and is - * protected with @lock. + * protected with @lock. * * The iterator will use @lock to retrieve the next item of the list and it * will then call the @item function before releasing @lock again. @@ -296,7 +297,7 @@ gst_iterator_pop (GstIterator * it) * @it: The #GstIterator to iterate * @elem: (out caller-allocates): pointer to hold next element * - * Get the next item from the iterator in @elem. + * Get the next item from the iterator in @elem. * * Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid * value. @elem must have been initialized to the type of the iterator or @@ -309,7 +310,7 @@ gst_iterator_pop (GstIterator * it) * * A return value of %GST_ITERATOR_RESYNC indicates that the element list was * concurrently updated. The user of @it should call gst_iterator_resync() to - * get the newly updated list. + * get the newly updated list. * * A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error. * diff --git a/gst/gstmemory.c b/gst/gstmemory.c index dbbb48245..0b0dba7a7 100644 --- a/gst/gstmemory.c +++ b/gst/gstmemory.c @@ -21,6 +21,7 @@ /** * SECTION:gstmemory + * @title: GstMemory * @short_description: refcounted wrapper for memory blocks * @see_also: #GstBuffer * diff --git a/gst/gstmessage.c b/gst/gstmessage.c index a1d0d2657..e426d3c45 100644 --- a/gst/gstmessage.c +++ b/gst/gstmessage.c @@ -21,6 +21,7 @@ /** * SECTION:gstmessage + * @title: GstMessage * @short_description: Lightweight objects to signal the application of * pipeline events * @see_also: #GstBus, #GstMiniObject, #GstElement @@ -1195,7 +1196,7 @@ gst_message_has_name (GstMessage * message, const gchar * name) * switch (GST_MESSAGE_TYPE (msg)) { * case GST_MESSAGE_TAG: { * GstTagList *tags = NULL; - * + * * gst_message_parse_tag (msg, &tags); * g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src)); * handle_tags (tags); @@ -1245,7 +1246,7 @@ gst_message_parse_buffering (GstMessage * message, gint * percent) /** * gst_message_set_buffering_stats: * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING. - * @mode: a buffering mode + * @mode: a buffering mode * @avg_in: the average input rate * @avg_out: the average output rate * @buffering_left: amount of buffering time left in milliseconds @@ -1318,7 +1319,7 @@ gst_message_parse_buffering_stats (GstMessage * message, * switch (GST_MESSAGE_TYPE (msg)) { * case GST_MESSAGE_STATE_CHANGED: { * GstState old_state, new_state; - * + * * gst_message_parse_state_changed (msg, &old_state, &new_state, NULL); * g_print ("Element %s changed state from %s to %s.\n", * GST_OBJECT_NAME (msg->src), @@ -1506,7 +1507,7 @@ gst_message_parse_structure_change (GstMessage * message, * case GST_MESSAGE_ERROR: { * GError *err = NULL; * gchar *dbg_info = NULL; - * + * * gst_message_parse_error (msg, &err, &dbg_info); * g_printerr ("ERROR from element %s: %s\n", * GST_OBJECT_NAME (msg->src), err->message); @@ -1696,7 +1697,7 @@ gst_message_parse_request_state (GstMessage * message, GstState * state) * * Create a new stream status message. This message is posted when a streaming * thread is created/destroyed or when the state changed. - * + * * Returns: (transfer full): the new stream status message. * * MT safe. @@ -1886,7 +1887,7 @@ gst_message_parse_step_done (GstMessage * message, GstFormat * format, * @intermediate: is this an intermediate step * * This message is posted by elements when they accept or activate a new step - * event for @amount in @format. + * event for @amount in @format. * * @active is set to %FALSE when the element accepted the new step event and has * queued it for execution in the streaming threads. @@ -1896,7 +1897,7 @@ gst_message_parse_step_done (GstMessage * message, GstFormat * format, * message is emitted, the application can queue a new step operation in the * element. * - * Returns: (transfer full): The new step_start message. + * Returns: (transfer full): The new step_start message. * * MT safe. */ @@ -2577,7 +2578,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device) * @message: a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED * @device: (out) (allow-none) (transfer full): A location where to store a * pointer to the new #GstDevice, or %NULL - * + * * Parses a device-added message. The device-added message is produced by * #GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance * of monitored devices. @@ -2755,7 +2756,7 @@ gst_message_new_stream_collection (GstObject * src, * @collection: (out) (allow-none) (transfer full): A location where to store a * pointer to the #GstStreamCollection, or %NULL * - * Parses a stream-collection message. + * Parses a stream-collection message. * * Since: 1.10 */ @@ -2903,7 +2904,7 @@ gst_message_streams_selected_get_stream (GstMessage * msg, guint idx) * @collection: (out) (allow-none) (transfer full): A location where to store a * pointer to the #GstStreamCollection, or %NULL * - * Parses a streams-selected message. + * Parses a streams-selected message. * * Since: 1.10 */ diff --git a/gst/gstmeta.c b/gst/gstmeta.c index daa26ca18..e177e588e 100644 --- a/gst/gstmeta.c +++ b/gst/gstmeta.c @@ -21,6 +21,7 @@ /** * SECTION:gstmeta + * @title: GstMeta * @short_description: Buffer metadata * * The #GstMeta structure should be included as the first member of a #GstBuffer diff --git a/gst/gstminiobject.c b/gst/gstminiobject.c index 4662f2655..cbefa86a6 100644 --- a/gst/gstminiobject.c +++ b/gst/gstminiobject.c @@ -20,6 +20,7 @@ */ /** * SECTION:gstminiobject + * @title: GstMiniObject * @short_description: Lightweight base class for the GStreamer object hierarchy * * #GstMiniObject is a simple structure that can be used to implement refcounted diff --git a/gst/gstobject.c b/gst/gstobject.c index 36da2a039..04daaacea 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -23,6 +23,7 @@ /** * SECTION:gstobject + * @title: GstObject * @short_description: Base class for the GStreamer object hierarchy * * #GstObject provides a root for the object hierarchy tree filed in by the @@ -42,9 +43,8 @@ * gst_object_set_name() and gst_object_get_name() are used to set/get the name * of the object. * - * <refsect2> - * <title>controlled properties</title> - * <para> + * ## controlled properties + * * Controlled properties offers a lightweight way to adjust gobject properties * over stream-time. It works by using time-stamped value pairs that are queued * for element-properties. At run-time the elements continuously pull value @@ -52,42 +52,29 @@ * * What needs to be changed in a #GstElement? * Very little - it is just two steps to make a plugin controllable! - * <orderedlist> - * <listitem><para> - * mark gobject-properties paramspecs that make sense to be controlled, + * + * * mark gobject-properties paramspecs that make sense to be controlled, * by GST_PARAM_CONTROLLABLE. - * </para></listitem> - * <listitem><para> - * when processing data (get, chain, loop function) at the beginning call + * + * * when processing data (get, chain, loop function) at the beginning call * gst_object_sync_values(element,timestamp). * This will make the controller update all GObject properties that are * under its control with the current values based on the timestamp. - * </para></listitem> - * </orderedlist> - * - * What needs to be done in applications? - * Again it's not a lot to change. - * <orderedlist> - * <listitem><para> - * create a #GstControlSource. + * + * What needs to be done in applications? Again it's not a lot to change. + * + * * create a #GstControlSource. * csource = gst_interpolation_control_source_new (); * g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); - * </para></listitem> - * <listitem><para> - * Attach the #GstControlSource on the controller to a property. + * + * * Attach the #GstControlSource on the controller to a property. * gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource)); - * </para></listitem> - * <listitem><para> - * Set the control values + * + * * Set the control values * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); * gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2); - * </para></listitem> - * <listitem><para> - * start your pipeline - * </para></listitem> - * </orderedlist> - * </para> - * </refsect2> + * + * * start your pipeline */ #include "gst_private.h" diff --git a/gst/gstpad.c b/gst/gstpad.c index e6bcaa8b0..f5142e6f6 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -21,6 +21,7 @@ */ /** * SECTION:gstpad + * @title: GstPad * @short_description: Object contained by elements that allows links to * other elements * @see_also: #GstPadTemplate, #GstElement, #GstEvent, #GstQuery, #GstBuffer diff --git a/gst/gstpad.h b/gst/gstpad.h index 4a8a24984..02c662206 100644 --- a/gst/gstpad.h +++ b/gst/gstpad.h @@ -205,12 +205,10 @@ const gchar* gst_pad_link_get_name (GstPadLinkReturn ret); * and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are * specified, expensive but safe @GST_PAD_LINK_CHECK_CAPS are performed. * - * <warning><para> - * Only disable some of the checks if you are 100% certain you know the link - * will not fail because of hierarchy/caps compatibility failures. If uncertain, - * use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods - * for linking the pads. - * </para></warning> + * > Only disable some of the checks if you are 100% certain you know the link + * > will not fail because of hierarchy/caps compatibility failures. If uncertain, + * > use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods + * > for linking the pads. */ typedef enum { diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c index 55ab8923d..ce272cab7 100644 --- a/gst/gstpadtemplate.c +++ b/gst/gstpadtemplate.c @@ -22,6 +22,7 @@ /** * SECTION:gstpadtemplate + * @title: GstPadTemplate * @short_description: Describe the media type of a pad. * @see_also: #GstPad, #GstElementFactory * diff --git a/gst/gstparamspecs.c b/gst/gstparamspecs.c index 6425e183f..14ae79659 100644 --- a/gst/gstparamspecs.c +++ b/gst/gstparamspecs.c @@ -18,6 +18,7 @@ */ /** * SECTION:gstparamspec + * @title: GstParamSpec * @short_description: GParamSpec implementations specific * to GStreamer * diff --git a/gst/gstparse.c b/gst/gstparse.c index 329578e98..4838d5c9a 100644 --- a/gst/gstparse.c +++ b/gst/gstparse.c @@ -24,6 +24,7 @@ /** * SECTION:gstparse + * @title: GstParse * @short_description: Get a pipeline from a text pipeline description * * These function allow to create a pipeline based on the syntax used in the diff --git a/gst/gstpipeline.c b/gst/gstpipeline.c index 554ff6eb5..ca4708fd5 100644 --- a/gst/gstpipeline.c +++ b/gst/gstpipeline.c @@ -22,6 +22,7 @@ /** * SECTION:gstpipeline + * @title: GstPipeline * @short_description: Top-level bin with clocking and bus management functionality. * @see_also: #GstElement, #GstBin, #GstClock, #GstBus diff --git a/gst/gstplugin.c b/gst/gstplugin.c index 7b5b75015..6285983de 100644 --- a/gst/gstplugin.c +++ b/gst/gstplugin.c @@ -22,6 +22,7 @@ /** * SECTION:gstplugin + * @title: GstPlugin * @short_description: Container for features loaded from a shared object module * @see_also: #GstPluginFeature, #GstElementFactory * @@ -671,7 +672,7 @@ static GMutex gst_plugin_loading_mutex; * * Loads the given plugin and refs it. Caller needs to unref after use. * - * Returns: (transfer full): a reference to the existing loaded GstPlugin, a + * Returns: (transfer full): a reference to the existing loaded GstPlugin, a * reference to the newly-loaded GstPlugin, or %NULL if an error occurred. */ GstPlugin * @@ -1285,13 +1286,13 @@ gst_plugin_load_by_name (const gchar * name) * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is * untouched. The normal use pattern of this function goes like this: * - * <programlisting> + * |[ * GstPlugin *loaded_plugin; * loaded_plugin = gst_plugin_load (plugin); * // presumably, we're no longer interested in the potentially-unloaded plugin * gst_object_unref (plugin); * plugin = loaded_plugin; - * </programlisting> + * ]| * * Returns: (transfer full): a reference to a loaded plugin, or %NULL on error. */ diff --git a/gst/gstpluginfeature.c b/gst/gstpluginfeature.c index 4b6062a9f..831236e2b 100644 --- a/gst/gstpluginfeature.c +++ b/gst/gstpluginfeature.c @@ -22,6 +22,7 @@ /** * SECTION:gstpluginfeature + * @title: GstPluginfeature * @short_description: Base class for contents of a GstPlugin * @see_also: #GstPlugin * diff --git a/gst/gstpoll.c b/gst/gstpoll.c index b2b1b681c..fd672ed40 100644 --- a/gst/gstpoll.c +++ b/gst/gstpoll.c @@ -23,6 +23,7 @@ */ /** * SECTION:gstpoll + * @title: GstPoll * @short_description: Keep track of file descriptors and make it possible * to wait on them in a cancellable way * @@ -734,7 +735,7 @@ no_socket_pair: * timeouts. * * A timeout is performed with gst_poll_wait(). Multiple timeouts can be - * performed from different threads. + * performed from different threads. * * Free-function: gst_poll_free * @@ -1636,7 +1637,7 @@ gst_poll_set_flushing (GstPoll * set, gboolean flushing) * * Write a byte to the control socket of the controllable @set. * This function is mostly useful for timer #GstPoll objects created with - * gst_poll_new_timer(). + * gst_poll_new_timer(). * * It will make any current and future gst_poll_wait() function return with * 1, meaning the control socket is set. After an equal amount of calls to diff --git a/gst/gstpreset.c b/gst/gstpreset.c index 0b560af15..795bfd7ef 100644 --- a/gst/gstpreset.c +++ b/gst/gstpreset.c @@ -20,6 +20,7 @@ */ /** * SECTION:gstpreset + * @title: GstPreset * @short_description: helper interface for element presets * * This interface offers methods to query and manipulate parameter preset sets. diff --git a/gst/gstprotection.c b/gst/gstprotection.c index 01b17a5d9..1df21fd49 100644 --- a/gst/gstprotection.c +++ b/gst/gstprotection.c @@ -19,6 +19,7 @@ /** * SECTION:gstprotection + * @title: GstProtection * @short_description: Functions and classes to support encrypted streams. * * The GstProtectionMeta class enables the information needed to decrypt a diff --git a/gst/gstquery.c b/gst/gstquery.c index 769ccaa9a..ad03f9ff0 100644 --- a/gst/gstquery.c +++ b/gst/gstquery.c @@ -23,6 +23,7 @@ /** * SECTION:gstquery + * @title: GstQuery * @short_description: Provide functions to create queries, and to set and parse * values in them. * @see_also: #GstPad, #GstElement @@ -2252,15 +2253,11 @@ gst_query_parse_nth_scheduling_mode (GstQuery * query, guint index) * * Check if @query has scheduling mode set. * - * <note> - * <para> - * When checking if upstream supports pull mode, it is usually not - * enough to just check for GST_PAD_MODE_PULL with this function, you - * also want to check whether the scheduling flags returned by - * gst_query_parse_scheduling() have the seeking flag set (meaning - * random access is supported, not only sequential pulls). - * </para> - * </note> + * > When checking if upstream supports pull mode, it is usually not + * > enough to just check for GST_PAD_MODE_PULL with this function, you + * > also want to check whether the scheduling flags returned by + * > gst_query_parse_scheduling() have the seeking flag set (meaning + * > random access is supported, not only sequential pulls). * * Returns: %TRUE when @mode is in the list of scheduling modes. */ diff --git a/gst/gstregistry.c b/gst/gstregistry.c index f16d2ebea..cc094e3ee 100644 --- a/gst/gstregistry.c +++ b/gst/gstregistry.c @@ -23,6 +23,7 @@ /** * SECTION:gstregistry + * @title: GstRegistry * @short_description: Abstract base class for management of #GstPlugin objects * @see_also: #GstPlugin, #GstPluginFeature * @@ -44,48 +45,28 @@ * * On startup, plugins are searched for in the plugin search path. The following * locations are checked in this order: - * <itemizedlist> - * <listitem> - * <para>location from --gst-plugin-path commandline option.</para> - * </listitem> - * <listitem> - * <para>the GST_PLUGIN_PATH environment variable.</para> - * </listitem> - * <listitem> - * <para>the GST_PLUGIN_SYSTEM_PATH environment variable.</para> - * </listitem> - * <listitem> - * <para>default locations (if GST_PLUGIN_SYSTEM_PATH is not set). Those - * default locations are: - * <filename>$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/</filename> - * and <filename>$prefix/libs/gstreamer-$GST_API_VERSION/</filename>. - * <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html"> - * <filename>$XDG_DATA_HOME</filename></ulink> defaults to - * <filename>$HOME/.local/share</filename>. - * </para> - * </listitem> - * </itemizedlist> + * + * * location from --gst-plugin-path commandline option. + * * the GST_PLUGIN_PATH environment variable. + * * the GST_PLUGIN_SYSTEM_PATH environment variable. + * * default locations (if GST_PLUGIN_SYSTEM_PATH is not set). + * Those default locations are: + * `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/` + * and `$prefix/libs/gstreamer-$GST_API_VERSION/`. + * [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to + * `$HOME/.local/share`. + * * The registry cache file is loaded from - * <filename>$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin</filename> - * (where - * <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html"> - * <filename>$XDG_CACHE_HOME</filename></ulink> defaults to - * <filename>$HOME/.cache</filename>) or the file listed in the GST_REGISTRY + * `$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin` + * (where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY` * env var. One reason to change the registry location is for testing. * * For each plugin that is found in the plugin search path, there could be 3 * possibilities for cached information: - * <itemizedlist> - * <listitem> - * <para>the cache may not contain information about a given file.</para> - * </listitem> - * <listitem> - * <para>the cache may have stale information.</para> - * </listitem> - * <listitem> - * <para>the cache may have current information.</para> - * </listitem> - * </itemizedlist> + * + * * the cache may not contain information about a given file. + * * the cache may have stale information. + * * the cache may have current information. * * In the first two cases, the plugin is loaded and the cache updated. In * addition to these cases, the cache may have entries for plugins that are not @@ -97,7 +78,7 @@ * checked to make sure the information is minimally valid. If not, the entry is * simply dropped. * - * <emphasis role="bold">Implementation notes:</emphasis> + * ## Implementation notes: * * The "cache" and "registry" are different concepts and can represent * different sets of plugins. For various reasons, at init time, the cache is diff --git a/gst/gstsample.c b/gst/gstsample.c index e61ff6784..219db6bac 100644 --- a/gst/gstsample.c +++ b/gst/gstsample.c @@ -21,6 +21,7 @@ /** * SECTION:gstsample + * @title: GstSample * @short_description: A media sample * @see_also: #GstBuffer, #GstCaps, #GstSegment * diff --git a/gst/gstsegment.c b/gst/gstsegment.c index fbb71e3e7..8d4183ea4 100644 --- a/gst/gstsegment.c +++ b/gst/gstsegment.c @@ -28,6 +28,7 @@ /** * SECTION:gstsegment + * @title: GstSegment * @short_description: Structure describing the configured region of interest * in a media file. * @see_also: #GstEvent @@ -36,10 +37,9 @@ * interest in a media file, called a segment. * * The structure can be used for two purposes: - * <itemizedlist> - * <listitem><para>performing seeks (handling seek events)</para></listitem> - * <listitem><para>tracking playback regions (handling newsegment events)</para></listitem> - * </itemizedlist> + * + * * performing seeks (handling seek events) + * * tracking playback regions (handling newsegment events) * * The segment is usually configured by the application with a seek event which * is propagated upstream and eventually handled by an element that performs the seek. diff --git a/gst/gststreamcollection.c b/gst/gststreamcollection.c index 8e848ded9..df53c593d 100644 --- a/gst/gststreamcollection.c +++ b/gst/gststreamcollection.c @@ -26,6 +26,7 @@ /** * SECTION:gststreamcollection + * @title: GstStreamCollection * @short_description: Base class for collection of streams * * Since: 1.10 diff --git a/gst/gststreams.c b/gst/gststreams.c index 28741d8b2..b61e61b45 100644 --- a/gst/gststreams.c +++ b/gst/gststreams.c @@ -26,6 +26,7 @@ /** * SECTION:gststreams + * @title: GstStreams * @short_description: Base class for stream objects * * A #GstStream is a high-level object defining a stream of data which is, or diff --git a/gst/gststructure.c b/gst/gststructure.c index c35703b81..8166e4795 100644 --- a/gst/gststructure.c +++ b/gst/gststructure.c @@ -21,6 +21,7 @@ /** * SECTION:gststructure + * @title: GstStructure * @short_description: Generic structure containing fields of names and values * @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery * diff --git a/gst/gstsystemclock.c b/gst/gstsystemclock.c index dbdecff6f..1fc88a2e5 100644 --- a/gst/gstsystemclock.c +++ b/gst/gstsystemclock.c @@ -22,6 +22,7 @@ /** * SECTION:gstsystemclock + * @title: GstSystemClock * @short_description: Default clock that uses the current system time * @see_also: #GstClock * diff --git a/gst/gsttaglist.c b/gst/gsttaglist.c index e851961cc..dd036de0e 100644 --- a/gst/gsttaglist.c +++ b/gst/gsttaglist.c @@ -21,6 +21,7 @@ /** * SECTION:gsttaglist + * @title: GstTagList * @short_description: List of tags and values used to describe media metadata * * List of tags and values used to describe media metadata. diff --git a/gst/gsttagsetter.c b/gst/gsttagsetter.c index dca1ccb1b..ea54c3574 100644 --- a/gst/gsttagsetter.c +++ b/gst/gsttagsetter.c @@ -21,6 +21,7 @@ /** * SECTION:gsttagsetter + * @title: GstTagsetter * @short_description: Element interface that allows setting and retrieval * of media metadata * @@ -29,7 +30,7 @@ * Elements that support changing a stream's metadata will implement this * interface. Examples of such elements are 'vorbisenc', 'theoraenc' and * 'id3v2mux'. - * + * * If you just want to retrieve metadata in your application then all you * need to do is watch for tag messages on your pipeline's bus. This * interface is only for setting metadata, not for extracting it. To set tags @@ -38,7 +39,7 @@ * setting the #GstTagMergeMode that is used for tag events that arrive at the * tagsetter element (default mode is to keep existing tags). * The application should do that before the element goes to %GST_STATE_PAUSED. - * + * * Elements implementing the #GstTagSetter interface often have to merge * any tags received from upstream and the tags set by the application via * the interface. This can be done like this: @@ -49,19 +50,19 @@ * const GstTagList *event_tags; * GstTagSetter *tagsetter; * GstTagList *result; - * + * * tagsetter = GST_TAG_SETTER (element); - * + * * merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter); * application_tags = gst_tag_setter_get_tag_list (tagsetter); * event_tags = (const GstTagList *) element->event_tags; - * + * * GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode); * GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags); * GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags); - * + * * result = gst_tag_list_merge (application_tags, event_tags, merge_mode); - * + * * GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result); * ]| */ diff --git a/gst/gsttask.c b/gst/gsttask.c index 190c4d61b..d5ce87c64 100644 --- a/gst/gsttask.c +++ b/gst/gsttask.c @@ -22,6 +22,7 @@ /** * SECTION:gsttask + * @title: GstTask * @short_description: Abstraction of GStreamer streaming threads. * @see_also: #GstElement, #GstPad * diff --git a/gst/gsttaskpool.c b/gst/gsttaskpool.c index 20b8aa41b..18f0a610c 100644 --- a/gst/gsttaskpool.c +++ b/gst/gsttaskpool.c @@ -21,6 +21,7 @@ /** * SECTION:gsttaskpool + * @title: GstTaskPool * @short_description: Pool of GStreamer streaming threads * @see_also: #GstTask, #GstPad * @@ -255,7 +256,7 @@ not_supported: * @pool: a #GstTaskPool * @id: the id * - * Join a task and/or return it to the pool. @id is the id obtained from + * Join a task and/or return it to the pool. @id is the id obtained from * gst_task_pool_push(). */ void diff --git a/gst/gsttoc.c b/gst/gsttoc.c index b1732b237..f501348e7 100644 --- a/gst/gsttoc.c +++ b/gst/gsttoc.c @@ -21,6 +21,7 @@ /** * SECTION:gsttoc + * @title: GstToc * @short_description: Generic table of contents support * @see_also: #GstStructure, #GstEvent, #GstMessage, #GstQuery * diff --git a/gst/gsttocsetter.c b/gst/gsttocsetter.c index f5c7ea5d1..c746f23f0 100644 --- a/gst/gsttocsetter.c +++ b/gst/gsttocsetter.c @@ -21,6 +21,7 @@ /** * SECTION:gsttocsetter + * @title: GstTocSetter * @short_description: Element interface that allows setting and retrieval * of the TOC * @@ -28,13 +29,13 @@ * * Elements that support some kind of chapters or editions (or tracks like in * the FLAC cue sheet) will implement this interface. - * + * * If you just want to retrieve the TOC in your application then all you * need to do is watch for TOC messages on your pipeline's bus (or you can * perform TOC query). This interface is only for setting TOC data, not for * extracting it. To set TOC from the application, find proper tocsetter element * and set TOC using gst_toc_setter_set_toc(). - * + * * Elements implementing the #GstTocSetter interface can extend existing TOC * by getting extend UID for that (you can use gst_toc_find_entry() to retrieve it) * with any TOC entries received from downstream. @@ -127,7 +128,6 @@ gst_toc_setter_reset (GstTocSetter * setter) * Return current TOC the setter uses. The TOC should not be * modified without making it writable first. * - * * Returns: (transfer full) (nullable): TOC set, or %NULL. Unref with * gst_toc_unref() when no longer needed */ diff --git a/gst/gsttracer.c b/gst/gsttracer.c index 57d6c81fb..a75fb994c 100644 --- a/gst/gsttracer.c +++ b/gst/gsttracer.c @@ -21,6 +21,7 @@ /** * SECTION:gsttracer + * @title: GstTracer * @short_description: Tracing base class * * Tracing modules will subclass #GstTracer and register through diff --git a/gst/gsttracerfactory.c b/gst/gsttracerfactory.c index 65fd06694..3e0100c96 100644 --- a/gst/gsttracerfactory.c +++ b/gst/gsttracerfactory.c @@ -21,6 +21,7 @@ /** * SECTION:gsttracerfactory + * @title: GstTracerFactory * @short_description: Information about registered tracer functions * * Use gst_tracer_factory_get_list() to get a list of tracer factories known to diff --git a/gst/gsttracerrecord.c b/gst/gsttracerrecord.c index 022f1694d..00102bdd1 100644 --- a/gst/gsttracerrecord.c +++ b/gst/gsttracerrecord.c @@ -21,6 +21,7 @@ /** * SECTION:gsttracerrecord + * @title: GstTracerRecord * @short_description: Trace log entry class * * Tracing modules will create instances of this class to announce the data they @@ -175,9 +176,7 @@ gst_tracer_record_init (GstTracerRecord * self) * pointer type values must not be NULL - the underlying serialisation can not * handle that right now. * - * <note><para> - * Please note that this is still under discussion and subject to change. - * </para></note> + * > Please note that this is still under discussion and subject to change. * * Returns: a new #GstTracerRecord */ @@ -236,9 +235,8 @@ gst_tracer_record_new (const gchar * name, const gchar * firstfield, ...) * * Right now this is using the gstreamer debug log with the level TRACE (7) and * the category "GST_TRACER". - * <note><para> - * Please note that this is still under discussion and subject to change. - * </para></note> + * + * > Please note that this is still under discussion and subject to change. */ void gst_tracer_record_log (GstTracerRecord * self, ...) diff --git a/gst/gsttypefind.c b/gst/gsttypefind.c index e0ca96fd9..93ea3cd10 100644 --- a/gst/gsttypefind.c +++ b/gst/gsttypefind.c @@ -21,6 +21,7 @@ /** * SECTION:gsttypefind + * @title: GstTypefind * @short_description: Stream type detection * * The following functions allow you to detect the media type of an unknown diff --git a/gst/gsttypefindfactory.c b/gst/gsttypefindfactory.c index 87a15738a..fe6b3754d 100644 --- a/gst/gsttypefindfactory.c +++ b/gst/gsttypefindfactory.c @@ -21,6 +21,7 @@ /** * SECTION:gsttypefindfactory + * @title: GstTypeFindFactory * @short_description: Information about registered typefind functions * * These functions allow querying informations about registered typefind diff --git a/gst/gsturi.c b/gst/gsturi.c index cb0d01b9e..3312e33fd 100644 --- a/gst/gsturi.c +++ b/gst/gsturi.c @@ -25,6 +25,7 @@ /** * SECTION:gsturihandler + * @title: GstUriHandler * @short_description: Interface to ease URI handling in plugins. * * The #GstURIHandler is an interface that is implemented by Source and Sink @@ -960,6 +961,7 @@ beach: /** * SECTION:gsturi + * @title: GstUri * @short_description: URI parsing and manipulation. * * A #GstUri object can be used to parse and split a URI string into its diff --git a/gst/gstutils.c b/gst/gstutils.c index 379faf38b..31a23c8bf 100644 --- a/gst/gstutils.c +++ b/gst/gstutils.c @@ -25,6 +25,7 @@ /** * SECTION:gstutils + * @title: GstUtils * @short_description: Various utility functions * */ @@ -4092,10 +4093,10 @@ gst_log2 (GstClockTime in) * %NULL, an allocation will take place. @temp should have at least the same * amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime). * - * <note>This function assumes (x,y) values with reasonable large differences - * between them. It will not calculate the exact results if the differences - * between neighbouring values are too small due to not being able to - * represent sub-integer values during the calculations.</note> + * > This function assumes (x,y) values with reasonable large differences + * > between them. It will not calculate the exact results if the differences + * > between neighbouring values are too small due to not being able to + * > represent sub-integer values during the calculations. * * Returns: %TRUE if the linear regression was successfully calculated * diff --git a/gst/gstvalue.c b/gst/gstvalue.c index 746b3ef51..0ee65b3e2 100644 --- a/gst/gstvalue.c +++ b/gst/gstvalue.c @@ -19,6 +19,7 @@ /** * SECTION:gstvalue + * @title: GstValue * @short_description: GValue implementations specific * to GStreamer * diff --git a/gst/gstvalue.h b/gst/gstvalue.h index d45d5f86e..19363c08b 100644 --- a/gst/gstvalue.h +++ b/gst/gstvalue.h @@ -36,11 +36,11 @@ G_BEGIN_DECLS * * Transform four characters into a #guint32 fourcc value with host * endianness. - * <informalexample> - * <programlisting> + * + * |[ * guint32 fourcc = GST_MAKE_FOURCC ('M', 'J', 'P', 'G'); - * </programlisting> - * </informalexample> + * ]| + * */ #define GST_MAKE_FOURCC(a,b,c,d) ((guint32)((a)|(b)<<8|(c)<<16|(d)<<24)) @@ -52,11 +52,11 @@ G_BEGIN_DECLS * endianness. * Caller is responsible for ensuring the input string consists of at least * four characters. - * <informalexample> - * <programlisting> + * + * |[ * guint32 fourcc = GST_STR_FOURCC ("MJPG"); - * </programlisting> - * </informalexample> + * ]| + * */ #define GST_STR_FOURCC(f) ((guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))) @@ -65,11 +65,11 @@ G_BEGIN_DECLS * * Can be used together with #GST_FOURCC_ARGS to properly output a * #guint32 fourcc value in a printf()-style text message. - * <informalexample> - * <programlisting> + * + * |[ * printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc)); - * </programlisting> - * </informalexample> + * ]| + * */ #define GST_FOURCC_FORMAT "c%c%c%c" diff --git a/libs/gst/base/gstadapter.c b/libs/gst/base/gstadapter.c index 18c9d4548..bd62abe7a 100644 --- a/libs/gst/base/gstadapter.c +++ b/libs/gst/base/gstadapter.c @@ -20,6 +20,7 @@ /** * SECTION:gstadapter + * @title: GstAdapter * @short_description: adapts incoming data on a sink pad into chunks of N bytes * * This class is for elements that receive buffers in an undesired size. @@ -1766,7 +1767,7 @@ gst_adapter_masked_scan_uint32_peek (GstAdapter * adapter, guint32 mask, * Returns: offset of the first match, or -1 if no match was found. * * Example: - * <programlisting> + * |[ * // Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff * * gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256); @@ -1783,7 +1784,7 @@ gst_adapter_masked_scan_uint32_peek (GstAdapter * adapter, guint32 mask, * // -> returns 2 * gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4); * // -> returns -1 - * </programlisting> + * ]| */ gssize gst_adapter_masked_scan_uint32 (GstAdapter * adapter, guint32 mask, diff --git a/libs/gst/base/gstbaseparse.c b/libs/gst/base/gstbaseparse.c index 2751239ca..7386168d7 100644 --- a/libs/gst/base/gstbaseparse.c +++ b/libs/gst/base/gstbaseparse.c @@ -23,6 +23,7 @@ /** * SECTION:gstbaseparse + * @title: GstBaseParse * @short_description: Base class for stream parsers * @see_also: #GstBaseTransform * @@ -30,109 +31,88 @@ * into separate audio/video/whatever frames. * * It provides for: - * <itemizedlist> - * <listitem><para>provides one sink pad and one source pad</para></listitem> - * <listitem><para>handles state changes</para></listitem> - * <listitem><para>can operate in pull mode or push mode</para></listitem> - * <listitem><para>handles seeking in both modes</para></listitem> - * <listitem><para>handles events (SEGMENT/EOS/FLUSH)</para></listitem> - * <listitem><para> - * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT) - * </para></listitem> - * <listitem><para>handles flushing</para></listitem> - * </itemizedlist> + * + * * provides one sink pad and one source pad + * * handles state changes + * * can operate in pull mode or push mode + * * handles seeking in both modes + * * handles events (SEGMENT/EOS/FLUSH) + * * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT) + * * handles flushing * * The purpose of this base class is to provide the basic functionality of * a parser and share a lot of rather complex code. * - * Description of the parsing mechanism: - * <orderedlist> - * <listitem> - * <itemizedlist><title>Set-up phase</title> - * <listitem><para> - * #GstBaseParse calls @start to inform subclass that data processing is - * about to start now. - * </para></listitem> - * <listitem><para> - * #GstBaseParse class calls @set_sink_caps to inform the subclass about - * incoming sinkpad caps. Subclass could already set the srcpad caps - * accordingly, but this might be delayed until calling - * gst_base_parse_finish_frame() with a non-queued frame. - * </para></listitem> - * <listitem><para> - * At least at this point subclass needs to tell the #GstBaseParse class - * how big data chunks it wants to receive (min_frame_size). It can do - * this with gst_base_parse_set_min_frame_size(). - * </para></listitem> - * <listitem><para> - * #GstBaseParse class sets up appropriate data passing mode (pull/push) - * and starts to process the data. - * </para></listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist> - * <title>Parsing phase</title> - * <listitem><para> - * #GstBaseParse gathers at least min_frame_size bytes of data either - * by pulling it from upstream or collecting buffers in an internal - * #GstAdapter. - * </para></listitem> - * <listitem><para> - * A buffer of (at least) min_frame_size bytes is passed to subclass with - * @handle_frame. Subclass checks the contents and can optionally - * return GST_FLOW_OK along with an amount of data to be skipped to find - * a valid frame (which will result in a subsequent DISCONT). - * If, otherwise, the buffer does not hold a complete frame, - * @handle_frame can merely return and will be called again when additional - * data is available. In push mode this amounts to an - * additional input buffer (thus minimal additional latency), in pull mode - * this amounts to some arbitrary reasonable buffer size increase. - * Of course, gst_base_parse_set_min_frame_size() could also be used if a - * very specific known amount of additional data is required. - * If, however, the buffer holds a complete valid frame, it can pass - * the size of this frame to gst_base_parse_finish_frame(). - * If acting as a converter, it can also merely indicate consumed input data - * while simultaneously providing custom output data. - * Note that baseclass performs some processing (such as tracking - * overall consumed data rate versus duration) for each finished frame, - * but other state is only updated upon each call to @handle_frame - * (such as tracking upstream input timestamp). - * </para><para> - * Subclass is also responsible for setting the buffer metadata - * (e.g. buffer timestamp and duration, or keyframe if applicable). - * (although the latter can also be done by #GstBaseParse if it is - * appropriately configured, see below). Frame is provided with - * timestamp derived from upstream (as much as generally possible), - * duration obtained from configuration (see below), and offset - * if meaningful (in pull mode). - * </para><para> - * Note that @check_valid_frame might receive any small - * amount of input data when leftover data is being drained (e.g. at EOS). - * </para></listitem> - * <listitem><para> - * As part of finish frame processing, - * just prior to actually pushing the buffer in question, - * it is passed to @pre_push_frame which gives subclass yet one - * last chance to examine buffer metadata, or to send some custom (tag) - * events, or to perform custom (segment) filtering. - * </para></listitem> - * <listitem><para> - * During the parsing process #GstBaseParseClass will handle both srcpad - * and sinkpad events. They will be passed to subclass if @event or - * @src_event callbacks have been provided. - * </para></listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist><title>Shutdown phase</title> - * <listitem><para> - * #GstBaseParse class calls @stop to inform the subclass that data - * parsing will be stopped. - * </para></listitem> - * </itemizedlist> - * </listitem> - * </orderedlist> + * # Description of the parsing mechanism: + * + * ## Set-up phase + * + * * #GstBaseParse calls @start to inform subclass that data processing is + * about to start now. + * + * * #GstBaseParse class calls @set_sink_caps to inform the subclass about + * incoming sinkpad caps. Subclass could already set the srcpad caps + * accordingly, but this might be delayed until calling + * gst_base_parse_finish_frame() with a non-queued frame. + * + * * At least at this point subclass needs to tell the #GstBaseParse class + * how big data chunks it wants to receive (min_frame_size). It can do + * this with gst_base_parse_set_min_frame_size(). + * + * * #GstBaseParse class sets up appropriate data passing mode (pull/push) + * and starts to process the data. + * + * ## Parsing phase + * + * * #GstBaseParse gathers at least min_frame_size bytes of data either + * by pulling it from upstream or collecting buffers in an internal + * #GstAdapter. + * + * * A buffer of (at least) min_frame_size bytes is passed to subclass with + * @handle_frame. Subclass checks the contents and can optionally + * return GST_FLOW_OK along with an amount of data to be skipped to find + * a valid frame (which will result in a subsequent DISCONT). + * If, otherwise, the buffer does not hold a complete frame, + * @handle_frame can merely return and will be called again when additional + * data is available. In push mode this amounts to an + * additional input buffer (thus minimal additional latency), in pull mode + * this amounts to some arbitrary reasonable buffer size increase. + * Of course, gst_base_parse_set_min_frame_size() could also be used if a + * very specific known amount of additional data is required. + * If, however, the buffer holds a complete valid frame, it can pass + * the size of this frame to gst_base_parse_finish_frame(). + * If acting as a converter, it can also merely indicate consumed input data + * while simultaneously providing custom output data. + * Note that baseclass performs some processing (such as tracking + * overall consumed data rate versus duration) for each finished frame, + * but other state is only updated upon each call to @handle_frame + * (such as tracking upstream input timestamp). + * + * Subclass is also responsible for setting the buffer metadata + * (e.g. buffer timestamp and duration, or keyframe if applicable). + * (although the latter can also be done by #GstBaseParse if it is + * appropriately configured, see below). Frame is provided with + * timestamp derived from upstream (as much as generally possible), + * duration obtained from configuration (see below), and offset + * if meaningful (in pull mode). + * + * Note that @check_valid_frame might receive any small + * amount of input data when leftover data is being drained (e.g. at EOS). + * + * * As part of finish frame processing, + * just prior to actually pushing the buffer in question, + * it is passed to @pre_push_frame which gives subclass yet one + * last chance to examine buffer metadata, or to send some custom (tag) + * events, or to perform custom (segment) filtering. + * + * * During the parsing process #GstBaseParseClass will handle both srcpad + * and sinkpad events. They will be passed to subclass if @event or + * @src_event callbacks have been provided. + * + * ## Shutdown phase + * + * * #GstBaseParse class calls @stop to inform the subclass that data + * parsing will be stopped. * * Subclass is responsible for providing pad template caps for * source and sink pads. The pads need to be named "sink" and "src". It also @@ -151,44 +131,30 @@ * and end of data processing. * * Things that subclass need to take care of: - * <itemizedlist> - * <listitem><para>Provide pad templates</para></listitem> - * <listitem><para> - * Fixate the source pad caps when appropriate - * </para></listitem> - * <listitem><para> - * Inform base class how big data chunks should be retrieved. This is - * done with gst_base_parse_set_min_frame_size() function. - * </para></listitem> - * <listitem><para> - * Examine data chunks passed to subclass with @handle_frame and pass - * proper frame(s) to gst_base_parse_finish_frame(), and setting src pad - * caps and timestamps on frame. - * </para></listitem> - * <listitem><para>Provide conversion functions</para></listitem> - * <listitem><para> - * Update the duration information with gst_base_parse_set_duration() - * </para></listitem> - * <listitem><para> - * Optionally passthrough using gst_base_parse_set_passthrough() - * </para></listitem> - * <listitem><para> - * Configure various baseparse parameters using - * gst_base_parse_set_average_bitrate(), gst_base_parse_set_syncable() - * and gst_base_parse_set_frame_rate(). - * </para></listitem> - * <listitem><para> - * In particular, if subclass is unable to determine a duration, but - * parsing (or specs) yields a frames per seconds rate, then this can be - * provided to #GstBaseParse to enable it to cater for - * buffer time metadata (which will be taken from upstream as much as - * possible). Internally keeping track of frame durations and respective - * sizes that have been pushed provides #GstBaseParse with an estimated - * bitrate. A default @convert (used if not overridden) will then use these - * rates to perform obvious conversions. These rates are also used to - * update (estimated) duration at regular frame intervals. - * </para></listitem> - * </itemizedlist> + * + * * Provide pad templates + * * Fixate the source pad caps when appropriate + * * Inform base class how big data chunks should be retrieved. This is + * done with gst_base_parse_set_min_frame_size() function. + * * Examine data chunks passed to subclass with @handle_frame and pass + * proper frame(s) to gst_base_parse_finish_frame(), and setting src pad + * caps and timestamps on frame. + * * Provide conversion functions + * * Update the duration information with gst_base_parse_set_duration() + * * Optionally passthrough using gst_base_parse_set_passthrough() + * * Configure various baseparse parameters using + * gst_base_parse_set_average_bitrate(), gst_base_parse_set_syncable() + * and gst_base_parse_set_frame_rate(). + * + * * In particular, if subclass is unable to determine a duration, but + * parsing (or specs) yields a frames per seconds rate, then this can be + * provided to #GstBaseParse to enable it to cater for + * buffer time metadata (which will be taken from upstream as much as + * possible). Internally keeping track of frame durations and respective + * sizes that have been pushed provides #GstBaseParse with an estimated + * bitrate. A default @convert (used if not overridden) will then use these + * rates to perform obvious conversions. These rates are also used to + * update (estimated) duration at regular frame intervals. * */ diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c index dccf3ce1b..543245033 100644 --- a/libs/gst/base/gstbasesink.c +++ b/libs/gst/base/gstbasesink.c @@ -21,6 +21,7 @@ /** * SECTION:gstbasesink + * @title: GstBaseSink * @short_description: Base class for sink elements * @see_also: #GstBaseTransform, #GstBaseSrc * @@ -51,7 +52,7 @@ * "Sink name", * "Sink", * "My Sink element", - * "The author <my.sink@my.email>"); + * "The author <my.sink@my.email>"); * } * ]| * @@ -98,7 +99,7 @@ * should configure itself to process a specific media type. * * The #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() virtual methods - * will be called when resources should be allocated. Any + * will be called when resources should be allocated. Any * #GstBaseSinkClass.preroll(), #GstBaseSinkClass.render() and * #GstBaseSinkClass.set_caps() function will be called between the * #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() calls. @@ -1330,7 +1331,7 @@ gst_base_sink_get_blocksize (GstBaseSink * sink) * * Set the time that will be inserted between rendered buffers. This * can be used to control the maximum buffers per second that the sink - * will render. + * will render. */ void gst_base_sink_set_throttle_time (GstBaseSink * sink, guint64 throttle) @@ -1347,7 +1348,7 @@ gst_base_sink_set_throttle_time (GstBaseSink * sink, guint64 throttle) * gst_base_sink_get_throttle_time: * @sink: a #GstBaseSink * - * Get the time that will be inserted between frames to control the + * Get the time that will be inserted between frames to control the * maximum buffers per second. * * Returns: the number of nanoseconds @sink will put between frames. @@ -4104,7 +4105,7 @@ paused: } } else if (result == GST_FLOW_NOT_LINKED || result <= GST_FLOW_EOS) { /* for fatal errors we post an error message, post the error - * first so the app knows about the error first. + * first so the app knows about the error first. * wrong-state is not a fatal error because it happens due to * flushing and posting an error message in that case is the * wrong thing to do, e.g. when basesrc is doing a flushing diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c index 7a3e211f9..1e50db2e9 100644 --- a/libs/gst/base/gstbasesrc.c +++ b/libs/gst/base/gstbasesrc.c @@ -22,16 +22,16 @@ /** * SECTION:gstbasesrc + * @title: GstBaseSrc * @short_description: Base class for getrange based source elements * @see_also: #GstPushSrc, #GstBaseTransform, #GstBaseSink * * This is a generic base class for source elements. The following * types of sources are supported: - * <itemizedlist> - * <listitem><para>random access sources like files</para></listitem> - * <listitem><para>seekable sources</para></listitem> - * <listitem><para>live sources</para></listitem> - * </itemizedlist> + * + * * random access sources like files + * * seekable sources + * * live sources * * The source can be configured to operate in any #GstFormat with the * gst_base_src_set_format() method. The currently set format determines @@ -40,30 +40,20 @@ * * #GstBaseSrc always supports push mode scheduling. If the following * conditions are met, it also supports pull mode scheduling: - * <itemizedlist> - * <listitem><para>The format is set to %GST_FORMAT_BYTES (default).</para> - * </listitem> - * <listitem><para>#GstBaseSrcClass.is_seekable() returns %TRUE.</para> - * </listitem> - * </itemizedlist> + * + * * The format is set to %GST_FORMAT_BYTES (default). + * * #GstBaseSrcClass.is_seekable() returns %TRUE. * * If all the conditions are met for operating in pull mode, #GstBaseSrc is * automatically seekable in push mode as well. The following conditions must * be met to make the element seekable in push mode when the format is not * %GST_FORMAT_BYTES: - * <itemizedlist> - * <listitem><para> - * #GstBaseSrcClass.is_seekable() returns %TRUE. - * </para></listitem> - * <listitem><para> - * #GstBaseSrcClass.query() can convert all supported seek formats to the - * internal format as set with gst_base_src_set_format(). - * </para></listitem> - * <listitem><para> - * #GstBaseSrcClass.do_seek() is implemented, performs the seek and returns - * %TRUE. - * </para></listitem> - * </itemizedlist> + * + * * #GstBaseSrcClass.is_seekable() returns %TRUE. + * * #GstBaseSrcClass.query() can convert all supported seek formats to the + * internal format as set with gst_base_src_set_format(). + * * #GstBaseSrcClass.do_seek() is implemented, performs the seek and returns + * %TRUE. * * When the element does not meet the requirements to operate in pull mode, the * offset and length in the #GstBaseSrcClass.create() method should be ignored. @@ -125,13 +115,12 @@ * "Source name", * "Source", * "My Source element", - * "The author <my.sink@my.email>"); + * "The author <my.sink@my.email>"); * } * ]| * - * <refsect2> - * <title>Controlled shutdown of live sources in applications</title> - * <para> + * ## Controlled shutdown of live sources in applications + * * Applications that record from a live source may want to stop recording * in a controlled way, so that the recording is stopped, but the data * already in the pipeline is processed to the end (remember that many live @@ -149,8 +138,7 @@ * After the EOS has been sent to the element, the application should wait for * an EOS message to be posted on the pipeline's bus. Once this EOS message is * received, it may safely shut down the entire pipeline. - * </para> - * </refsect2> + * */ #ifdef HAVE_CONFIG_H diff --git a/libs/gst/base/gstbasetransform.c b/libs/gst/base/gstbasetransform.c index 1a4ac857f..e10a32845 100644 --- a/libs/gst/base/gstbasetransform.c +++ b/libs/gst/base/gstbasetransform.c @@ -23,6 +23,7 @@ /** * SECTION:gstbasetransform + * @title: GstBaseTransform * @short_description: Base class for simple transform filters * @see_also: #GstBaseSrc, #GstBaseSink * @@ -36,172 +37,100 @@ * for more concrete use cases. * * It provides for: - * <itemizedlist> - * <listitem><para>one sinkpad and one srcpad</para></listitem> - * <listitem><para> - * Possible formats on sink and source pad implemented - * with custom transform_caps function. By default uses - * same format on sink and source. - * </para></listitem> - * <listitem><para>Handles state changes</para></listitem> - * <listitem><para>Does flushing</para></listitem> - * <listitem><para>Push mode</para></listitem> - * <listitem><para> - * Pull mode if the sub-class transform can operate on arbitrary data - * </para></listitem> - * </itemizedlist> - * - * <refsect2> - * <title>Use Cases</title> - * <para> - * <orderedlist> - * <listitem> - * <itemizedlist><title>Passthrough mode</title> - * <listitem><para> - * Element has no interest in modifying the buffer. It may want to inspect it, + * + * * one sinkpad and one srcpad + * * Possible formats on sink and source pad implemented + * with custom transform_caps function. By default uses + * same format on sink and source. + * + * * Handles state changes + * * Does flushing + * * Push mode + * * Pull mode if the sub-class transform can operate on arbitrary data + * + * # Use Cases + * + * ## Passthrough mode + * + * * Element has no interest in modifying the buffer. It may want to inspect it, * in which case the element should have a transform_ip function. If there * is no transform_ip function in passthrough mode, the buffer is pushed * intact. - * </para></listitem> - * <listitem><para> - * The #GstBaseTransformClass.passthrough_on_same_caps variable + * + * * The #GstBaseTransformClass.passthrough_on_same_caps variable * will automatically set/unset passthrough based on whether the * element negotiates the same caps on both pads. - * </para></listitem> - * <listitem><para> - * #GstBaseTransformClass.passthrough_on_same_caps on an element that + * + * * #GstBaseTransformClass.passthrough_on_same_caps on an element that * doesn't implement a transform_caps function is useful for elements that * only inspect data (such as level) - * </para></listitem> - * </itemizedlist> - * <itemizedlist> - * <title>Example elements</title> - * <listitem>Level</listitem> - * <listitem>Videoscale, audioconvert, videoconvert, audioresample in - * certain modes.</listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist> - * <title>Modifications in-place - input buffer and output buffer are the - * same thing.</title> - * <listitem><para> - * The element must implement a transform_ip function. - * </para></listitem> - * <listitem><para> - * Output buffer size must <= input buffer size - * </para></listitem> - * <listitem><para> - * If the always_in_place flag is set, non-writable buffers will be copied - * and passed to the transform_ip function, otherwise a new buffer will be - * created and the transform function called. - * </para></listitem> - * <listitem><para> - * Incoming writable buffers will be passed to the transform_ip function - * immediately. </para></listitem> - * <listitem><para> - * only implementing transform_ip and not transform implies always_in_place - * = %TRUE - * </para></listitem> - * </itemizedlist> - * <itemizedlist> - * <title>Example elements</title> - * <listitem>Volume</listitem> - * <listitem>Audioconvert in certain modes (signed/unsigned - * conversion)</listitem> - * <listitem>videoconvert in certain modes (endianness - * swapping)</listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist> - * <title>Modifications only to the caps/metadata of a buffer</title> - * <listitem><para> - * The element does not require writable data, but non-writable buffers - * should be subbuffered so that the meta-information can be replaced. - * </para></listitem> - * <listitem><para> - * Elements wishing to operate in this mode should replace the - * prepare_output_buffer method to create subbuffers of the input buffer - * and set always_in_place to %TRUE - * </para></listitem> - * </itemizedlist> - * <itemizedlist> - * <title>Example elements</title> - * <listitem>Capsfilter when setting caps on outgoing buffers that have - * none.</listitem> - * <listitem>identity when it is going to re-timestamp buffers by - * datarate.</listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist><title>Normal mode</title> - * <listitem><para> - * always_in_place flag is not set, or there is no transform_ip function - * </para></listitem> - * <listitem><para> - * Element will receive an input buffer and output buffer to operate on. - * </para></listitem> - * <listitem><para> - * Output buffer is allocated by calling the prepare_output_buffer function. - * </para></listitem> - * </itemizedlist> - * <itemizedlist> - * <title>Example elements</title> - * <listitem>Videoscale, videoconvert, audioconvert when doing - * scaling/conversions</listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist><title>Special output buffer allocations</title> - * <listitem><para> - * Elements which need to do special allocation of their output buffers + * + * * Example elements + * + * * Level + * * Videoscale, audioconvert, videoconvert, audioresample in certain modes. + * + * ## Modifications in-place - input buffer and output buffer are the same thing. + * + * * The element must implement a transform_ip function. + * * Output buffer size must <= input buffer size + * * If the always_in_place flag is set, non-writable buffers will be copied + * and passed to the transform_ip function, otherwise a new buffer will be + * created and the transform function called. + * + * * Incoming writable buffers will be passed to the transform_ip function + * immediately. + * * only implementing transform_ip and not transform implies always_in_place = %TRUE + * + * * Example elements: + * * Volume + * * Audioconvert in certain modes (signed/unsigned conversion) + * * videoconvert in certain modes (endianness swapping) + * + * ## Modifications only to the caps/metadata of a buffer + * + * * The element does not require writable data, but non-writable buffers + * should be subbuffered so that the meta-information can be replaced. + * + * * Elements wishing to operate in this mode should replace the + * prepare_output_buffer method to create subbuffers of the input buffer + * and set always_in_place to %TRUE + * + * * Example elements + * * Capsfilter when setting caps on outgoing buffers that have + * none. + * * identity when it is going to re-timestamp buffers by + * datarate. + * + * ## Normal mode + * * always_in_place flag is not set, or there is no transform_ip function + * * Element will receive an input buffer and output buffer to operate on. + * * Output buffer is allocated by calling the prepare_output_buffer function. + * * Example elements: + * * Videoscale, videoconvert, audioconvert when doing + * scaling/conversions + * + * ## Special output buffer allocations + * * Elements which need to do special allocation of their output buffers * beyond allocating output buffers via the negotiated allocator or * buffer pool should implement the prepare_output_buffer method. - * </para></listitem> - * </itemizedlist> - * <itemizedlist> - * <title>Example elements</title> - * <listitem>efence</listitem> - * </itemizedlist> - * </listitem> - * </orderedlist> - * </para> - * </refsect2> - * <refsect2> - * <title>Sub-class settable flags on GstBaseTransform</title> - * <para> - * <itemizedlist> - * <listitem><para> - * <itemizedlist><title>passthrough</title> - * <listitem><para> - * Implies that in the current configuration, the sub-class is not - * interested in modifying the buffers. - * </para></listitem> - * <listitem><para> - * Elements which are always in passthrough mode whenever the same caps - * has been negotiated on both pads can set the class variable - * passthrough_on_same_caps to have this behaviour automatically. - * </para></listitem> - * </itemizedlist> - * </para></listitem> - * <listitem><para> - * <itemizedlist><title>always_in_place</title> - * <listitem><para> - * Determines whether a non-writable buffer will be copied before passing - * to the transform_ip function. - * </para></listitem> - * <listitem><para> - * Implied %TRUE if no transform function is implemented. - * </para></listitem> - * <listitem><para> - * Implied %FALSE if ONLY transform function is implemented. - * </para></listitem> - * </itemizedlist> - * </para></listitem> - * </itemizedlist> - * </para> - * </refsect2> + * + * * Example elements: + * * efence + * + * # Sub-class settable flags on GstBaseTransform + * + * * passthrough + * + * * Implies that in the current configuration, the sub-class is not interested in modifying the buffers. + * * Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically. + * + * * always_in_place + * * Determines whether a non-writable buffer will be copied before passing + * to the transform_ip function. + * + * * Implied %TRUE if no transform function is implemented. + * * Implied %FALSE if ONLY transform function is implemented. */ #ifdef HAVE_CONFIG_H @@ -679,7 +608,7 @@ gst_base_transform_transform_size (GstBaseTransform * trans, /* get the caps that can be handled by @pad. We perform: * * - take the caps of peer of otherpad, - * - filter against the padtemplate of otherpad, + * - filter against the padtemplate of otherpad, * - calculate all transforms of remaining caps * - filter against template of @pad * @@ -2478,7 +2407,7 @@ gst_base_transform_activate (GstBaseTransform * trans, gboolean active) GST_PAD_STREAM_UNLOCK (trans->sinkpad); priv->have_same_caps = FALSE; - /* We can only reset the passthrough mode if the instance told us to + /* We can only reset the passthrough mode if the instance told us to handle it in configure_caps */ if (bclass->passthrough_on_same_caps) { gst_base_transform_set_passthrough (trans, FALSE); @@ -2621,10 +2550,9 @@ gst_base_transform_is_passthrough (GstBaseTransform * trans) * * Determines whether a non-writable buffer will be copied before passing * to the transform_ip function. - * <itemizedlist> - * <listitem>Always %TRUE if no transform function is implemented.</listitem> - * <listitem>Always %FALSE if ONLY transform function is implemented.</listitem> - * </itemizedlist> + * + * * Always %TRUE if no transform function is implemented. + * * Always %FALSE if ONLY transform function is implemented. * * MT safe. */ diff --git a/libs/gst/base/gstbasetransform.h b/libs/gst/base/gstbasetransform.h index 2fe25ece6..ee1bd7b71 100644 --- a/libs/gst/base/gstbasetransform.h +++ b/libs/gst/base/gstbasetransform.h @@ -208,7 +208,7 @@ struct _GstBaseTransform { * do 1-to-1 transformations on input to output buffers can either * return GST_BASE_TRANSFORM_FLOW_DROPPED or simply not generate * an output buffer until they are ready to do so. (Since 1.6) - * + * * Subclasses can override any of the available virtual methods or not, as * needed. At minimum either @transform or @transform_ip need to be overridden. * If the element can overwrite the input data with the results (data is of the diff --git a/libs/gst/base/gstbitreader.c b/libs/gst/base/gstbitreader.c index 387937241..9df36d145 100644 --- a/libs/gst/base/gstbitreader.c +++ b/libs/gst/base/gstbitreader.c @@ -29,6 +29,7 @@ /** * SECTION:gstbitreader + * @title: GstBitReader * @short_description: Reads any number of bits from a memory buffer * * #GstBitReader provides a bit reader that can read any number of bits diff --git a/libs/gst/base/gstbytereader.c b/libs/gst/base/gstbytereader.c index 8a7e35da4..baa152fd1 100644 --- a/libs/gst/base/gstbytereader.c +++ b/libs/gst/base/gstbytereader.c @@ -30,6 +30,7 @@ /** * SECTION:gstbytereader + * @title: GstByteReader * @short_description: Reads different integer, string and floating point * types from a memory buffer * @@ -769,7 +770,6 @@ GST_BYTE_READER_PEEK_GET(64,gdouble,float64_be) * position if at least @size bytes are left and * updates the current position. * - * * Returns: %TRUE if successful, %FALSE otherwise. */ gboolean @@ -790,7 +790,6 @@ gst_byte_reader_get_data (GstByteReader * reader, guint size, * position if at least @size bytes are left and * keeps the current position. * - * * Returns: %TRUE if successful, %FALSE otherwise. */ gboolean @@ -916,7 +915,7 @@ _masked_scan_uint32_peek (const GstByteReader * reader, * Returns: offset of the first match, or -1 if no match was found. * * Example: - * <programlisting> + * |[ * // Assume the reader contains 0x00 0x01 0x02 ... 0xfe 0xff * * gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x00010203, 0, 256); @@ -933,7 +932,7 @@ _masked_scan_uint32_peek (const GstByteReader * reader, * // -> returns 2 * gst_byte_reader_masked_scan_uint32 (reader, 0xffff0000, 0x02030000, 0, 4); * // -> returns -1 - * </programlisting> + * ]| */ guint gst_byte_reader_masked_scan_uint32 (const GstByteReader * reader, guint32 mask, diff --git a/libs/gst/base/gstbytewriter.c b/libs/gst/base/gstbytewriter.c index 945ac58dd..72364fca2 100644 --- a/libs/gst/base/gstbytewriter.c +++ b/libs/gst/base/gstbytewriter.c @@ -27,6 +27,7 @@ /** * SECTION:gstbytewriter + * @title: GstByteWriter * @short_description: Writes different integer, string and floating point * types to a memory buffer and allows reading * diff --git a/libs/gst/base/gstcollectpads.c b/libs/gst/base/gstcollectpads.c index a19edf340..16a239b5d 100644 --- a/libs/gst/base/gstcollectpads.c +++ b/libs/gst/base/gstcollectpads.c @@ -22,55 +22,47 @@ */ /** * SECTION:gstcollectpads + * @title: GstCollectPads * @short_description: manages a set of pads that operate in collect mode * @see_also: * * Manages a set of pads that operate in collect mode. This means that control * is given to the manager of this object when all pads have data. - * <itemizedlist> - * <listitem><para> - * Collectpads are created with gst_collect_pads_new(). A callback should then + * + * * Collectpads are created with gst_collect_pads_new(). A callback should then * be installed with gst_collect_pads_set_function (). - * </para></listitem> - * <listitem><para> - * Pads are added to the collection with gst_collect_pads_add_pad()/ + * + * * Pads are added to the collection with gst_collect_pads_add_pad()/ * gst_collect_pads_remove_pad(). The pad * has to be a sinkpad. The chain and event functions of the pad are * overridden. The element_private of the pad is used to store * private information for the collectpads. - * </para></listitem> - * <listitem><para> - * For each pad, data is queued in the _chain function or by + * + * * For each pad, data is queued in the _chain function or by * performing a pull_range. - * </para></listitem> - * <listitem><para> - * When data is queued on all pads in waiting mode, the callback function is called. - * </para></listitem> - * <listitem><para> - * Data can be dequeued from the pad with the gst_collect_pads_pop() method. + * + * * When data is queued on all pads in waiting mode, the callback function is called. + * + * * Data can be dequeued from the pad with the gst_collect_pads_pop() method. * One can peek at the data with the gst_collect_pads_peek() function. * These functions will return %NULL if the pad received an EOS event. When all * pads return %NULL from a gst_collect_pads_peek(), the element can emit an EOS * event itself. - * </para></listitem> - * <listitem><para> - * Data can also be dequeued in byte units using the gst_collect_pads_available(), + * + * * Data can also be dequeued in byte units using the gst_collect_pads_available(), * gst_collect_pads_read_buffer() and gst_collect_pads_flush() calls. - * </para></listitem> - * <listitem><para> - * Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in + * + * * Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in * their state change functions to start and stop the processing of the collectpads. * The gst_collect_pads_stop() call should be called before calling the parent * element state change function in the PAUSED_TO_READY state change to ensure * no pad is blocked and the element can finish streaming. - * </para></listitem> - * <listitem><para> - * gst_collect_pads_set_waiting() sets a pad to waiting or non-waiting mode. + * + * * gst_collect_pads_set_waiting() sets a pad to waiting or non-waiting mode. * CollectPads element is not waiting for data to be collected on non-waiting pads. * Thus these pads may but need not have data when the callback is called. * All pads are in waiting mode by default. - * </para></listitem> - * </itemizedlist> + * */ #ifdef HAVE_CONFIG_H @@ -2137,7 +2129,7 @@ pad_removed: * and if so we call the collected function. When this is done we check if * data has been unqueued. If data is still queued we wait holding the stream * lock to make sure no EOS event can happen while we are ready to be - * collected + * collected */ static GstFlowReturn gst_collect_pads_chain (GstPad * pad, GstObject * parent, GstBuffer * buffer) diff --git a/libs/gst/base/gstdataqueue.c b/libs/gst/base/gstdataqueue.c index 2f9c16a3a..5c1c574e1 100644 --- a/libs/gst/base/gstdataqueue.c +++ b/libs/gst/base/gstdataqueue.c @@ -21,6 +21,7 @@ /** * SECTION:gstdataqueue + * @title: GstDataQueue * @short_description: Threadsafe queueing object * * #GstDataQueue is an object that handles threadsafe queueing of objects. It @@ -386,7 +387,7 @@ gst_data_queue_is_full (GstDataQueue * queue) * Sets the queue to flushing state if @flushing is %TRUE. If set to flushing * state, any incoming data on the @queue will be discarded. Any call currently * blocking on #gst_data_queue_push or #gst_data_queue_pop will return straight - * away with a return value of %FALSE. While the @queue is in flushing state, + * away with a return value of %FALSE. While the @queue is in flushing state, * all calls to those two functions will return %FALSE. * * MT Safe. diff --git a/libs/gst/base/gstdataqueue.h b/libs/gst/base/gstdataqueue.h index f1fd9be87..301e17b15 100644 --- a/libs/gst/base/gstdataqueue.h +++ b/libs/gst/base/gstdataqueue.h @@ -93,7 +93,7 @@ struct _GstDataQueueSize * @bytes: The amount of bytes currently in the queue. * @time: The accumulated duration of the items currently in the queue. * @checkdata: The #gpointer registered when the #GstDataQueue was created. - * + * * The prototype of the function used to inform the queue that it should be * considered as full. * diff --git a/libs/gst/base/gstflowcombiner.c b/libs/gst/base/gstflowcombiner.c index 377198f69..9aba81dea 100644 --- a/libs/gst/base/gstflowcombiner.c +++ b/libs/gst/base/gstflowcombiner.c @@ -23,6 +23,7 @@ /** * SECTION:gstflowcombiner + * @title: GstFlowCombiner * @short_description: Utility to combine multiple flow returns into one * * Utility struct to help handling #GstFlowReturn combination. Useful for diff --git a/libs/gst/base/gstindex.c b/libs/gst/base/gstindex.c index c75c2c7c5..1df5bd2c6 100644 --- a/libs/gst/base/gstindex.c +++ b/libs/gst/base/gstindex.c @@ -20,8 +20,9 @@ * Boston, MA 02110-1301, USA. */ -/* +/** * SECTION:gstindex + * @title: GstIndexEntry * @short_description: Generate indexes on objects * @see_also: #GstIndexFactory * @@ -687,11 +688,9 @@ gst_index_gtype_resolver (GstIndex * index, GstObject * writer, * to a string. That string will be used to register or look up an id * in the index. * - * <note> - * The caller must not hold @writer's GST_OBJECT_LOCK(), as the default - * resolver may call functions that take the object lock as well, and - * the lock is not recursive. - * </note> + * > The caller must not hold @writer's GST_OBJECT_LOCK(), as the default + * > resolver may call functions that take the object lock as well, and + * > the lock is not recursive. * * Returns: %TRUE if the writer would be mapped to an id. */ diff --git a/libs/gst/base/gstpushsrc.c b/libs/gst/base/gstpushsrc.c index 7af814753..db0a6d332 100644 --- a/libs/gst/base/gstpushsrc.c +++ b/libs/gst/base/gstpushsrc.c @@ -22,6 +22,7 @@ /** * SECTION:gstpushsrc + * @title: GstPushSrc * @short_description: Base class for push based source elements * @see_also: #GstBaseSrc * diff --git a/libs/gst/base/gstqueuearray.c b/libs/gst/base/gstqueuearray.c index 3a6444611..3084c3ca8 100644 --- a/libs/gst/base/gstqueuearray.c +++ b/libs/gst/base/gstqueuearray.c @@ -22,6 +22,7 @@ /** * SECTION:gstqueuearray + * @title: GstQueueArray * @short_description: Array based queue object * * #GstQueueArray is an object that provides standard queue functionality diff --git a/libs/gst/base/gsttypefindhelper.c b/libs/gst/base/gsttypefindhelper.c index 8828534ab..61a475edb 100644 --- a/libs/gst/base/gsttypefindhelper.c +++ b/libs/gst/base/gsttypefindhelper.c @@ -23,7 +23,8 @@ /** * SECTION:gsttypefindhelper - * @short_description: Utility functions for typefinding + * @title: GstTypeFindHelper + * @short_description: Utility functions for typefinding * * Utility functions for elements doing typefinding: * gst_type_find_helper() does typefinding in pull mode, while @@ -118,7 +119,7 @@ helper_find_peek (gpointer data, gint64 offset, guint size) buf_size = bmp->map.size; /* buffers are kept sorted by end offset (highest first) in the list, so - * at this point we save the current position and stop searching if + * at this point we save the current position and stop searching if * we're after the searched end offset */ if (buf_offset <= offset) { if ((offset + size) < (buf_offset + buf_size)) { diff --git a/libs/gst/check/gstbufferstraw.c b/libs/gst/check/gstbufferstraw.c index 2a440906f..93a2c3763 100644 --- a/libs/gst/check/gstbufferstraw.c +++ b/libs/gst/check/gstbufferstraw.c @@ -22,6 +22,7 @@ /** * SECTION:gstcheckbufferstraw + * @title: GstBufferStraw * @short_description: Buffer interception code for GStreamer unit tests * * These macros and functions are for internal use of the unit tests found diff --git a/libs/gst/check/gstcheck.c b/libs/gst/check/gstcheck.c index 22c78e120..e10a19e66 100644 --- a/libs/gst/check/gstcheck.c +++ b/libs/gst/check/gstcheck.c @@ -22,6 +22,7 @@ */ /** * SECTION:gstcheck + * @title: GstCheck * @short_description: Common code for GStreamer unit tests * * These macros and functions are for internal use of the unit tests found @@ -64,7 +65,8 @@ gboolean _gst_check_list_tests = FALSE; static GQueue _gst_check_log_filters = G_QUEUE_INIT; static GMutex _gst_check_log_filters_mutex; -struct _GstCheckLogFilter { +struct _GstCheckLogFilter +{ gchar *log_domain; GLogLevelFlags log_level; GRegex *regex; @@ -199,8 +201,8 @@ gst_check_clear_log_filter (void) typedef struct { - const gchar * domain; - const gchar * message; + const gchar *domain; + const gchar *message; GLogLevelFlags level; gboolean discard; } LogFilterApplyData; @@ -243,7 +245,7 @@ gst_check_filter_log_filter (const gchar * log_domain, static gboolean gst_check_log_fatal_func (const gchar * log_domain, GLogLevelFlags log_level, - const gchar *message, gpointer user_data) + const gchar * message, gpointer user_data) { if (gst_check_filter_log_filter (log_domain, log_level, message)) return FALSE; diff --git a/libs/gst/check/gstconsistencychecker.c b/libs/gst/check/gstconsistencychecker.c index e152c6a08..cf1dbf70a 100644 --- a/libs/gst/check/gstconsistencychecker.c +++ b/libs/gst/check/gstconsistencychecker.c @@ -23,6 +23,7 @@ /** * SECTION:gstcheckconsistencychecker + * @title: GstStreamConsistencyChecker * @short_description: Data flow consistency checker for GStreamer unit tests. * * These macros and functions are for internal use of the unit tests found diff --git a/libs/gst/check/gstharness.c b/libs/gst/check/gstharness.c index 1226b7e4c..f91778699 100644 --- a/libs/gst/check/gstharness.c +++ b/libs/gst/check/gstharness.c @@ -20,6 +20,7 @@ /** * SECTION:gstharness + * @title: GstHarness * @short_description: A test-harness for writing GStreamer unit tests * @see_also: #GstTestClock,\ * @@ -30,7 +31,7 @@ * The basic structure of #GstHarness is two "floating" #GstPads that connect * to the harnessed #GstElement src and sink #GstPads like so: * - * <programlisting> + * |[ * __________________________ * _____ | _____ _____ | _____ * | | | | | | | | | | @@ -38,7 +39,7 @@ * |_____| | |_____| |_____| | |_____| * |__________________________| * - * </programlisting> + * ]| * * With this, you can now simulate any environment the #GstElement might find * itself in. By specifying the #GstCaps of the harness #GstPads, using @@ -54,11 +55,11 @@ * then pull them out to examine them with gst_harness_pull() and * gst_harness_pull_event(). * - * <example> - * <title>A simple buffer-in buffer-out example</title> - * <programlisting language="c"> - * #include <gst/gst.h> - * #include <gst/check/gstharness.h> + * ## A simple buffer-in buffer-out example + * + * |[<!-- language="C" --> + * #include <gst/gst.h> + * #include <gst/check/gstharness.h> * GstHarness *h; * GstBuffer *in_buf; * GstBuffer *out_buf; @@ -85,8 +86,7 @@ * gst_buffer_unref (out_buf); * gst_harness_teardown (h); * - * </programlisting> - * </example> + * ]| * * Another main feature of the #GstHarness is its integration with the * #GstTestClock. Operating the #GstTestClock can be very challenging, but @@ -104,20 +104,16 @@ * src-element (videotestsrc) and an encoder (vp8enc) to feed the decoder data * with different configurations, by simply doing: * - * <example> - * <programlisting language="c"> + * |[<!-- language="C" --> * GstHarness * h = gst_harness_new (h, "vp8dec"); * gst_harness_add_src_parse (h, "videotestsrc is-live=1 ! vp8enc", TRUE); - * </programlisting> - * </example> + * ]| * * and then feeding it data with: * - * <example> - * <programlisting language="c"> + * |[<!-- language="C" --> * gst_harness_push_from_src (h); - * </programlisting> - * </example> + * ]| * */ #ifdef HAVE_CONFIG_H diff --git a/libs/gst/check/gsttestclock.c b/libs/gst/check/gsttestclock.c index 513667fd3..ab90e49d4 100644 --- a/libs/gst/check/gsttestclock.c +++ b/libs/gst/check/gsttestclock.c @@ -23,6 +23,7 @@ /** * SECTION:gsttestclock + * @title: GstTestClock * @short_description: Controllable, deterministic clock for GStreamer unit tests * @see_also: #GstSystemClock, #GstClock * @@ -34,11 +35,11 @@ * precisely advance the time in a deterministic manner, independent of the * system time or any other external factors. * - * <example> - * <title>Advancing the time of a #GstTestClock</title> - * <programlisting language="c"> - * #include <gst/gst.h> - * #include <gst/check/gsttestclock.h> + * ## Advancing the time of a #GstTestClock + * + * |[<!-- language="C" --> + * #include <gst/gst.h> + * #include <gst/check/gsttestclock.h> * * GstClock *clock; * GstTestClock *test_clock; @@ -53,8 +54,7 @@ * gst_test_clock_set_time (test_clock, 42 * GST_SECOND); * GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock))); * ... - * </programlisting> - * </example> + * ]| * * #GstClock allows for setting up single shot or periodic clock notifications * as well as waiting for these notifications synchronously (using @@ -93,12 +93,12 @@ * second buffer will arrive a little late (7ms) due to simulated jitter in the * clock notification. * - * <example> - * <title>Demonstration of how to work with clock notifications and #GstTestClock</title> - * <programlisting language="c"> - * #include <gst/gst.h> - * #include <gst/check/gstcheck.h> - * #include <gst/check/gsttestclock.h> + * ## Demonstration of how to work with clock notifications and #GstTestClock + * + * |[<!-- language="C" --> + * #include <gst/gst.h> + * #include <gst/check/gstcheck.h> + * #include <gst/check/gsttestclock.h> * * GstClockTime latency; * GstElement *element; @@ -166,8 +166,7 @@ * GST_INFO ("Check that element does not wait for any clock notification\n"); * g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL)); * ... - * </programlisting> - * </example> + * ]| * * Since #GstTestClock is only supposed to be used in unit tests it calls * g_assert(), g_assert_cmpint() or g_assert_cmpuint() to validate all function diff --git a/libs/gst/controller/gstargbcontrolbinding.c b/libs/gst/controller/gstargbcontrolbinding.c index 772d37057..6fe79e310 100644 --- a/libs/gst/controller/gstargbcontrolbinding.c +++ b/libs/gst/controller/gstargbcontrolbinding.c @@ -22,6 +22,7 @@ */ /** * SECTION:gstargbcontrolbinding + * @title: GstARGBControlBinding * @short_description: attachment for control sources to argb properties * * A value mapping object that attaches multiple control sources to a guint diff --git a/libs/gst/controller/gstdirectcontrolbinding.c b/libs/gst/controller/gstdirectcontrolbinding.c index d6dcf3ea3..9e5955d1b 100644 --- a/libs/gst/controller/gstdirectcontrolbinding.c +++ b/libs/gst/controller/gstdirectcontrolbinding.c @@ -21,6 +21,7 @@ */ /** * SECTION:gstdirectcontrolbinding + * @title: GstDirectControlBinding * @short_description: direct attachment for control sources * * A value mapping object that attaches control sources to gobject properties. It diff --git a/libs/gst/controller/gstinterpolationcontrolsource.c b/libs/gst/controller/gstinterpolationcontrolsource.c index 39bb9e33c..21f5feab5 100644 --- a/libs/gst/controller/gstinterpolationcontrolsource.c +++ b/libs/gst/controller/gstinterpolationcontrolsource.c @@ -23,6 +23,7 @@ /** * SECTION:gstinterpolationcontrolsource + * @title: GstInterpolationControlSource * @short_description: interpolation control source * * #GstInterpolationControlSource is a #GstControlSource, that interpolates values between user-given diff --git a/libs/gst/controller/gstlfocontrolsource.c b/libs/gst/controller/gstlfocontrolsource.c index df7a439fc..403adf541 100644 --- a/libs/gst/controller/gstlfocontrolsource.c +++ b/libs/gst/controller/gstlfocontrolsource.c @@ -23,6 +23,7 @@ /** * SECTION:gstlfocontrolsource + * @title: GstLFOControlSource * @short_description: LFO control source * * #GstLFOControlSource is a #GstControlSource, that provides several periodic diff --git a/libs/gst/controller/gstproxycontrolbinding.c b/libs/gst/controller/gstproxycontrolbinding.c index ce5cad5d8..17a08a7d5 100644 --- a/libs/gst/controller/gstproxycontrolbinding.c +++ b/libs/gst/controller/gstproxycontrolbinding.c @@ -19,6 +19,7 @@ */ /** * SECTION:gstproxycontrolbinding + * @title: GstProxyControlBinding * @short_description: attachment for forwarding control sources * @see_also: #GstControlBinding * diff --git a/libs/gst/controller/gsttimedvaluecontrolsource.c b/libs/gst/controller/gsttimedvaluecontrolsource.c index 04101c25a..47f5ead76 100644 --- a/libs/gst/controller/gsttimedvaluecontrolsource.c +++ b/libs/gst/controller/gsttimedvaluecontrolsource.c @@ -24,6 +24,7 @@ /** * SECTION:gsttimedvaluecontrolsource + * @title: GstTimedValueControlSource * @short_description: timed value control source base class * * Base class for #GstControlSource that use time-stamped values. diff --git a/libs/gst/controller/gsttriggercontrolsource.c b/libs/gst/controller/gsttriggercontrolsource.c index c40525fbb..8fd0c8302 100644 --- a/libs/gst/controller/gsttriggercontrolsource.c +++ b/libs/gst/controller/gsttriggercontrolsource.c @@ -24,6 +24,7 @@ /** * SECTION:gsttriggercontrolsource + * @title: GstTriggerControlSource * @short_description: trigger control source * * #GstTriggerControlSource is a #GstControlSource, that returns values from user-given diff --git a/libs/gst/net/gstnetaddressmeta.c b/libs/gst/net/gstnetaddressmeta.c index ae10071ea..de98a1c2f 100644 --- a/libs/gst/net/gstnetaddressmeta.c +++ b/libs/gst/net/gstnetaddressmeta.c @@ -19,6 +19,7 @@ /** * SECTION:gstnetaddressmeta + * @title: GstNetAddressMeta * @short_description: Network address metadata * * #GstNetAddressMeta can be used to store a network address (a #GSocketAddress) diff --git a/libs/gst/net/gstnetclientclock.c b/libs/gst/net/gstnetclientclock.c index cce8952f8..3049ed4a3 100644 --- a/libs/gst/net/gstnetclientclock.c +++ b/libs/gst/net/gstnetclientclock.c @@ -25,6 +25,7 @@ */ /** * SECTION:gstnetclientclock + * @title: GstNetClientClock * @short_description: Special clock that synchronizes to a remote time * provider. * @see_also: #GstClock, #GstNetTimeProvider, #GstPipeline @@ -1378,7 +1379,7 @@ gst_net_client_clock_get_internal_time (GstClock * clock) * @base_time: initial time of the clock * * Create a new #GstNetClientInternalClock that will report the time - * provided by the #GstNetTimeProvider on @remote_address and + * provided by the #GstNetTimeProvider on @remote_address and * @remote_port. * * Returns: a new #GstClock that receives a time from the remote diff --git a/libs/gst/net/gstnetcontrolmessagemeta.c b/libs/gst/net/gstnetcontrolmessagemeta.c index d5b0c533a..d6cc52548 100644 --- a/libs/gst/net/gstnetcontrolmessagemeta.c +++ b/libs/gst/net/gstnetcontrolmessagemeta.c @@ -19,6 +19,7 @@ /** * SECTION:gstnetcontrolmessagemeta + * @title: GstNetControlMessageMeta * @short_description: Network Control Message Meta * * #GstNetControlMessageMeta can be used to store control messages (ancillary diff --git a/libs/gst/net/gstnettimepacket.c b/libs/gst/net/gstnettimepacket.c index 754199532..e103e16e8 100644 --- a/libs/gst/net/gstnettimepacket.c +++ b/libs/gst/net/gstnettimepacket.c @@ -20,6 +20,7 @@ */ /** * SECTION:gstnettimepacket + * @title: GstNetTimePacket * @short_description: Helper structure to construct clock packets used * by network clocks. * @see_also: #GstClock, #GstNetClientClock, #GstNetTimeProvider diff --git a/libs/gst/net/gstnettimeprovider.c b/libs/gst/net/gstnettimeprovider.c index 0025936e0..fee3ec125 100644 --- a/libs/gst/net/gstnettimeprovider.c +++ b/libs/gst/net/gstnettimeprovider.c @@ -18,6 +18,7 @@ */ /** * SECTION:gstnettimeprovider + * @title: GstNetTimeProvider * @short_description: Special object that exposed the time of a clock * on the network. * @see_also: #GstClock, #GstNetClientClock, #GstPipeline diff --git a/libs/gst/net/gstptpclock.c b/libs/gst/net/gstptpclock.c index 1528da2e7..79951a3ab 100644 --- a/libs/gst/net/gstptpclock.c +++ b/libs/gst/net/gstptpclock.c @@ -19,6 +19,7 @@ */ /** * SECTION:gstptpclock + * @title: GstPtpClock * @short_description: Special clock that synchronizes to a remote time * provider via PTP (IEEE1588:2008). * @see_also: #GstClock, #GstNetClientClock, #GstPipeline @@ -40,7 +41,6 @@ * check this, you can use gst_clock_wait_for_sync(), the GstClock::synced * signal and gst_clock_is_synced(). * - * * To gather statistics about the PTP clock synchronization, * gst_ptp_statistics_callback_add() can be used. This gives the application * the possibility to collect all kinds of statistics from the clock @@ -1991,7 +1991,6 @@ gst_ptp_is_initialized (void) * If @clock_id is %GST_PTP_CLOCK_ID_NONE, a clock id is automatically * generated from the MAC address of the first network interface. * - * * This function is automatically called by gst_ptp_clock_new() with default * parameters if it wasn't called before. * @@ -2505,7 +2504,6 @@ gst_ptp_clock_get_internal_time (GstClock * clock) * If gst_ptp_init() was not called before, this will call gst_ptp_init() with * default parameters. * - * * This clock only returns valid timestamps after it received the first * times from the PTP master clock on the network. Once this happens the * GstPtpClock::internal-clock property will become non-NULL. You can diff --git a/plugins/elements/gstcapsfilter.c b/plugins/elements/gstcapsfilter.c index 30b6b99da..69b23f70c 100644 --- a/plugins/elements/gstcapsfilter.c +++ b/plugins/elements/gstcapsfilter.c @@ -21,19 +21,19 @@ */ /** * SECTION:element-capsfilter + * @title: capsfilter * * The element does not modify data as such, but can enforce limitations on the * data format. * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * gst-launch-1.0 videotestsrc ! capsfilter caps=video/x-raw,format=GRAY8 ! videoconvert ! autovideosink * ]| Limits acceptable video from videotestsrc to be grayscale. Equivalent to * |[ * gst-launch-1.0 videotestsrc ! video/x-raw,format=GRAY8 ! videoconvert ! autovideosink * ]| which is a short notation for the capsfilter element. - * </refsect2> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstconcat.c b/plugins/elements/gstconcat.c index 788cc9c78..4cc134d99 100644 --- a/plugins/elements/gstconcat.c +++ b/plugins/elements/gstconcat.c @@ -20,6 +20,7 @@ */ /** * SECTION:element-concat + * @title: concat * @see_also: #GstFunnel * * Concatenates streams together to one continous stream. @@ -37,12 +38,11 @@ * another downstream element like a streamsynchronizer adjusts the base * values on its own). The adjust-base property can be used for this purpose. * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * gst-launch-1.0 concat name=c ! xvimagesink videotestsrc num-buffers=100 ! c. videotestsrc num-buffers=100 pattern=ball ! c. * ]| Plays two video streams one after another. - * </refsect2> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstdataurisrc.c b/plugins/elements/gstdataurisrc.c index d63e43728..e35d012dd 100644 --- a/plugins/elements/gstdataurisrc.c +++ b/plugins/elements/gstdataurisrc.c @@ -20,15 +20,17 @@ /** * SECTION:element-dataurisrc + * @title: dataurisrc * - * dataurisrc handles data: URIs, see <ulink url="http://tools.ietf.org/html/rfc2397">RFC 2397</ulink> for more information. + * dataurisrc handles data: URIs, see [RFC 2397](http://tools.ietf.org/html/rfc2397) for more information. + * + * ## Example launch line * - * <refsect2> - * <title>Example launch line</title> * |[ * gst-launch-1.0 -v dataurisrc uri="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAfElEQVQ4je2MwQnAIAxFgziA4EnczIsO4MEROo/gzZWc4xdTbe1R6LGRR74heYS7iKElzfcMiRnt4hf8gk8EayB6luefue/HzlJfCA50XsNjYRxprZmenXNIKSGEsC+QUqK1hhgj521BzhnWWiilUGvdF5RS4L2HMQZCCJy8sHMm2TYdJAAAAABJRU5ErkJggg==" ! pngdec ! videoconvert ! imagefreeze ! videoconvert ! autovideosink - * ]| This pipeline displays a small 16x16 PNG image from the data URI. - * </refsect2> + * ]| + * + * This pipeline displays a small 16x16 PNG image from the data URI. */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstdownloadbuffer.c b/plugins/elements/gstdownloadbuffer.c index 9551d9bea..335dc5436 100644 --- a/plugins/elements/gstdownloadbuffer.c +++ b/plugins/elements/gstdownloadbuffer.c @@ -21,6 +21,7 @@ /** * SECTION:element-downloadbuffer + * @title: downloadbuffer * * The downloadbuffer element provides on-disk buffering and caching of, typically, * a network file. temp-template should be set to a value such as @@ -42,15 +43,12 @@ * When the downloadbuffer has completely downloaded the media, it will * post an application message named <classname>"GstCacheDownloadComplete"</classname> * with the following information: - * <itemizedlist> - * <listitem> - * <para> + * + * * * G_TYPE_STRING * <classname>"location"</classname>: * the location of the completely downloaded file. - * </para> - * </listitem> - * </itemizedlist> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstfakesink.c b/plugins/elements/gstfakesink.c index 0c7e84a55..b71f20f6f 100644 --- a/plugins/elements/gstfakesink.c +++ b/plugins/elements/gstfakesink.c @@ -21,16 +21,16 @@ */ /** * SECTION:element-fakesink + * @title: fakesink * @see_also: #GstFakeSrc * * Dummy sink that swallows everything. - * - * <refsect2> - * <title>Example launch line</title> + * + * ## Example launch line * |[ * gst-launch-1.0 audiotestsrc num-buffers=1000 ! fakesink sync=false * ]| Render 1000 audio buffers (of default size) as fast as possible. - * </refsect2> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstfakesrc.c b/plugins/elements/gstfakesrc.c index 9d4041b6e..14f3226b0 100644 --- a/plugins/elements/gstfakesrc.c +++ b/plugins/elements/gstfakesrc.c @@ -21,6 +21,7 @@ */ /** * SECTION:element-fakesrc + * @title: fakesrc * @see_also: #GstFakeSink * * The fakesrc element is a multipurpose element that can generate @@ -29,13 +30,12 @@ * It is mostly used as a testing element, one trivial example for testing * basic <application>GStreamer</application> core functionality is: * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * gst-launch-1.0 -v fakesrc num-buffers=5 ! fakesink * ]| This pipeline will push 5 empty buffers to the fakesink element and then * sends an EOS. - * </refsect2> + * */ /* FIXME: this ignores basesrc::blocksize property, which could be used as an diff --git a/plugins/elements/gstfakesrc.h b/plugins/elements/gstfakesrc.h index 5190ee893..0d54d82cb 100644 --- a/plugins/elements/gstfakesrc.h +++ b/plugins/elements/gstfakesrc.h @@ -81,7 +81,7 @@ typedef enum { /** * GstFakeSrcFillType: - * @FAKE_SRC_FILLTYPE_NOTHING: do not fill buffers + * @FAKE_SRC_FILLTYPE_NOTHING: do not fill buffers * @FAKE_SRC_FILLTYPE_ZERO: fill buffers with 0 * @FAKE_SRC_FILLTYPE_RANDOM: fill buffers with random bytes * @FAKE_SRC_FILLTYPE_PATTERN: fill buffers with a pattern diff --git a/plugins/elements/gstfdsink.c b/plugins/elements/gstfdsink.c index f4eb10073..ef2480087 100644 --- a/plugins/elements/gstfdsink.c +++ b/plugins/elements/gstfdsink.c @@ -22,6 +22,7 @@ /** * SECTION:element-fdsink + * @title: fdsink * @see_also: #GstFdSrc * * Write data to a unix file descriptor. diff --git a/plugins/elements/gstfdsrc.c b/plugins/elements/gstfdsrc.c index 469a61423..963bcbd43 100644 --- a/plugins/elements/gstfdsrc.c +++ b/plugins/elements/gstfdsrc.c @@ -22,6 +22,7 @@ */ /** * SECTION:element-fdsrc + * @title: fdsrc * @see_also: #GstFdSink * * Read data from a unix file descriptor. @@ -34,23 +35,16 @@ * if no data was received in the given timeout. * * The message's structure contains one field: - * <itemizedlist> - * <listitem> - * <para> - * #guint64 - * <classname>"timeout"</classname>: the timeout in microseconds that + * + * * #guint64 `timeout`: the timeout in microseconds that * expired when waiting for data. - * </para> - * </listitem> - * </itemizedlist> * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * echo "Hello GStreamer" | gst-launch-1.0 -v fdsrc ! fakesink dump=true * ]| A simple pipeline to read from the standard input and dump the data * with a fakesink as hex ascii block. - * </refsect2> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstfilesink.c b/plugins/elements/gstfilesink.c index 9f0243bd7..4ce527e30 100644 --- a/plugins/elements/gstfilesink.c +++ b/plugins/elements/gstfilesink.c @@ -22,16 +22,16 @@ */ /** * SECTION:element-filesink + * @title: filesink * @see_also: #GstFileSrc * * Write incoming data to a file in the local file system. * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * gst-launch-1.0 v4l2src num-buffers=1 ! jpegenc ! filesink location=capture1.jpeg * ]| Capture one frame from a v4l2 camera and save as jpeg image. - * </refsect2> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstfilesrc.c b/plugins/elements/gstfilesrc.c index 15dd5a96b..530735196 100644 --- a/plugins/elements/gstfilesrc.c +++ b/plugins/elements/gstfilesrc.c @@ -21,16 +21,16 @@ */ /** * SECTION:element-filesrc + * @title: filesrc * @see_also: #GstFileSrc * * Read data from a file in the local file system. * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * gst-launch-1.0 filesrc location=song.ogg ! decodebin ! audioconvert ! audioresample ! autoaudiosink * ]| Play song.ogg audio file which must be in the current working directory. - * </refsect2> + * */ #ifdef HAVE_CONFIG_H @@ -648,7 +648,7 @@ gst_file_src_uri_set_uri (GstURIHandler * handler, const gchar * uri, #ifdef G_OS_WIN32 /* Unfortunately, g_filename_from_uri() doesn't handle some UNC paths * correctly on windows, it leaves them with an extra backslash - * at the start if they're of the mozilla-style file://///host/path/file + * at the start if they're of the mozilla-style file://///host/path/file * form. Correct this. */ if (location[0] == '\\' && location[1] == '\\' && location[2] == '\\') diff --git a/plugins/elements/gstfunnel.c b/plugins/elements/gstfunnel.c index 3597d58f1..a9293383a 100644 --- a/plugins/elements/gstfunnel.c +++ b/plugins/elements/gstfunnel.c @@ -24,6 +24,7 @@ /** * SECTION:element-funnel + * @title: funnel * * Takes packets from various input sinks into one output source. * diff --git a/plugins/elements/gstidentity.c b/plugins/elements/gstidentity.c index 77cd2d8e1..119fb5886 100644 --- a/plugins/elements/gstidentity.c +++ b/plugins/elements/gstidentity.c @@ -22,6 +22,7 @@ */ /** * SECTION:element-identity + * @title: identity * * Dummy element that passes incoming data through unmodified. It has some * useful diagnostic functions, such as offset and timestamp checking. diff --git a/plugins/elements/gstinputselector.c b/plugins/elements/gstinputselector.c index 5d1d65ecd..d842c2979 100644 --- a/plugins/elements/gstinputselector.c +++ b/plugins/elements/gstinputselector.c @@ -25,6 +25,7 @@ /** * SECTION:element-input-selector + * @title: input-selector * @see_also: #GstOutputSelector * * Direct one out of N input streams to the output pad. @@ -32,21 +33,12 @@ * The input pads are from a GstPad subclass and have additional * properties, which users may find useful, namely: * - * <itemizedlist> - * <listitem> - * "running-time": Running time of stream on pad (#gint64) - * </listitem> - * <listitem> - * "tags": The currently active tags on the pad (#GstTagList, boxed type) - * </listitem> - * <listitem> - * "active": If the pad is currently active (#gboolean) - * </listitem> - * <listitem> - * "always-ok" : Make an inactive pads return #GST_FLOW_OK instead of + * * "running-time": Running time of stream on pad (#gint64) + * * "tags": The currently active tags on the pad (#GstTagList, boxed type) + * * "active": If the pad is currently active (#gboolean) + * * "always-ok" : Make an inactive pads return #GST_FLOW_OK instead of * #GST_FLOW_NOT_LINKED - * </listitem> - * </itemizedlist> + * */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gstmultiqueue.c b/plugins/elements/gstmultiqueue.c index fed846d01..a9dbdbdfd 100644 --- a/plugins/elements/gstmultiqueue.c +++ b/plugins/elements/gstmultiqueue.c @@ -24,94 +24,70 @@ /** * SECTION:element-multiqueue + * @title: multiqueue * @see_also: #GstQueue * - * <refsect2> - * <para> * Multiqueue is similar to a normal #GstQueue with the following additional * features: - * <orderedlist> - * <listitem> - * <itemizedlist><title>Multiple streamhandling</title> - * <listitem><para> - * The element handles queueing data on more than one stream at once. To - * achieve such a feature it has request sink pads (sink%u) and - * 'sometimes' src pads (src%u). - * </para><para> - * When requesting a given sinkpad with gst_element_request_pad(), - * the associated srcpad for that stream will be created. - * Example: requesting sink1 will generate src1. - * </para></listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist><title>Non-starvation on multiple streams</title> - * <listitem><para> - * If more than one stream is used with the element, the streams' queues - * will be dynamically grown (up to a limit), in order to ensure that no - * stream is risking data starvation. This guarantees that at any given - * time there are at least N bytes queued and available for each individual - * stream. - * </para><para> - * If an EOS event comes through a srcpad, the associated queue will be - * considered as 'not-empty' in the queue-size-growing algorithm. - * </para></listitem> - * </itemizedlist> - * </listitem> - * <listitem> - * <itemizedlist><title>Non-linked srcpads graceful handling</title> - * <listitem><para> - * In order to better support dynamic switching between streams, the multiqueue - * (unlike the current GStreamer queue) continues to push buffers on non-linked - * pads rather than shutting down. - * </para><para> - * In addition, to prevent a non-linked stream from very quickly consuming all - * available buffers and thus 'racing ahead' of the other streams, the element - * must ensure that buffers and inlined events for a non-linked stream are pushed - * in the same order as they were received, relative to the other streams - * controlled by the element. This means that a buffer cannot be pushed to a - * non-linked pad any sooner than buffers in any other stream which were received - * before it. - * </para></listitem> - * </itemizedlist> - * </listitem> - * </orderedlist> - * </para> - * <para> - * Data is queued until one of the limits specified by the - * #GstMultiQueue:max-size-buffers, #GstMultiQueue:max-size-bytes and/or - * #GstMultiQueue:max-size-time properties has been reached. Any attempt to push - * more buffers into the queue will block the pushing thread until more space - * becomes available. #GstMultiQueue:extra-size-buffers, - * </para> - * <para> - * #GstMultiQueue:extra-size-bytes and #GstMultiQueue:extra-size-time are - * currently unused. - * </para> - * <para> - * The default queue size limits are 5 buffers, 10MB of data, or - * two second worth of data, whichever is reached first. Note that the number - * of buffers will dynamically grow depending on the fill level of - * other queues. - * </para> - * <para> - * The #GstMultiQueue::underrun signal is emitted when all of the queues - * are empty. The #GstMultiQueue::overrun signal is emitted when one of the - * queues is filled. - * Both signals are emitted from the context of the streaming thread. - * </para> - * <para> - * When using #GstMultiQueue:sync-by-running-time the unlinked streams will - * be throttled by the highest running-time of linked streams. This allows - * further relinking of those unlinked streams without them being in the - * future (i.e. to achieve gapless playback). - * When dealing with streams which have got different consumption requirements - * downstream (ex: video decoders which will consume more buffer (in time) than - * audio decoders), it is recommended to group streams of the same type - * by using the pad "group-id" property. This will further throttle streams - * in time within that group. - * </para> - * </refsect2> + * + * 1) Multiple streamhandling + * + * * The element handles queueing data on more than one stream at once. To + * achieve such a feature it has request sink pads (sink%u) and + * 'sometimes' src pads (src%u). When requesting a given sinkpad with gst_element_request_pad(), + * the associated srcpad for that stream will be created. + * Example: requesting sink1 will generate src1. + * + * 2) Non-starvation on multiple stream + * + * * If more than one stream is used with the element, the streams' queues + * will be dynamically grown (up to a limit), in order to ensure that no + * stream is risking data starvation. This guarantees that at any given + * time there are at least N bytes queued and available for each individual + * stream. If an EOS event comes through a srcpad, the associated queue will be + * considered as 'not-empty' in the queue-size-growing algorithm. + * + * 3) Non-linked srcpads graceful handling + * + * * In order to better support dynamic switching between streams, the multiqueue + * (unlike the current GStreamer queue) continues to push buffers on non-linked + * pads rather than shutting down. In addition, to prevent a non-linked stream from very quickly consuming all + * available buffers and thus 'racing ahead' of the other streams, the element + * must ensure that buffers and inlined events for a non-linked stream are pushed + * in the same order as they were received, relative to the other streams + * controlled by the element. This means that a buffer cannot be pushed to a + * non-linked pad any sooner than buffers in any other stream which were received + * before it. + * + * Data is queued until one of the limits specified by the + * #GstMultiQueue:max-size-buffers, #GstMultiQueue:max-size-bytes and/or + * #GstMultiQueue:max-size-time properties has been reached. Any attempt to push + * more buffers into the queue will block the pushing thread until more space + * becomes available. #GstMultiQueue:extra-size-buffers, + * + * + * #GstMultiQueue:extra-size-bytes and #GstMultiQueue:extra-size-time are + * currently unused. + * + * The default queue size limits are 5 buffers, 10MB of data, or + * two second worth of data, whichever is reached first. Note that the number + * of buffers will dynamically grow depending on the fill level of + * other queues. + * + * The #GstMultiQueue::underrun signal is emitted when all of the queues + * are empty. The #GstMultiQueue::overrun signal is emitted when one of the + * queues is filled. + * Both signals are emitted from the context of the streaming thread. + * + * When using #GstMultiQueue:sync-by-running-time the unlinked streams will + * be throttled by the highest running-time of linked streams. This allows + * further relinking of those unlinked streams without them being in the + * future (i.e. to achieve gapless playback). + * When dealing with streams which have got different consumption requirements + * downstream (ex: video decoders which will consume more buffer (in time) than + * audio decoders), it is recommended to group streams of the same type + * by using the pad "group-id" property. This will further throttle streams + * in time within that group. */ #ifdef HAVE_CONFIG_H @@ -504,7 +480,7 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) * size) is higher than the boundary values which can be set through the * GObject properties. * - * This can be used as an indicator of pre-roll. + * This can be used as an indicator of pre-roll. */ gst_multi_queue_signals[SIGNAL_OVERRUN] = g_signal_new ("overrun", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST, @@ -551,8 +527,8 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * GstMultiQueue:use-buffering - * + * GstMultiQueue:use-buffering: + * * Enable the buffering option in multiqueue so that BUFFERING messages are * emitted based on low-/high-percent thresholds. */ @@ -562,8 +538,8 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) DEFAULT_USE_BUFFERING, G_PARAM_READWRITE | GST_PARAM_MUTABLE_PLAYING | G_PARAM_STATIC_STRINGS)); /** - * GstMultiQueue:low-percent - * + * GstMultiQueue:low-percent: + * * Low threshold percent for buffering to start. */ g_object_class_install_property (gobject_class, PROP_LOW_PERCENT, @@ -573,8 +549,8 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) 0, 100, DEFAULT_LOW_WATERMARK * 100, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * GstMultiQueue:high-percent - * + * GstMultiQueue:high-percent: + * * High threshold percent for buffering to finish. */ g_object_class_install_property (gobject_class, PROP_HIGH_PERCENT, @@ -584,7 +560,7 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) 0, 100, DEFAULT_HIGH_WATERMARK * 100, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * GstMultiQueue:low-watermark + * GstMultiQueue:low-watermark: * * Low threshold watermark for buffering to start. * @@ -596,7 +572,7 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) 0.0, 1.0, DEFAULT_LOW_WATERMARK, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * GstMultiQueue:high-watermark + * GstMultiQueue:high-watermark: * * High threshold watermark for buffering to finish. * @@ -609,8 +585,8 @@ gst_multi_queue_class_init (GstMultiQueueClass * klass) G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); /** - * GstMultiQueue:sync-by-running-time - * + * GstMultiQueue:sync-by-running-time: + * * If enabled multiqueue will synchronize deactivated or not-linked streams * to the activated and linked streams by taking the running time. * Otherwise multiqueue will synchronize the deactivated or not-linked @@ -1334,7 +1310,7 @@ beach: /* calculate the diff between running time on the sink and src of the queue. - * This is the total amount of time in the queue. + * This is the total amount of time in the queue. * WITH LOCK TAKEN */ static void update_time_level (GstMultiQueue * mq, GstSingleQueue * sq) @@ -1464,7 +1440,7 @@ apply_buffer (GstMultiQueue * mq, GstSingleQueue * sq, GstClockTime timestamp, { GST_MULTI_QUEUE_MUTEX_LOCK (mq); - /* if no timestamp is set, assume it's continuous with the previous + /* if no timestamp is set, assume it's continuous with the previous * time */ if (timestamp == GST_CLOCK_TIME_NONE) timestamp = segment->position; @@ -2580,7 +2556,7 @@ compute_high_id (GstMultiQueue * mq) lowest = sq->nextid; } else if (!GST_PAD_IS_EOS (sq->srcpad) && sq->srcresult != GST_FLOW_EOS) { /* If we don't have a global highid, or the global highid is lower than - * this single queue's last outputted id, store the queue's one, + * this single queue's last outputted id, store the queue's one, * unless the singlequeue output is at EOS */ if ((highid == G_MAXUINT32) || (sq->oldid > highid)) highid = sq->oldid; diff --git a/plugins/elements/gstoutputselector.c b/plugins/elements/gstoutputselector.c index 15d547807..03cf20621 100644 --- a/plugins/elements/gstoutputselector.c +++ b/plugins/elements/gstoutputselector.c @@ -19,6 +19,7 @@ /** * SECTION:element-output-selector + * @title: output-selector * @see_also: #GstOutputSelector, #GstInputSelector * * Direct input stream to one out of N output pads. diff --git a/plugins/elements/gstqueue.c b/plugins/elements/gstqueue.c index 57c57591e..e98c1f601 100644 --- a/plugins/elements/gstqueue.c +++ b/plugins/elements/gstqueue.c @@ -24,6 +24,7 @@ /** * SECTION:element-queue + * @title: queue * * Data is queued until one of the limits specified by the * #GstQueue:max-size-buffers, #GstQueue:max-size-bytes and/or diff --git a/plugins/elements/gstqueue2.c b/plugins/elements/gstqueue2.c index 3a878e0d1..51db8285b 100644 --- a/plugins/elements/gstqueue2.c +++ b/plugins/elements/gstqueue2.c @@ -25,6 +25,7 @@ /** * SECTION:element-queue2 + * @title: queue2 * * Data is queued until one of the limits specified by the * #GstQueue2:max-size-buffers, #GstQueue2:max-size-bytes and/or diff --git a/plugins/elements/gststreamiddemux.c b/plugins/elements/gststreamiddemux.c index 49fc29054..f0b1dd29b 100644 --- a/plugins/elements/gststreamiddemux.c +++ b/plugins/elements/gststreamiddemux.c @@ -24,6 +24,7 @@ /** * SECTION:element-streamiddemux + * @title: streamiddemux * * The basic concept was started from de-funneling element which restores one * serialized stream via #GstFunnel to its original state. #GstStreamidDemux diff --git a/plugins/elements/gsttee.c b/plugins/elements/gsttee.c index 2369814bd..8531992cb 100644 --- a/plugins/elements/gsttee.c +++ b/plugins/elements/gsttee.c @@ -23,6 +23,7 @@ /** * SECTION:element-tee + * @title: tee * @see_also: #GstIdentity * * Split data to multiple pads. Branching the data flow is useful when e.g. @@ -34,14 +35,14 @@ * provide separate threads for each branch. Otherwise a blocked dataflow in one * branch would stall the other branches. * - * <refsect2> - * <title>Example launch line</title> + * ## Example launch line * |[ * gst-launch-1.0 filesrc location=song.ogg ! decodebin ! tee name=t ! queue ! audioconvert ! audioresample ! autoaudiosink t. ! queue ! audioconvert ! goom ! videoconvert ! autovideosink - * ]| Play song.ogg audio file which must be in the current working directory + * ]| + * + * Play song.ogg audio file which must be in the current working directory * and render visualisations using the goom element (this can be easier done * using the playbin element, this is just an example pipeline). - * </refsect2> */ #ifdef HAVE_CONFIG_H diff --git a/plugins/elements/gsttypefindelement.c b/plugins/elements/gsttypefindelement.c index fa192ca2a..5da2d7571 100644 --- a/plugins/elements/gsttypefindelement.c +++ b/plugins/elements/gsttypefindelement.c @@ -20,6 +20,7 @@ */ /** * SECTION:element-typefind + * @title: typefind * * Determines the media-type of a stream. It applies typefind functions in the * order of their rank. Once the type has been detected it sets its src pad caps diff --git a/plugins/elements/gstvalve.c b/plugins/elements/gstvalve.c index 04cc965b8..9dbc7a6f6 100644 --- a/plugins/elements/gstvalve.c +++ b/plugins/elements/gstvalve.c @@ -22,6 +22,7 @@ /** * SECTION:element-valve + * @title: valve * * The valve is a simple element that drops buffers when the #GstValve:drop * property is set to %TRUE and lets then through otherwise. |