doc fixes, to link to function, just write gst_cool_function(), don't prefix with '#'

Original commit message from CVS:
* gst/gstcaps.c:
* gst/gstelement.c: (gst_element_send_event):
* gst/gstevent.c:
* gst/gstinfo.c:
* gst/gstiterator.c:
* gst/gstiterator.h:
* gst/gstpad.c: (gst_pad_send_event):
* gst/gststructure.c:
* gst/gsturi.c:
* gst/gstutils.c:
* gst/gstvalue.c:
* libs/gst/base/gstadapter.c:
doc fixes, to link to function, just write gst_cool_function(), don't
prefix with '#'

ChangeLog

@@ -1,3 +1,19 @@
+2006-01-27  Stefan Kost  <ensonic@users.sf.net>
+	* gst/gstcaps.c:
+	* gst/gstelement.c: (gst_element_send_event):
+	* gst/gstevent.c:
+	* gst/gstinfo.c:
+	* gst/gstiterator.c:
+	* gst/gstiterator.h:
+	* gst/gstpad.c: (gst_pad_send_event):
+	* gst/gststructure.c:
+	* gst/gsturi.c:
+	* gst/gstutils.c:
+	* gst/gstvalue.c:
+	* libs/gst/base/gstadapter.c:
+          doc fixes, to link to function, just write gst_cool_function(), don't
+          prefix with '#'
+
 2006-01-27  Jan Schmidt  <thaytan@mad.scientist.com>
 
 	* plugins/elements/gsttee.c: (gst_tee_do_push),

gst/gstcaps.c

@@ -1587,7 +1587,7 @@ gst_caps_replace (GstCaps ** caps, GstCaps * newcaps)
  * @caps: a #GstCaps
  *
  * Converts @caps to a string representation.  This string representation
- * can be converted back to a #GstCaps by #gst_caps_from_string.
+ * can be converted back to a #GstCaps by gst_caps_from_string().
  *
  * Returns: a newly allocated string representing @caps.
  */

gst/gstelement.c

@@ -62,10 +62,10 @@
  * You can get and set a #GstClock on an element using gst_element_get_clock()
  * and gst_element_set_clock().
  * Some elements can provide a clock for the pipeline if
- * gst_element_provides_clock() returns TRUE. With the gst_element_provide_clock()
+ * gst_element_provides_clock() returns %TRUE. With the gst_element_provide_clock()
  * method one can retrieve the clock provided by such an element.
  * Not all elements require a clock to operate correctly. If
- * gst_element_requires_clock() returns TRUE, a clock should be set on the
+ * gst_element_requires_clock() returns %TRUE, a clock should be set on the
  * element with gst_element_set_clock().
  *
  * Note that clock slection and distribution is normally handled by the
@@ -1401,7 +1401,7 @@ no_bus:
  * _gst_element_error_printf:
  * @format: the printf-like format to use, or NULL
  *
- * This function is only used internally by the #gst_element_error macro.
+ * This function is only used internally by the gst_element_error() macro.
  *
  * Returns: a newly allocated string, or NULL if the format was NULL or ""
  *
@@ -1735,36 +1735,36 @@ interrupted:
  * @element: a #GstElement to get the state of.
  * @state: a pointer to #GstState to hold the state. Can be NULL.
  * @pending: a pointer to #GstState to hold the pending state.
- *           Can be NULL.
+ *           Can be %NULL.
  * @timeout: a #GstClockTime to specify the timeout for an async
- *           state change or GST_CLOCK_TIME_NONE for infinite timeout.
+ *           state change or %GST_CLOCK_TIME_NONE for infinite timeout.
  *
  * Gets the state of the element.
  *
  * For elements that performed an ASYNC state change, as reported by
- * #gst_element_set_state(), this function will block up to the
+ * gst_element_set_state(), this function will block up to the
  * specified timeout value for the state change to complete.
  * If the element completes the state change or goes into
  * an error, this function returns immediately with a return value of
- * #GST_STATE_CHANGE_SUCCESS or #GST_STATE_CHANGE_FAILURE respectively.
+ * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
  *
- * For elements that did not return #GST_STATE_CHANGE_ASYNC, this function
+ * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
  * returns the current and pending state immediately.
  *
