From 02eda0e3d9cb559ddeffe4babc38158fdc662f6b Mon Sep 17 00:00:00 2001 From: Stefan Kost Date: Thu, 24 Mar 2011 13:22:57 +0200 Subject: [PATCH] docs: cleanup and xref fixes Deal with the hints from gtk-doc and fix the xrefs. Apply a work-around for () precedence over @. Move "MT Safe" text to doc body in many places. Trim eol whitespaces. --- libs/gst/base/gstbasesrc.c | 4 +-- libs/gst/base/gstbasesrc.h | 4 +-- libs/gst/base/gstbasetransform.h | 3 +- libs/gst/base/gstcollectpads.c | 78 ++++++++++++++++++++-------------------- 4 files changed, 45 insertions(+), 44 deletions(-) diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c index f673355..dc97580 100644 --- a/libs/gst/base/gstbasesrc.c +++ b/libs/gst/base/gstbasesrc.c @@ -59,7 +59,7 @@ * #GstBaseSrcClass.is_seekable() returns %TRUE. * * - * #GstBaseSrc:Class.query() can convert all supported seek formats to the + * #GstBaseSrcClass.query() can convert all supported seek formats to the * internal format as set with gst_base_src_set_format(). * * @@ -565,7 +565,7 @@ gst_base_src_is_live (GstBaseSrc * src) * for sending NEW_SEGMENT events and for performing seeks. * * If a format of GST_FORMAT_BYTES is set, the element will be able to - * operate in pull mode if the #GstBaseSrc.is_seekable() returns TRUE. + * operate in pull mode if the #GstBaseSrcClass.is_seekable() returns TRUE. * * This function must only be called in states < %GST_STATE_PAUSED. * diff --git a/libs/gst/base/gstbasesrc.h b/libs/gst/base/gstbasesrc.h index 9715972..2a3caec 100644 --- a/libs/gst/base/gstbasesrc.h +++ b/libs/gst/base/gstbasesrc.h @@ -133,8 +133,8 @@ struct _GstBaseSrc { * @unlock: Unlock any pending access to the resource. Subclasses should * unblock any blocked function ASAP. In particular, any create() function in * progress should be unblocked and should return GST_FLOW_WRONG_STATE. Any - * future create() function call should also return GST_FLOW_WRONG_STATE - * until the unlock_stop() function has been called. + * future @create() function call should also return GST_FLOW_WRONG_STATE + * until the @unlock_stop() function has been called. * @unlock_stop: Clear the previous unlock request. Subclasses should clear * any state they set during unlock(), such as clearing command queues. * @event: Override this to implement custom event handling. diff --git a/libs/gst/base/gstbasetransform.h b/libs/gst/base/gstbasetransform.h index 33f971b..72c2b2a 100644 --- a/libs/gst/base/gstbasetransform.h +++ b/libs/gst/base/gstbasetransform.h @@ -143,6 +143,7 @@ struct _GstBaseTransform { /** * GstBaseTransformClass: + * @parent_class: Element parent class * @transform_caps: Optional. Given the pad in this direction and the given * caps, what caps are allowed on the other pad in this * element ? @@ -170,7 +171,7 @@ struct _GstBaseTransform { * Transform the incoming buffer in-place. * @event: Optional. * Event handler on the sink pad. This function should return - * TRUE if the base class should forward the event. + * TRUE if the base class should forward the event. * @src_event: Optional. * Event handler on the source pad. * @passthrough_on_same_caps: If set to TRUE, passthrough mode will be diff --git a/libs/gst/base/gstcollectpads.c b/libs/gst/base/gstcollectpads.c index 8d0aa14..004508d 100644 --- a/libs/gst/base/gstcollectpads.c +++ b/libs/gst/base/gstcollectpads.c @@ -28,7 +28,7 @@ * * * Collectpads are created with gst_collect_pads_new(). A callback should then - * be installed with gst_collect_pads_set_function (). + * be installed with gst_collect_pads_set_function (). * * * Pads are added to the collection with gst_collect_pads_add_pad()/ @@ -52,7 +52,7 @@ * event itself. * * - * 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() and gst_collect_pads_flush() calls. * * @@ -166,9 +166,9 @@ gst_collect_pads_finalize (GObject * object) * * Create a new instance of #GstCollectPads. * - * Returns: (transfer full): a new #GstCollectPads, or NULL in case of an error. - * * MT safe. + * + * Returns: (transfer full): a new #GstCollectPads, or NULL in case of an error. */ GstCollectPads * gst_collect_pads_new (void) @@ -262,10 +262,10 @@ unref_data (GstCollectData * data) * This function calls gst_collect_pads_add_pad_full() passing a value of NULL * for destroy_notify. * + * MT safe. + * * Returns: a new #GstCollectData to identify the new pad. Or NULL * if wrong parameters are supplied. - * - * MT safe. */ GstCollectData * gst_collect_pads_add_pad (GstCollectPads * pads, GstPad * pad, guint size) @@ -297,12 +297,12 @@ gst_collect_pads_add_pad (GstCollectPads * pads, GstPad * pad, guint size) * The pad will be automatically activated in push mode when @pads is * started. * + * MT safe. + * * Since: 0.10.12 * * Returns: a new #GstCollectData to identify the new pad. Or NULL * if wrong parameters are supplied. - * - * MT safe. */ GstCollectData * gst_collect_pads_add_pad_full (GstCollectPads * pads, GstPad * pad, guint size, @@ -365,7 +365,7 @@ find_pad (GstCollectData * data, GstPad * pad) * @user_data: (closure): user data to pass to @clip_func * * Install a clipping function that is called right after a buffer is received - * on a pad managed by @pads. See #GstCollectDataClipFunction for more info. + * on a pad managed by @pads. See #GstCollectPadsClipFunction for more info. * * Since: 0.10.26 */ @@ -390,14 +390,14 @@ gst_collect_pads_set_clip_function (GstCollectPads * pads, * @pad: (transfer none): the pad to remove * * Remove a pad from the collection of collect pads. This function will also - * free the #GstCollectData and all the resources that were allocated with + * free the #GstCollectData and all the resources that were allocated with * gst_collect_pads_add_pad(). * * The pad will be deactivated automatically when @pads is stopped. * - * Returns: %TRUE if the pad could be removed. - * * MT safe. + * + * Returns: %TRUE if the pad could be removed. */ gboolean gst_collect_pads_remove_pad (GstCollectPads * pads, GstPad * pad) @@ -480,9 +480,9 @@ unknown_pad: * * This function is currently not implemented. * - * Returns: %TRUE if the pad is active. - * * MT safe. + * + * Returns: %TRUE if the pad is active. */ gboolean gst_collect_pads_is_active (GstCollectPads * pads, GstPad * pad) @@ -502,13 +502,13 @@ gst_collect_pads_is_active (GstCollectPads * pads, GstPad * pad) * @pads: the collectspads to use * * Collect data on all pads. This function is usually called - * from a #GstTask function in an element. + * from a #GstTask function in an element. * * This function is currently not implemented. * - * Returns: #GstFlowReturn of the operation. - * * MT safe. + * + * Returns: #GstFlowReturn of the operation. */ GstFlowReturn gst_collect_pads_collect (GstCollectPads * pads) @@ -528,13 +528,13 @@ gst_collect_pads_collect (GstCollectPads * pads) * @length: the length to collect * * Collect data with @offset and @length on all pads. This function - * is typically called in the getrange function of an element. + * is typically called in the getrange function of an element. * * This function is currently not implemented. * - * Returns: #GstFlowReturn of the operation. - * * MT safe. + * + * Returns: #GstFlowReturn of the operation. */ GstFlowReturn gst_collect_pads_collect_range (GstCollectPads * pads, guint64 offset, @@ -607,7 +607,7 @@ gst_collect_pads_set_flushing_unlocked (GstCollectPads * pads, } } /* Setting the pads to flushing means that we changed the values which - * are 'protected' by the cookie. We therefore update it to force a + * are 'protected' by the cookie. We therefore update it to force a * recalculation of the current pad status. */ pads->abidata.ABI.pad_cookie++; } @@ -741,10 +741,10 @@ gst_collect_pads_stop (GstCollectPads * pads) * should be called with the @pads LOCK held, such as in the callback * handler. * + * MT safe. + * * Returns: (transfer full): The buffer in @data or NULL if no buffer is queued. * should unref the buffer after usage. - * - * MT safe. */ GstBuffer * gst_collect_pads_peek (GstCollectPads * pads, GstCollectData * data) @@ -775,10 +775,10 @@ gst_collect_pads_peek (GstCollectPads * pads, GstCollectData * data) * * Free-function: gst_buffer_unref * + * MT safe. + * * Returns: (transfer full): The buffer in @data or NULL if no buffer was * queued. You should unref the buffer after usage. - * - * MT safe. */ GstBuffer * gst_collect_pads_pop (GstCollectPads * pads, GstCollectData * data) @@ -826,10 +826,10 @@ gst_collect_pads_clear (GstCollectPads * pads, GstCollectData * data) * This function should be called with @pads LOCK held, such as * in the callback. * + * MT safe. + * * Returns: The maximum number of bytes queued on all pads. This function * returns 0 if a pad has no queued buffer. - * - * MT safe. */ /* FIXME, we can do this in the _chain functions */ guint @@ -894,11 +894,11 @@ not_filled: * This function should be called with @pads LOCK held, such as * in the callback. * + * MT safe. + * * Returns: The number of bytes available for consumption in the * memory pointed to by @bytes. This can be less than @size and * is 0 if the pad is end-of-stream. - * - * MT safe. */ guint gst_collect_pads_read (GstCollectPads * pads, GstCollectData * data, @@ -939,9 +939,9 @@ gst_collect_pads_read (GstCollectPads * pads, GstCollectData * data, * that requested. A return of NULL signals that the pad is end-of-stream. * Unref the buffer with gst_buffer_unref() after use. * - * Since: 0.10.18 - * * MT safe. + * + * Since: 0.10.18 */ GstBuffer * gst_collect_pads_read_buffer (GstCollectPads * pads, GstCollectData * data, @@ -981,13 +981,13 @@ gst_collect_pads_read_buffer (GstCollectPads * pads, GstCollectData * data, * * Free-function: gst_buffer_unref * + * MT safe. + * * Returns: (transfer full): a #GstBuffer. The size of the buffer can be less * that requested. A return of NULL signals that the pad is end-of-stream. * Unref the buffer after use. * * Since: 0.10.18 - * - * MT safe. */ GstBuffer * gst_collect_pads_take_buffer (GstCollectPads * pads, GstCollectData * data, @@ -1012,10 +1012,10 @@ gst_collect_pads_take_buffer (GstCollectPads * pads, GstCollectData * data, * This function should be called with @pads LOCK held, such as * in the callback. * + * MT safe. + * * Returns: The number of bytes flushed. This can be less than @size and * is 0 if the pad was end-of-stream. - * - * MT safe. */ guint gst_collect_pads_flush (GstCollectPads * pads, GstCollectData * data, @@ -1186,7 +1186,7 @@ gst_collect_pads_event (GstPad * pad, GstEvent * event) gst_pad_event_default (pad, event); /* now unblock the chain function. - * no cond per pad, so they all unblock, + * no cond per pad, so they all unblock, * non-flushing block again */ GST_OBJECT_LOCK (pads); data->abidata.ABI.flushing = TRUE; @@ -1260,7 +1260,7 @@ gst_collect_pads_event (GstPad * pad, GstEvent * event) data->abidata.ABI.new_segment = TRUE; - /* we must not forward this event since multiple segments will be + /* we must not forward this event since multiple segments will be * accumulated and this is certainly not what we want. */ gst_event_unref (event); /* FIXME: collect-pads based elements need to create their own newsegment @@ -1302,7 +1302,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, GstBuffer * buffer) @@ -1392,7 +1392,7 @@ gst_collect_pads_chain (GstPad * pad, GstBuffer * buffer) /* wait to be collected, this must happen from another thread triggered * by the _chain function of another pad. We release the lock so we * can get stopped or flushed as well. We can however not get EOS - * because we still hold the STREAM_LOCK. + * because we still hold the STREAM_LOCK. */ GST_COLLECT_PADS_WAIT (pads); -- 2.7.4