docs: libgstbase: more gobject introspection annotations

Many of these are superfluous and were added for clarity.

12 files changed, 193 insertions, 113 deletions

diff --git a/libs/gst/base/gstadapter.c b/libs/gst/base/gstadapter.c
index f4b1c508de..75944a902a 100644
--- a/libs/gst/base/gstadapter.c
+++ b/libs/gst/base/gstadapter.c
@@ -191,7 +191,7 @@ gst_adapter_finalize (GObject * object)
  *
  * Creates a new #GstAdapter. Free with g_object_unref().
  *
- * Returns: a new #GstAdapter
+ * Returns: (transfer full): a new #GstAdapter
  */
 GstAdapter *
 gst_adapter_new (void)
@@ -285,7 +285,7 @@ copy_into_unchecked (GstAdapter * adapter, guint8 * dest, guint skip,
 /**
  * gst_adapter_push:
  * @adapter: a #GstAdapter
- * @buf: a #GstBuffer to add to queue in the adapter
+ * @buf: (transfer full): a #GstBuffer to add to queue in the adapter
  *
  * Adds the data from @buf to the data stored inside @adapter and takes
  * ownership of the buffer.
@@ -386,7 +386,8 @@ gst_adapter_try_to_merge_up (GstAdapter * adapter, guint size)
  *
  * Returns #NULL if @size bytes are not available.
  *
- * Returns: a pointer to the first @size bytes of data, or NULL.
+ * Returns: (transfer none) (array length=size): a pointer to the first
+ *     @size bytes of data, or NULL
  */
 const guint8 *
 gst_adapter_peek (GstAdapter * adapter, guint size)
@@ -459,7 +460,7 @@ gst_adapter_peek (GstAdapter * adapter, guint size)
 /**
  * gst_adapter_copy:
  * @adapter: a #GstAdapter
- * @dest: the memory where to copy to
+ * @dest: (out caller-allocates) (array length=size): the memory to copy into
  * @offset: the bytes offset in the adapter to start from
  * @size: the number of bytes to copy
  *
@@ -608,7 +609,10 @@ gst_adapter_take_internal (GstAdapter * adapter, guint nbytes)
  *
  * Caller owns returned value. g_free after usage.
  *
- * Returns: oven-fresh hot data, or #NULL if @nbytes bytes are not available
+ * Free-function: g_free
+ *
+ * Returns: (transfer full) (array length=nbytes): oven-fresh hot data, or
+ *     #NULL if @nbytes bytes are not available
  */
 guint8 *
 gst_adapter_take (GstAdapter * adapter, guint nbytes)
@@ -644,10 +648,12 @@ gst_adapter_take (GstAdapter * adapter, guint nbytes)
  *
  * Caller owns returned value. gst_buffer_unref() after usage.
  *
- * Since: 0.10.6
+ * Free-function: gst_buffer_unref
  *
- * Returns: a #GstBuffer containing the first @nbytes of the adapter,
- * or #NULL if @nbytes bytes are not available
+ * Returns: (transfer full): a #GstBuffer containing the first @nbytes of
+ *     the adapter, or #NULL if @nbytes bytes are not available
+ *
+ * Since: 0.10.6
  */
 GstBuffer *
 gst_adapter_take_buffer (GstAdapter * adapter, guint nbytes)
@@ -714,16 +720,17 @@ done:
  * @adapter: a #GstAdapter
  * @nbytes: the number of bytes to take
  *
- * Returns a #GSList of buffers containing the first @nbytes bytes of the
+ * Returns a #GList of buffers containing the first @nbytes bytes of the
  * @adapter. The returned bytes will be flushed from the adapter.
  * When the caller can deal with individual buffers, this function is more
- * performant because no memory should be coppied.
+ * performant because no memory should be copied.
  *
  * Caller owns returned list and contained buffers. gst_buffer_unref() each
- * buffer in the list before freeng the list after usage.
+ * buffer in the list before freeing the list after usage.
  *
- * Returns: a #GSList of buffers containing the first @nbytes of the adapter,
- * or #NULL if @nbytes bytes are not available
+ * Returns: (element-type Gst.Buffer) (transfer full): a #GList of buffers
+ *     containing the first @nbytes of the adapter, or #NULL if @nbytes bytes
+ *     are not available
  *
  * Since: 0.10.31
  */
@@ -820,7 +827,7 @@ gst_adapter_available_fast (GstAdapter * adapter)
 /**
  * gst_adapter_prev_timestamp:
  * @adapter: a #GstAdapter
- * @distance: pointer to location for distance or NULL
+ * @distance: (out) (allow-none): pointer to location for distance, or NULL
  *
  * Get the timestamp that was before the current byte in the adapter. When
  * @distance is given, the amount of bytes between the timestamp and the current
diff --git a/libs/gst/base/gstbasesink.c b/libs/gst/base/gstbasesink.c
index 7a3fb74f5b..cde24082d7 100644
--- a/libs/gst/base/gstbasesink.c
+++ b/libs/gst/base/gstbasesink.c
@@ -945,9 +945,11 @@ gst_base_sink_get_ts_offset (GstBaseSink * sink)
  *
  * The #GstCaps on the buffer can be used to determine the type of the buffer.
  *
- * Returns: a #GstBuffer. gst_buffer_unref() after usage. This function returns
- * NULL when no buffer has arrived in the sink yet or when the sink is not in
- * PAUSED or PLAYING.
+ * Free-function: gst_buffer_unref
+ *
+ * Returns: (transfer full): a #GstBuffer. gst_buffer_unref() after usage.
+ *     This function returns NULL when no buffer has arrived in the sink yet
+ *     or when the sink is not in PAUSED or PLAYING.
  *
  * Since: 0.10.15
  */
@@ -1069,10 +1071,10 @@ gst_base_sink_get_latency (GstBaseSink * sink)
 /**
  * gst_base_sink_query_latency:
  * @sink: the sink
- * @live: if the sink is live
- * @upstream_live: if an upstream element is live
- * @min_latency: the min latency of the upstream elements
- * @max_latency: the max latency of the upstream elements
+ * @live: (out) (allow-none): if the sink is live
+ * @upstream_live: (out) (allow-none): if an upstream element is live
+ * @min_latency: (out) (allow-none): the min latency of the upstream elements
+ * @max_latency: (out) (allow-none): the max latency of the upstream elements
  *
  * Query the sink for the latency parameters. The latency will be queried from
  * the upstream elements. @live will be TRUE if @sink is configured to
@@ -2054,7 +2056,7 @@ gst_base_sink_adjust_time (GstBaseSink * basesink, GstClockTime time)
  * gst_base_sink_wait_clock:
  * @sink: the sink
  * @time: the running_time to be reached
- * @jitter: the jitter to be filled with time diff (can be NULL)
+ * @jitter: (out) (allow-none): the jitter to be filled with time diff, or NULL
  *
  * This function will block until @time is reached. It is usually called by
  * subclasses that use their own internal synchronisation.
@@ -2164,10 +2166,10 @@ no_clock:
  * This function should only be called with the PREROLL_LOCK held, like in the
  * render function.
  *
- * Since: 0.10.11
- *
  * Returns: #GST_FLOW_OK if the preroll completed and processing can
  * continue. Any other return value should be returned from the render vmethod.
+ *
+ * Since: 0.10.11
  */
 GstFlowReturn
 gst_base_sink_wait_preroll (GstBaseSink * sink)
@@ -2202,7 +2204,7 @@ step_unlocked:
 /**
  * gst_base_sink_do_preroll:
  * @sink: the sink
- * @obj: the object that caused the preroll
+ * @obj: (transfer none): the mini object that caused the preroll
  *
  * If the @sink spawns its own thread for pulling buffers from upstream it
  * should call this method after it has pulled a buffer. If the element needed
@@ -2211,10 +2213,10 @@ step_unlocked:
  *
  * This function should be called with the PREROLL_LOCK held.
  *
- * Since 0.10.22
- *
  * Returns: #GST_FLOW_OK if the preroll completed and processing can
  * continue. Any other return value should be returned from the render vmethod.
+ *
+ * Since 0.10.22
  */
 GstFlowReturn
 gst_base_sink_do_preroll (GstBaseSink * sink, GstMiniObject * obj)
@@ -2259,7 +2261,7 @@ preroll_failed:
  * gst_base_sink_wait_eos:
  * @sink: the sink
  * @time: the running_time to be reached
- * @jitter: the jitter to be filled with time diff (can be NULL)
+ * @jitter: (out) (allow-none): the jitter to be filled with time diff, or NULL
  *
  * This function will block until @time is reached. It is usually called by
  * subclasses that use their own internal synchronisation but want to let the
@@ -2271,9 +2273,9 @@ preroll_failed:
  * The @time argument should be the running_time of when the EOS should happen
  * and will be adjusted with any latency and offset configured in the sink.
  *
- * Since 0.10.15
- *
  * Returns: #GstFlowReturn
+ *
+ * Since 0.10.15
  */
 GstFlowReturn
 gst_base_sink_wait_eos (GstBaseSink * sink, GstClockTime time,
diff --git a/libs/gst/base/gstbasesrc.c b/libs/gst/base/gstbasesrc.c
index 649a07c9df..97a91f696a 100644
--- a/libs/gst/base/gstbasesrc.c
+++ b/libs/gst/base/gstbasesrc.c
@@ -580,9 +580,9 @@ gst_base_src_set_format (GstBaseSrc * src, GstFormat format)
 /**
  * gst_base_src_query_latency:
  * @src: the source
- * @live: if the source is live
- * @min_latency: the min latency of the source
- * @max_latency: the max latency of the source
+ * @live: (out) (allow-none): if the source is live
+ * @min_latency: (out) (allow-none): the min latency of the source
+ * @max_latency: (out) (allow-none): the max latency of the source
  *
  * Query the source for the latency parameters. @live will be TRUE when @src is
  * configured as a live source. @min_latency will be set to the difference
diff --git a/libs/gst/base/gstbasetransform.c b/libs/gst/base/gstbasetransform.c
index 62731c5c4c..8bb7fb8f56 100644
--- a/libs/gst/base/gstbasetransform.c
+++ b/libs/gst/base/gstbasetransform.c
@@ -2758,7 +2758,7 @@ gst_base_transform_set_gap_aware (GstBaseTransform * trans, gboolean gap_aware)
 /**
  * gst_base_transform_suggest:
  * @trans: a #GstBaseTransform
- * @caps: caps to suggest
+ * @caps: (transfer none): caps to suggest
  * @size: buffer size to suggest
  *
  * Instructs @trans to suggest new @caps upstream. A copy of @caps will be
diff --git a/libs/gst/base/gstbitreader.c b/libs/gst/base/gstbitreader.c
index 1dd8979e42..a4393992cb 100644
--- a/libs/gst/base/gstbitreader.c
+++ b/libs/gst/base/gstbitreader.c
@@ -43,7 +43,9 @@
  *
  * Create a new #GstBitReader instance, which will read from @data.
  *
- * Returns: a new #GstBitReader instance
+ * Free-function: gst_bit_reader_free
+ *
+ * Returns: (transfer full): a new #GstBitReader instance
  *
  * Since: 0.10.22
  */
@@ -65,7 +67,9 @@ gst_bit_reader_new (const guint8 * data, guint size)
  * Create a new #GstBitReader instance, which will read from the
  * #GstBuffer @buffer.
  *
- * Returns: a new #GstBitReader instance
+ * Free-function: gst_bit_reader_free
+ *
+ * Returns: (transfer full): a new #GstBitReader instance
  *
  * Since: 0.10.22
  */
@@ -80,7 +84,7 @@ gst_bit_reader_new_from_buffer (const GstBuffer * buffer)
 
 /**
  * gst_bit_reader_free:
- * @reader: a #GstBitReader instance
+ * @reader: (in) (transfer full): a #GstBitReader instance
  *
  * Frees a #GstBitReader instance, which was previously allocated by
  * gst_bit_reader_new() or gst_bit_reader_new_from_buffer().
@@ -98,7 +102,7 @@ gst_bit_reader_free (GstBitReader * reader)
 /**
  * gst_bit_reader_init:
  * @reader: a #GstBitReader instance
- * @data: Data from which the #GstBitReader should read
+ * @data: (in) (array length=size): data from which the bit reader should read
  * @size: Size of @data in bytes
  *
  * Initializes a #GstBitReader instance to read from @data. This function
@@ -119,7 +123,7 @@ gst_bit_reader_init (GstBitReader * reader, const guint8 * data, guint size)
 /**
  * gst_bit_reader_init_from_buffer:
  * @reader: a #GstBitReader instance
- * @buffer: Buffer from which the #GstBitReader should read
+ * @buffer: (transfer none): Buffer from which the #GstBitReader should read
  *
  * Initializes a #GstBitReader instance to read from @buffer. This function
  * can be called on already initialized instances.
diff --git a/libs/gst/base/gstbytereader-docs.h b/libs/gst/base/gstbytereader-docs.h
index 91747601e4..01b8326a04 100644
--- a/libs/gst/base/gstbytereader-docs.h
+++ b/libs/gst/base/gstbytereader-docs.h
@@ -608,7 +608,7 @@ gdouble gst_byte_reader_peek_float64_be_unchecked (GstByteReader * reader);
  * gst_byte_reader_peek_data_unchecked:
  * @reader: a #GstByteReader instance
  *
- * Returns: a constant pointer to the current data position
+ * Returns: (transfer none): a constant pointer to the current data position
  *
  * Since: 0.10.25
  */
@@ -622,7 +622,8 @@ const guint8 * gst_byte_reader_peek_data_unchecked (GstByteReader * reader);
  * if at least @size bytes are left. Advances the current read position by
  * @size bytes.
  *
- * Returns: a constant pointer to the current data position.
+ * Returns: (transfer none) (array length=size): a constant pointer to the
+ *     current data position.
  *
  * Since: 0.10.25
  */
@@ -636,8 +637,10 @@ const guint8 * gst_byte_reader_get_data_unchecked (GstByteReader * reader, guint
  * without checking if at least @size bytes are left. Advances the current read
  * position by @size bytes.
  *
- * Returns: a newly-allocated copy of the data @size bytes in size. Free with
- *     g_free() when no longer needed.
+ * Free-function: g_free
+ *
+ * Returns: (transfer full) (array length=size): a newly-allocated copy of the
+ *     data @size bytes in size. Free with g_free() when no longer needed.
  *
  * Since: 0.10.25
  */
diff --git a/libs/gst/base/gstbytereader.c b/libs/gst/base/gstbytereader.c
index d8796aaa65..e0cc7237f1 100644
--- a/libs/gst/base/gstbytereader.c
+++ b/libs/gst/base/gstbytereader.c
@@ -43,12 +43,15 @@
 
 /**
  * gst_byte_reader_new:
- * @data: Data from which the #GstByteReader should read
+ * @data: (in) (transfer none) (array length=size): data from which the
+ *     #GstByteReader should read
  * @size: Size of @data in bytes
  *
  * Create a new #GstByteReader instance, which will read from @data.
  *
- * Returns: a new #GstByteReader instance
+ * Free-function: gst_byte_reader_free
+ *
+ * Returns: (transfer full): a new #GstByteReader instance
  *
  * Since: 0.10.22
  */
@@ -65,12 +68,14 @@ gst_byte_reader_new (const guint8 * data, guint size)
 
 /**
  * gst_byte_reader_new_from_buffer:
- * @buffer: Buffer from which the #GstByteReader should read
+ * @buffer: (transfer none): Buffer from which the #GstByteReader should read
  *
  * Create a new #GstByteReader instance, which will read from the
  * #GstBuffer @buffer.
  *
- * Returns: a new #GstByteReader instance
+ * Free-function: gst_byte_reader_free
+ *
+ * Returns: (transfer full): a new #GstByteReader instance
  *
  * Since: 0.10.22
  */
@@ -85,7 +90,7 @@ gst_byte_reader_new_from_buffer (const GstBuffer * buffer)
 
 /**
  * gst_byte_reader_free:
- * @reader: a #GstByteReader instance
+ * @reader: (in) (transfer full): a #GstByteReader instance
  *
  * Frees a #GstByteReader instance, which was previously allocated by
  * gst_byte_reader_new() or gst_byte_reader_new_from_buffer().
@@ -103,7 +108,8 @@ gst_byte_reader_free (GstByteReader * reader)
 /**
  * gst_byte_reader_init:
  * @reader: a #GstByteReader instance
- * @data: Data from which the #GstByteReader should read
+ * @data: (in) (transfer none) (array length=size): data from which
+ *     the #GstByteReader should read
  * @size: Size of @data in bytes
  *
  * Initializes a #GstByteReader instance to read from @data. This function
@@ -124,7 +130,7 @@ gst_byte_reader_init (GstByteReader * reader, const guint8 * data, guint size)
 /**
  * gst_byte_reader_init_from_buffer:
  * @reader: a #GstByteReader instance
- * @buffer: Buffer from which the #GstByteReader should read
+ * @buffer: (transfer none): Buffer from which the #GstByteReader should read
  *
  * Initializes a #GstByteReader instance to read from @buffer. This function
  * can be called on already initialized instances.
@@ -852,7 +858,8 @@ GST_BYTE_READER_PEEK_GET(64,gdouble,float64_be)
  * gst_byte_reader_get_data:
  * @reader: a #GstByteReader instance
  * @size: Size in bytes
- * @val: Pointer to a #guint8 to store the result
+ * @val: (out) (transfer none) (array length=size): address of a
+ *     #guint8 pointer variable in which to store the result
  *
  * Returns a constant pointer to the current data
  * position if at least @size bytes are left and
@@ -874,7 +881,8 @@ gst_byte_reader_get_data (GstByteReader * reader, guint size,
  * gst_byte_reader_peek_data:
  * @reader: a #GstByteReader instance
  * @size: Size in bytes
- * @val: Pointer to a #guint8 to store the result
+ * @val: (out) (transfer none) (array length=size): address of a
+ *     #guint8 pointer variable in which to store the result
  *
  * Returns a constant pointer to the current data
  * position if at least @size bytes are left and
@@ -896,11 +904,14 @@ gst_byte_reader_peek_data (const GstByteReader * reader, guint size,
  * gst_byte_reader_dup_data:
  * @reader: a #GstByteReader instance
  * @size: Size in bytes
- * @val: Pointer to a #guint8 to store the result
+ * @val: (out) (transfer full) (array length=size): address of a
+ *     #guint8 pointer variable in which to store the result
+ *
+ * Free-function: g_free
  *
  * Returns a newly-allocated copy of the current data
  * position if at least @size bytes are left and
- * updates the current position.
+ * updates the current position. Free with g_free() when no longer needed.
  *
  * Returns: %TRUE if successful, %FALSE otherwise.
  *
@@ -1107,7 +1118,8 @@ GST_BYTE_READER_SKIP_STRING (32);
 /**
  * gst_byte_reader_peek_string:
  * @reader: a #GstByteReader instance
- * @str: Pointer to a #gchar to store the result
+ * @str: (out) (transfer none) (array zero-terminated=1): address of a
+ *     #gchar pointer varieble in which to store the result
  *
  * Returns a constant pointer to the current data position if there is
  * a NUL-terminated string in the data (this could be just a NUL terminator).
@@ -1124,7 +1136,8 @@ GST_BYTE_READER_SKIP_STRING (32);
 /**
  * gst_byte_reader_peek_string_utf8:
  * @reader: a #GstByteReader instance
- * @str: Pointer to a #gchar to store the result
+ * @str: (out) (transfer none) (array zero-terminated=1): address of a
+ *     #gchar pointer varieble in which to store the result
  *
  * Returns a constant pointer to the current data position if there is
  * a NUL-terminated string in the data (this could be just a NUL terminator).
@@ -1158,7 +1171,8 @@ gst_byte_reader_peek_string_utf8 (const GstByteReader * reader,
 /**
  * gst_byte_reader_get_string_utf8:
  * @reader: a #GstByteReader instance
- * @str: Pointer to a #gchar to store the result
+ * @str: (out) (transfer none) (array zero-terminated=1): address of a
+ *     #gchar pointer varieble in which to store the result
  *
  * Returns a constant pointer to the current data position if there is
  * a NUL-terminated string in the data (this could be just a NUL terminator),
@@ -1215,7 +1229,10 @@ gst_byte_reader_dup_string_utf##bits (GstByteReader * reader, type ** str) \
 /**
  * gst_byte_reader_dup_string_utf8:
  * @reader: a #GstByteReader instance
- * @str: address of a string pointer to store the result
+ * @str: (out) (transfer full) (array zero-terminated=1): address of a
+ *     #gchar pointer varieble in which to store the result
+ *
+ * Free-function: g_free
  *
  * FIXME:Reads (copies) a NUL-terminated string in the #GstByteReader instance,
  * advancing the current position to the byte after the string. This will work
@@ -1234,7 +1251,10 @@ GST_BYTE_READER_DUP_STRING (8, gchar);
 /**
  * gst_byte_reader_dup_string_utf16:
  * @reader: a #GstByteReader instance
- * @str: address of a #guint16 pointer to store the result
+ * @str: (out) (transfer full) (array zero-terminated=1): address of a
+ *     #guint16 pointer varieble in which to store the result
+ *
+ * Free-function: g_free
  *
  * Returns a newly-allocated copy of the current data position if there is
  * a NUL-terminated UTF-16 string in the data (this could be an empty string
@@ -1259,7 +1279,10 @@ GST_BYTE_READER_DUP_STRING (16, guint16);
 /**
  * gst_byte_reader_dup_string_utf32:
  * @reader: a #GstByteReader instance
- * @str: address of a #guint32 pointer to store the result
+ * @str: (out) (transfer full) (array zero-terminated=1): address of a
+ *     #guint32 pointer varieble in which to store the result
+ *
+ * Free-function: g_free
  *
  * Returns a newly-allocated copy of the current data position if there is
  * a NUL-terminated UTF-32 string in the data (this could be an empty string
diff --git a/libs/gst/base/gstbytewriter-docs.h b/libs/gst/base/gstbytewriter-docs.h
index e7a3d70cc3..da4c20efaa 100644
--- a/libs/gst/base/gstbytewriter-docs.h
+++ b/libs/gst/base/gstbytewriter-docs.h
@@ -291,7 +291,7 @@ void gst_byte_writer_put_float64_le_unchecked (GstByteWriter *writer, gdouble va
 /**
  * gst_byte_writer_put_data_unchecked:
  * @writer: #GstByteWriter instance
- * @data: Data to write
+ * @data: (in) (transfer none) (array length=size): Data to write
  * @size: Size of @data in bytes
  *
  * Writes @size bytes of @data to @writer without
diff --git a/libs/gst/base/gstbytewriter.c b/libs/gst/base/gstbytewriter.c
index 6aa940ac8a..25564f7d97 100644
--- a/libs/gst/base/gstbytewriter.c
+++ b/libs/gst/base/gstbytewriter.c
@@ -43,7 +43,9 @@
  *
  * Creates a new, empty #GstByteWriter instance
  *
- * Returns: a new, empty #GstByteWriter instance
+ * Free-function: gst_byte_writer_free
+ *
+ * Returns: (transfer full): a new, empty #GstByteWriter instance
  *
  * Since: 0.10.26
  */
@@ -64,7 +66,9 @@ gst_byte_writer_new (void)
  * Creates a new #GstByteWriter instance with the given
  * initial data size.
  *
- * Returns: a new #GstByteWriter instance
+ * Free-function: gst_byte_writer_free
+ *
+ * Returns: (transfer full): a new #GstByteWriter instance
  *
  * Since: 0.10.26
  */
@@ -91,7 +95,9 @@ gst_byte_writer_new_with_size (guint size, gboolean fixed)
  * memory area. If @initialized is %TRUE it is possible to
  * read @size bytes from the #GstByteWriter from the beginning.
  *
- * Returns: a new #GstByteWriter instance
+ * Free-function: gst_byte_writer_free
+ *
+ * Returns: (transfer full): a new #GstByteWriter instance
  *
  * Since: 0.10.26
  */
@@ -120,7 +126,9 @@ gst_byte_writer_new_with_data (guint8 * data, guint size, gboolean initialized)
  *
  * <note>@buffer must be writable</note>
  *
- * Returns: a new #GstByteWriter instance
+ * Free-function: gst_byte_writer_free
+ *
+ * Returns: (transfer full): a new #GstByteWriter instance
  *
  * Since: 0.10.26
  */
@@ -179,7 +187,8 @@ gst_byte_writer_init_with_size (GstByteWriter * writer, guint size,
 /**
  * gst_byte_writer_init_with_data:
  * @writer: #GstByteWriter instance
- * @data: Memory area for writing
+ * @data: (in callee-allocated) (array length=size) (transfer none): Memory
+ *     area for writing
  * @size: Size of @data in bytes
  * @initialized: If %TRUE the complete data can be read from the beginning
  *
@@ -207,7 +216,7 @@ gst_byte_writer_init_with_data (GstByteWriter * writer, guint8 * data,
 /**
  * gst_byte_writer_init_with_buffer:
  * @writer: #GstByteWriter instance
- * @buffer: Buffer used for writing
+ * @buffer: (transfer none): Buffer used for writing
  * @initialized: If %TRUE the complete data can be read from the beginning
  *
  * Initializes @writer with the given
@@ -253,7 +262,9 @@ gst_byte_writer_reset (GstByteWriter * writer)
  *
  * Resets @writer and returns the current data.
  *
- * Returns: the current data. g_free() after usage.
+ * Free-function: g_free
+ *
+ * Returns: (transfer full): the current data. g_free() after usage.
  *
  * Since: 0.10.26
  */
@@ -279,7 +290,10 @@ gst_byte_writer_reset_and_get_data (GstByteWriter * writer)
  *
  * Resets @writer and returns the current data as buffer.
  *
- * Returns: the current data as buffer. gst_buffer_unref() after usage.
+ * Free-function: gst_buffer_unref
+ *
+ * Returns: (transfer full): the current data as buffer. gst_buffer_unref()
+ *     after usage.
  *
  * Since: 0.10.26
  */
@@ -300,7 +314,7 @@ gst_byte_writer_reset_and_get_buffer (GstByteWriter * writer)
 
 /**
  * gst_byte_writer_free:
- * @writer: #GstByteWriter instance
+ * @writer: (in) (transfer full): #GstByteWriter instance
  *
  * Frees @writer and all memory allocated by it.
  *
@@ -317,12 +331,14 @@ gst_byte_writer_free (GstByteWriter * writer)
 
 /**
  * gst_byte_writer_free_and_get_data:
- * @writer: #GstByteWriter instance
+ * @writer: (in) (transfer full): #GstByteWriter instance
  *
  * Frees @writer and all memory allocated by it except
  * the current data, which is returned.
  *
- * Returns: the current data. g_free() after usage.
+ * Free-function: g_free
+ *
+ * Returns: (transfer full): the current data. g_free() after usage.
  *
  * Since: 0.10.26
  */
@@ -341,12 +357,15 @@ gst_byte_writer_free_and_get_data (GstByteWriter * writer)
 
 /**
  * gst_byte_writer_free_and_get_buffer:
- * @writer: #GstByteWriter instance
+ * @writer: (in) (transfer full): #GstByteWriter instance
  *
  * Frees @writer and all memory allocated by it except
  * the current data, which is returned as #GstBuffer.
  *
- * Returns: the current data as buffer. gst_buffer_unref() after usage.
+ * Free-function: gst_buffer_unref
+ *
+ * Returns: (transfer full): the current data as buffer. gst_buffer_unref()
+ *     after usage.
  *
  * Since: 0.10.26
  */
@@ -721,7 +740,8 @@ CREATE_WRITE_STRING_FUNC (32, guint32);
 /**
  * gst_byte_writer_put_string_utf8:
  * @writer: #GstByteWriter instance
- * @data: UTF8 string to write
+ * @data: (transfer none) (array zero-terminated=1) (type utf8): UTF8 string to
+ *     write
  *
  * Writes a NUL-terminated UTF8 string to @writer (including the terminator).
  *
@@ -732,7 +752,7 @@ CREATE_WRITE_STRING_FUNC (32, guint32);
 /**
  * gst_byte_writer_put_string_utf16:
  * @writer: #GstByteWriter instance
- * @data: UTF16 string to write
+ * @data: (transfer none) (array zero-terminated=1): UTF16 string to write
  *
  * Writes a NUL-terminated UTF16 string to @writer (including the terminator).
  *
@@ -743,7 +763,7 @@ CREATE_WRITE_STRING_FUNC (32, guint32);
 /**
  * gst_byte_writer_put_string_utf32:
  * @writer: #GstByteWriter instance
- * @data: UTF32 string to write
+ * @data: (transfer none) (array zero-terminated=1): UTF32 string to write
  *
  * Writes a NUL-terminated UTF32 string to @writer (including the terminator).
  *
@@ -754,7 +774,7 @@ CREATE_WRITE_STRING_FUNC (32, guint32);
 /**
  * gst_byte_writer_put_data:
  * @writer: #GstByteWriter instance
- * @data: Data to write
+ * @data: (transfer none) (array length=size): Data to write
  * @size: Size of @data in bytes
  *
  * Writes @size bytes of @data to @writer.
diff --git a/libs/gst/base/gstbytewriter.h b/libs/gst/base/gstbytewriter.h
index 72554a5ed1..186480d6cd 100644
--- a/libs/gst/base/gstbytewriter.h
+++ b/libs/gst/base/gstbytewriter.h
@@ -154,7 +154,7 @@ gboolean gst_byte_writer_put_string_utf32 (GstByteWriter *writer, const guint32
 /**
  * gst_byte_writer_put_string:
  * @writer: #GstByteWriter instance
- * @data: Null terminated string
+ * @data: (in) (array zero-terminated=1): Null terminated string
  *
  * Write a NUL-terminated string to @writer (including the terminator). The
  * string is assumed to be in an 8-bit encoding (e.g. ASCII,UTF-8 or
diff --git a/libs/gst/base/gstcollectpads.c b/libs/gst/base/gstcollectpads.c
index 2259e2a61b..d3120db367 100644
--- a/libs/gst/base/gstcollectpads.c
+++ b/libs/gst/base/gstcollectpads.c
@@ -166,7 +166,7 @@ gst_collect_pads_finalize (GObject * object)
  *
  * Create a new instance of #GstCollectPads.
  *
- * Returns: a new #GstCollectPads, or NULL in case of an error.
+ * Returns: (transfer full): a new #GstCollectPads, or NULL in case of an error.
  *
  * MT safe.
  */
@@ -184,7 +184,7 @@ gst_collect_pads_new (void)
  * gst_collect_pads_set_function:
  * @pads: the collectspads to use
  * @func: the function to set
- * @user_data: user data passed to the function
+ * @user_data: (closure): user data passed to the function
  *
  * Set the callback function and user data that will be called when
  * all the pads added to the collection have buffers queued.
@@ -241,7 +241,7 @@ unref_data (GstCollectData * data)
 /**
  * gst_collect_pads_add_pad:
  * @pads: the collectspads to use
- * @pad: the pad to add
+ * @pad: (transfer none): the pad to add
  * @size: the size of the returned #GstCollectData structure
  *
  * Add a pad to the collection of collect pads. The pad has to be
@@ -276,7 +276,7 @@ gst_collect_pads_add_pad (GstCollectPads * pads, GstPad * pad, guint size)
 /**
  * gst_collect_pads_add_pad_full:
  * @pads: the collectspads to use
- * @pad: the pad to add
+ * @pad: (transfer none): the pad to add
  * @size: the size of the returned #GstCollectData structure
  * @destroy_notify: function to be called before the returned #GstCollectData
  * structure is freed
@@ -362,7 +362,7 @@ find_pad (GstCollectData * data, GstPad * pad)
  * gst_collect_pads_set_clip_function:
  * @pads: the collectspads to use
  * @clipfunc: clip function to install
- * @user_data: user data to pass to @clip_func
+ * @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.
@@ -387,7 +387,7 @@ gst_collect_pads_set_clip_function (GstCollectPads * pads,
 /**
  * gst_collect_pads_remove_pad:
  * @pads: the collectspads to use
- * @pad: the pad to remove
+ * @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 
@@ -473,7 +473,7 @@ unknown_pad:
 
 /**
  * gst_collect_pads_is_active:
- * @pads: the collectspads to use
+ * @pads: (transfer none): the collectspads to use
  * @pad: the pad to check
  *
  * Check if a pad is active.
@@ -773,8 +773,10 @@ gst_collect_pads_peek (GstCollectPads * pads, GstCollectData * data)
  * should be called with the @pads LOCK held, such as in the callback
  * handler.
  *
- * Returns: The buffer in @data or NULL if no buffer was queued.
- *   You should unref the buffer after usage.
+ * Free-function: gst_buffer_unref
+ *
+ * Returns: (transfer full): The buffer in @data or NULL if no buffer was
+ *   queued. You should unref the buffer after usage.
  *
  * MT safe.
  */
@@ -883,7 +885,7 @@ not_filled:
  * gst_collect_pads_read:
  * @pads: the collectspads to query
  * @data: the data to use
- * @bytes: a pointer to a byte array
+ * @bytes: (out) (transfer none) (array length=size): a pointer to a byte array
  * @size: the number of bytes to read
  *
  * Get a pointer in @bytes where @size bytes can be read from the
@@ -931,11 +933,13 @@ gst_collect_pads_read (GstCollectPads * pads, GstCollectData * data,
  *
  * This function should be called with @pads LOCK held, such as in the callback.
  *
- * Since: 0.10.18
+ * Free-function: gst_buffer_unref
+ *
+ * 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 with gst_buffer_unref() after use.
  *
- * Returns: 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.
  */
@@ -975,11 +979,13 @@ gst_collect_pads_read_buffer (GstCollectPads * pads, GstCollectData * data,
  *
  * This function should be called with @pads LOCK held, such as in the callback.
  *
- * Since: 0.10.18
+ * Free-function: gst_buffer_unref
  *
- * Returns: 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.
+ * 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.
  */
diff --git a/libs/gst/base/gsttypefindhelper.c b/libs/gst/base/gsttypefindhelper.c
index e586e39114..653f905542 100644
--- a/libs/gst/base/gsttypefindhelper.c
+++ b/libs/gst/base/gsttypefindhelper.c
@@ -220,8 +220,9 @@ helper_find_get_length (gpointer data)
  * @func: A generic #GstTypeFindHelperGetRangeFunction that will be used
  *        to access data at random offsets when doing the typefinding
  * @size: The length in bytes
- * @extension: extenstion of the media
- * @prob: location to store the probability of the found caps, or #NULL
+ * @extension: extension of the media
+ * @prob: (out) (allow-none): location to store the probability of the found
+ *     caps, or #NULL
  *
  * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
  * however, this function will use the specified function @func to obtain the
@@ -236,8 +237,10 @@ helper_find_get_length (gpointer data)
  * functions for the given extension, which might speed up the typefinding
  * in many cases.
  *
- * Returns: The #GstCaps corresponding to the data stream.
- * Returns #NULL if no #GstCaps matches the data stream.
+ * Free-function: gst_caps_unref
+ *
+ * Returns: (transfer full): the #GstCaps corresponding to the data stream.
+ *     Returns #NULL if no #GstCaps matches the data stream.
  *
  * Since: 0.10.26
  */
@@ -348,7 +351,8 @@ gst_type_find_helper_get_range_ext (GstObject * obj,
  * @func: A generic #GstTypeFindHelperGetRangeFunction that will be used
  *        to access data at random offsets when doing the typefinding
  * @size: The length in bytes
- * @prob: location to store the probability of the found caps, or #NULL
+ * @prob: (out) (allow-none): location to store the probability of the found
+ *     caps, or #NULL
  *
  * Utility function to do pull-based typefinding. Unlike gst_type_find_helper()
  * however, this function will use the specified function @func to obtain the
@@ -359,8 +363,10 @@ gst_type_find_helper_get_range_ext (GstObject * obj,
  * callback can then call the upstream peer pad with offsets adjusted for the
  * tag size, for example).
  *
- * Returns: The #GstCaps corresponding to the data stream.
- * Returns #NULL if no #GstCaps matches the data stream.
+ * Free-function: gst_caps_unref
+ *
+ * Returns: (transfer full): the #GstCaps corresponding to the data stream.
+ *     Returns #NULL if no #GstCaps matches the data stream.
  */
 GstCaps *
 gst_type_find_helper_get_range (GstObject * obj,
@@ -377,8 +383,10 @@ gst_type_find_helper_get_range (GstObject * obj,
  *
  * Tries to find what type of data is flowing from the given source #GstPad.
  *
- * Returns: The #GstCaps corresponding to the data stream.
- * Returns #NULL if no #GstCaps matches the data stream.
+ * Free-function: gst_caps_unref
+ *
+ * Returns: (transfer full): the #GstCaps corresponding to the data stream.
+ *     Returns #NULL if no #GstCaps matches the data stream.
  */
 
 GstCaps *
@@ -471,8 +479,9 @@ buf_helper_find_suggest (gpointer data, guint probability, const GstCaps * caps)
 /**
  * gst_type_find_helper_for_buffer:
  * @obj: object doing the typefinding, or NULL (used for logging)
- * @buf: a #GstBuffer with data to typefind
- * @prob: location to store the probability of the found caps, or #NULL
+ * @buf: (in) (transfer none): a #GstBuffer with data to typefind
+ * @prob: (out) (allow-none): location to store the probability of the found
+ *     caps, or #NULL
  *
  * Tries to find what type of data is contained in the given #GstBuffer, the
  * assumption being that the buffer represents the beginning of the stream or
@@ -485,8 +494,11 @@ buf_helper_find_suggest (gpointer data, guint probability, const GstCaps * caps)
  * and the caps with the highest probability will be returned, or #NULL if
  * the content of the buffer could not be identified.
  *
- * Returns: The #GstCaps corresponding to the data, or #NULL if no type could
- * be found. The caller should free the caps returned with gst_caps_unref().
+ * Free-function: gst_caps_unref
+ *
+ * Returns: (transfer full): the #GstCaps corresponding to the data, or #NULL
+ *     if no type could be found. The caller should free the caps returned
+ *     with gst_caps_unref().
  */
 GstCaps *
 gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
@@ -540,7 +552,7 @@ gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
 
 /**
  * gst_type_find_helper_for_extension:
- * @obj: object doing the typefinding, or NULL (used for logging)
+ * @obj: (allow-none): object doing the typefinding, or NULL (used for logging)
  * @extension: an extension
  *
  * Tries to find the best #GstCaps associated with @extension.
@@ -549,8 +561,11 @@ gst_type_find_helper_for_buffer (GstObject * obj, GstBuffer * buf,
  * of rank. The caps of the first typefinder that can handle @extension will be
  * returned.
  *
- * Returns: The #GstCaps corresponding to @extension, or #NULL if no type could
- * be found. The caller should free the caps returned with gst_caps_unref().
+ * Free-function: gst_caps_unref
+ *
+ * Returns: (transfer full): the #GstCaps corresponding to @extension, or
+ *     #NULL if no type could be found. The caller should free the caps
+ *     returned with gst_caps_unref().
  * 
  * Since: 0.10.23
  */