- * This function returns #GST_STATE_CHANGE_NO_PREROLL if the element
+ * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
  * successfully changed its state but is not able to provide data yet.
  * This mostly
  * happens for live sources that only produce data in the PLAYING state.
- * While the state change return is equivalent to #GST_STATE_CHANGE_SUCCESS, it
+ * While the state change return is equivalent to %GST_STATE_CHANGE_SUCCESS, it
  * is returned to the application to signal that some sink elements might not
  * be able to complete their state change because an element is not producing
  * data to complete the preroll. When setting the element to playing,
  * the preroll will complete and playback will start.
  *
- * Returns: #GST_STATE_CHANGE_SUCCESS if the element has no more pending state
+ * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
- *          and the last state change succeeded, #GST_STATE_CHANGE_ASYNC if the
+ *          and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
  *          element is still performing a state change or
- *          #GST_STATE_CHANGE_FAILURE if the last state change failed.
+ *          %GST_STATE_CHANGE_FAILURE if the last state change failed.
  *
  * MT safe.
  */
@@ -1950,7 +1950,7 @@ complete:
  *
  * Brings the element to the lost state. The current state of the
  * element is copied to the pending state so that any call to
- * #gst_element_get_state() will return ASYNC.
+ * gst_element_get_state() will return ASYNC.
  *
  * This is mostly used for elements that lost their preroll buffer
  * in the PAUSED state after a flush, they become PAUSED again

gst/gstevent.c

@@ -32,8 +32,8 @@
  *
  * Events are usually created with gst_event_new_*() which takes event-type
  * specific parameters as arguments.
- * To send an event use gst_element_send_event(),gst_pad_send_event() or
+ * To send an event application will usually use gst_element_send_event() and
- * gst_pad_push_event().
+ * elements will use gst_pad_send_event() or gst_pad_push_event().
  * The event should be unreffed with gst_event_unref() if it has not been sent.
  *
  * Events that have been received can be parsed with their respective 

gst/gstinfo.c

@@ -539,9 +539,9 @@ gst_debug_construct_term_color (guint colorinfo)
  * The default logging handler used by GStreamer. Logging functions get called
  * whenever a macro like GST_DEBUG or similar is used. This function outputs the
  * message and additional info using the glib error handler.
- * You can add other handlers by using #gst_debug_add_log_function.
+ * You can add other handlers by using gst_debug_add_log_function().
  * And you can remove this handler by calling
