From 5467c643791facedd88e79d01294760b64645f52 Mon Sep 17 00:00:00 2001
From: Wim Taymans <wim.taymans@collabora.co.uk>
Date: Thu, 12 Mar 2009 10:48:21 +0100
Subject: [PATCH] docs: Improve some docs

Rename some function variables and add some Return: to make the docs more happy.
---
 gst/gstbuffer.h  |  2 ++
 gst/gstevent.h   | 16 ++++++++--------
 gst/gstmessage.h |  2 ++
 gst/gstpad.h     |  3 ++-
 gst/gstquery.h   |  4 ++++
 5 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h
index e4d45c74ab..aa06281016 100644
--- a/gst/gstbuffer.h
+++ b/gst/gstbuffer.h
@@ -370,6 +370,8 @@ gst_buffer_unref (GstBuffer * buf)
  *
  * Create a copy of the given buffer. This will also make a newly allocated
  * copy of the data the source buffer contains.
+ *
+ * Returns: a new copy of @buf.
  */
 #ifdef _FOOL_GTK_DOC_
 G_INLINE_FUNC GstBuffer * gst_buffer_copy (const GstBuffer * buf);
diff --git a/gst/gstevent.h b/gst/gstevent.h
index 4593542dac..121736644f 100644
--- a/gst/gstevent.h
+++ b/gst/gstevent.h
@@ -348,14 +348,14 @@ G_INLINE_FUNC GstEvent * gst_event_ref (GstEvent * event);
 #endif
 
 static inline GstEvent *
-gst_event_ref (GstEvent * ev)
+gst_event_ref (GstEvent * event)
 {
-  return (GstEvent *) gst_mini_object_ref (GST_MINI_OBJECT (ev));
+  return (GstEvent *) gst_mini_object_ref (GST_MINI_OBJECT (event));
 }
 
 /**
  * gst_event_unref:
- * @ev: The event to refcount
+ * @event: The event to refcount
  *
  * Decrease the refcount of an event, freeing it if the refcount reaches 0.
  */
@@ -364,15 +364,15 @@ G_INLINE_FUNC void gst_event_unref (GstEvent * event);
 #endif
 
 static inline void
-gst_event_unref (GstEvent * ev)
+gst_event_unref (GstEvent * event)
 {
-  gst_mini_object_unref (GST_MINI_OBJECT (ev));
+  gst_mini_object_unref (GST_MINI_OBJECT (event));
 }
 
 /* copy event */
 /**
  * gst_event_copy:
- * @ev: The event to copy
+ * @event: The event to copy
  *
  * Copy the event using the event specific copy function.
  */
@@ -381,9 +381,9 @@ G_INLINE_FUNC void gst_event_copy (GstEvent * event);
 #endif
 
 static inline GstEvent *
-gst_event_copy (const GstEvent * ev)
+gst_event_copy (const GstEvent * event)
 {
-  return GST_EVENT_CAST (gst_mini_object_copy (GST_MINI_OBJECT (ev)));
+  return GST_EVENT_CAST (gst_mini_object_copy (GST_MINI_OBJECT (event)));
 }
 
 
diff --git a/gst/gstmessage.h b/gst/gstmessage.h
index ac01453a5c..9a06c9d79d 100644
--- a/gst/gstmessage.h
+++ b/gst/gstmessage.h
@@ -287,6 +287,8 @@ gst_message_unref (GstMessage * msg)
  *
  * Creates a copy of the message. Returns a copy of the message.
  *
+ * Returns: a new copy of @msg.
+ *
  * MT safe
  */
 #ifdef _FOOL_GTK_DOC_
diff --git a/gst/gstpad.h b/gst/gstpad.h
index 9d4c6aa6bf..c12993ba84 100644
--- a/gst/gstpad.h
+++ b/gst/gstpad.h
@@ -558,6 +558,7 @@ typedef struct _GstPadTemplate GstPadTemplate;
  * @do_buffer_signals: counter counting installed buffer signals
  * @do_event_signals: counter counting installed event signals
  * @iterintlinkfunc: get the internal links iterator of this pad
+ * @block_destroy_data: notify function for gst_pad_set_blocked_async_full()
  *
  * The #GstPad structure. Use the functions to update the variables.
  */
@@ -819,7 +820,7 @@ gboolean		gst_pad_set_blocked_async		(GstPad *pad, gboolean blocked,
 								 GstPadBlockCallback callback, gpointer user_data);
 gboolean		gst_pad_set_blocked_async_full		(GstPad *pad, gboolean blocked,
 								 GstPadBlockCallback callback, gpointer user_data,
-                 GDestroyNotify destroy_data);
+                                                                 GDestroyNotify destroy_data);
 gboolean		gst_pad_is_blocked			(GstPad *pad);
 gboolean		gst_pad_is_blocking			(GstPad *pad);
 
diff --git a/gst/gstquery.h b/gst/gstquery.h
index 61cdb55c50..2a45fd8056 100644
--- a/gst/gstquery.h
+++ b/gst/gstquery.h
@@ -189,6 +189,8 @@ GstIterator*    gst_query_type_iterate_definitions (void);
  * @q: a #GstQuery to increase the refcount of.
  *
  * Increases the refcount of the given query by one.
+ *
+ * Returns: @q
  */
 #ifdef _FOOL_GTK_DOC_
 G_INLINE_FUNC GstQuery * gst_query_ref (GstQuery * q);
@@ -224,6 +226,8 @@ gst_query_unref (GstQuery * q)
  *
  * Copies the given query using the copy function of the parent #GstData
  * structure.
+ *
+ * Returns: a new copy of @q.
  */
 #ifdef _FOOL_GTK_DOC_
 G_INLINE_FUNC GstQuery * gst_query_copy (const GstQuery * q);