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

@@ -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.
  *

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
+ *    future @create<!-- -->() function call should also return GST_FLOW_WRONG_STATE
- *    until the unlock_stop() function has been called.
+ *    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.

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 ?

libs/gst/base/gstcollectpads.c

@@ -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
  */
@@ -395,9 +395,9 @@ gst_collect_pads_set_clip_function (GstCollectPads * pads,
  *
  * 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)
@@ -506,9 +506,9 @@ gst_collect_pads_is_active (GstCollectPads * pads, GstPad * pad)
  *
  * 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)
@@ -532,9 +532,9 @@ gst_collect_pads_collect (GstCollectPads * pads)
  *
  * 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,
@@ -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,