- * gst_debug_remove_log_function (gst_debug_log_default);
+ * gst_debug_remove_log_function(gst_debug_log_default);
  */
 void
 gst_debug_log_default (GstDebugCategory * category, GstDebugLevel level,

gst/gstiterator.c

@@ -298,7 +298,7 @@ done:
  * @it: The #GstIterator to resync
  *
  * Resync the iterator. this function is mostly called
- * after #gst_iterator_next() returned #GST_ITERATOR_RESYNC.
+ * after gst_iterator_next() returned %GST_ITERATOR_RESYNC.
  *
  * MT safe.
  */

gst/gstiterator.h

@@ -129,9 +129,9 @@ typedef void		  (*GstIteratorFreeFunction)	(GstIterator *it);
  * GstIteratorFoldFunction:
  * @item: the item to fold
  * @ret: a GValue collecting the result
- * @user_data: data passed to #gst_iterator_fold
+ * @user_data: data passed to gst_iterator_fold()
  *
- * A function to be passed to #gst_iterator_fold.
+ * A function to be passed to gst_iterator_fold().
  *
  * Returns: TRUE if the fold should continue, FALSE if it should stop.
  */

gst/gstpad.c

@@ -1873,7 +1873,7 @@ done:
  *
  * Gets the capabilities this pad can produce or consume.
  * Note that this method doesn't necessarily returns the caps set by
- * #gst_pad_set_caps - use #GST_PAD_CAPS for that instead.
+ * gst_pad_set_caps() - use #GST_PAD_CAPS for that instead.
  * gst_pad_get_caps returns all possible caps a pad can operate with, using
  * the pad's get_caps function;
  * this returns the pad template caps if not explicitly set.
@@ -3302,7 +3302,7 @@ not_linked:
  * gst_pad_check_pull_range:
  * @pad: a sink #GstPad.
  *
- * Checks if a #gst_pad_pull_range() can be performed on the peer
+ * Checks if a gst_pad_pull_range() can be performed on the peer
  * source pad. This function is used by plugins that want to check
  * if they can use random access on the peer source pad.
  *
@@ -3841,7 +3841,7 @@ no_task:
  * from the GstTaskFunction.
  *
  * This function will deadlock if called from the GstTaskFunction of
- * the task. Use #gst_task_pause() instead.
+ * the task. Use gst_task_pause() instead.
  *
  * Regardless of whether the pad has a task, the stream lock is acquired and
  * released so as to ensure that streaming through this pad has finished.

gst/gststructure.c

@@ -447,7 +447,7 @@ gst_structure_set (GstStructure * structure, const gchar * field, ...)
  * @fieldname: the name of the field to set
  * @varargs: variable arguments
  *
- * va_list form of #gst_structure_set.
+ * va_list form of gst_structure_set().
  */
 void
 gst_structure_set_valist (GstStructure * structure,
@@ -656,7 +656,7 @@ gst_structure_remove_fields (GstStructure * structure,
  * @fieldname: the name of the field to remove
  * @varargs: NULL-terminated list of more fieldnames to remove
  *
- * va_list form of #gst_structure_remove_fields.
+ * va_list form of gst_structure_remove_fields().
  */
 void
 gst_structure_remove_fields_valist (GstStructure * structure,

gst/gsturi.c

@@ -28,9 +28,10 @@
  * #GstElement to simplify then handling of URI.
  *
  * An application can use the following functions to quickly get an element
- * that handles the given URI for reading or writing (#gst_element_make_from_uri).
+ * that handles the given URI for reading or writing
+ * (gst_element_make_from_uri()).
  *
- * Source and Sink plugins should implement when possible this interface.
+ * Source and Sink plugins should implement this interface when possible.
  *
  * Last reviewed on 2005-11-09 (0.9.4)
  */

gst/gstutils.c

@@ -2794,7 +2794,10 @@ gst_pad_remove_buffer_probe (GstPad * pad, guint handler_id)
  * @list: the taglist to post on the bus and create event from.
  *
  * Posts a message to the bus that new tags were found and pushes the
- * tags as event. Takes ownership of the taglist.
+ * tags as event. Takes ownership of the @list.
+ *
+ * This is a utility method for elements. Applications should use the
+ * #GstTagSetter interface.
  */
 void
 gst_element_found_tags_for_pad (GstElement * element,
@@ -2821,7 +2824,10 @@ push_and_ref (GstPad * pad, GstEvent * event)
  * @list: list of tags.
  *
  * Posts a message to the bus that new tags were found, and pushes an event
- * to all sourcepads. Takes ownership of the taglist.
+ * to all sourcepads. Takes ownership of the @list.
+ *
+ * This is a utility method for elements. Applications should use the
+ * #GstTagSetter interface.
  */
 void
 gst_element_found_tags (GstElement * element, GstTagList * list)

gst/gstvalue.c

@@ -2736,7 +2736,7 @@ gst_value_register_union_func (GType type1, GType type2, GstValueUnionFunc func)
  * Determines if intersecting two values will produce a valid result.
  * Two values will produce a valid intersection if they have the same
  * type, or if there is a method (registered by
- * #gst_value_register_intersection_func) to calculate the intersection.
+ * gst_value_register_intersection_func()) to calculate the intersection.
  *
  * Returns: TRUE if the values can intersect
  */

libs/gst/base/gstadapter.c

@@ -47,12 +47,12 @@
  *   adapter = this->adapter;
  *   
  *   // put buffer into adapter
- *   #gst_adapter_push (adapter, buffer);
+ *   gst_adapter_push (adapter, buffer);
  *   // while we can read out 512 bytes, process them
- *   while (#gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) {
+ *   while (gst_adapter_available (adapter) >= 512 && ret == GST_FLOW_OK) {
  *     // use flowreturn as an error value
- *     ret = my_library_foo (#gst_adapter_peek (adapter, 512));
+ *     ret = my_library_foo (gst_adapter_peek (adapter, 512));
- *     #gst_adapter_flush (adapter, 512);
+ *     gst_adapter_flush (adapter, 512);
  *   }
  *   
  *   gst_object_unref (this);