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.
2025-01-26 09:08:14 +00:00 · 2011-03-24 13:22:57 +02:00 · 2011-03-24 13:22:57 +02:00 · 02eda0e3d9
commit 02eda0e3d9
parent 71dcd52cc0
4 changed files with 45 additions and 44 deletions
--- a/libs/gst/base/gstbasesrc.c
+++ b/libs/gst/base/gstbasesrc.c
@ -59,7 +59,7 @@
 *     #GstBaseSrcClass.is_seekable() returns %TRUE.
 *   </para></listitem>
 *   <listitem><para>
- *     #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().
 *   </para></listitem>
 *   <listitem><para>
@ -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.
 *
--- 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.
--- 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
--- a/libs/gst/base/gstcollectpads.c
+++ b/libs/gst/base/gstcollectpads.c
@ -28,7 +28,7 @@
 * <itemizedlist>
 *   <listitem><para>
 *     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 ().
 *   </para></listitem>
 *   <listitem><para>
 *     Pads are added to the collection with gst_collect_pads_add_pad()/
@ -52,7 +52,7 @@
 *     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() and gst_collect_pads_flush() calls.
 *   </para></listitem>
 *   <listitem><para>
@ -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);