From 85763437c7fa0aace72571223d77fbfe29a65be9 Mon Sep 17 00:00:00 2001 From: Mathieu Duponchelle Date: Mon, 8 Feb 2021 14:31:09 +0100 Subject: [PATCH] docs: standardize GstBufferList documentation * Don't repeat what annotations are stating with respect to ownership transfer, nullability * Misc cleanup / typo fixes / addition of links Part-of: --- gst/gstbufferlist.c | 40 ++++++++++++++++------------------------ gst/gstbufferlist.h | 2 +- 2 files changed, 17 insertions(+), 25 deletions(-) diff --git a/gst/gstbufferlist.c b/gst/gstbufferlist.c index 5dfc9ca..dca4335 100644 --- a/gst/gstbufferlist.c +++ b/gst/gstbufferlist.c @@ -30,7 +30,7 @@ * Buffer lists are an object containing a list of buffers. * * Buffer lists are created with gst_buffer_list_new() and filled with data - * using a gst_buffer_list_insert(). + * using gst_buffer_list_insert(). * * Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is * interesting when multiple buffers need to be pushed in one go because it @@ -147,14 +147,10 @@ gst_buffer_list_init (GstBufferList * list, guint n_allocated, gsize slice_size) * gst_buffer_list_new_sized: * @size: an initial reserved size * - * Creates a new, empty #GstBufferList. The caller is responsible for unreffing - * the returned #GstBufferList. The list will have @size space preallocated so - * that memory reallocations can be avoided. + * Creates a new, empty #GstBufferList. The list will have @size space + * preallocated so that memory reallocations can be avoided. * - * Free-function: gst_buffer_list_unref - * - * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref() - * after usage. + * Returns: (transfer full): the new #GstBufferList. */ GstBufferList * gst_buffer_list_new_sized (guint size) @@ -182,13 +178,9 @@ gst_buffer_list_new_sized (guint size) /** * gst_buffer_list_new: * - * Creates a new, empty #GstBufferList. The caller is responsible for unreffing - * the returned #GstBufferList. - * - * Free-function: gst_buffer_list_unref + * Creates a new, empty #GstBufferList. * - * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref() - * after usage. + * Returns: (transfer full): the new #GstBufferList. */ GstBufferList * gst_buffer_list_new (void) @@ -240,10 +232,10 @@ gst_buffer_list_remove_range_internal (GstBufferList * list, guint idx, * @func: (scope call): a #GstBufferListFunc to call * @user_data: (closure): user data passed to @func * - * Call @func with @data for each buffer in @list. + * Calls @func with @data for each buffer in @list. * * @func can modify the passed buffer pointer or its contents. The return value - * of @func define if this function returns or if the remaining buffers in + * of @func defines if this function returns or if the remaining buffers in * the list should be skipped. * * Returns: %TRUE when @func returned %TRUE for each buffer in @list or when @@ -341,7 +333,7 @@ gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func, * @list: a #GstBufferList * @idx: the index * - * Get the buffer at @idx. + * Gets the buffer at @idx. * * You must make sure that @idx does not exceed the number of * buffers available. @@ -413,7 +405,7 @@ gst_buffer_list_get_writable (GstBufferList * list, guint idx) * @idx: the index * @buffer: (transfer full): a #GstBuffer * - * Insert @buffer at @idx in @list. Other buffers are moved to make room for + * Inserts @buffer at @idx in @list. Other buffers are moved to make room for * this new buffer. * * A -1 value for @idx will append the buffer at the end. @@ -473,7 +465,7 @@ gst_buffer_list_insert (GstBufferList * list, gint idx, GstBuffer * buffer) * @idx: the index * @length: the amount to remove * - * Remove @length buffers starting from @idx in @list. The following buffers + * Removes @length buffers starting from @idx in @list. The following buffers * are moved to close the gap. */ void @@ -491,8 +483,8 @@ gst_buffer_list_remove (GstBufferList * list, guint idx, guint length) * gst_buffer_list_copy_deep: * @list: a #GstBufferList * - * Create a copy of the given buffer list. This will make a newly allocated - * copy of the buffer that the source buffer list contains. + * Creates a copy of the given buffer list. This will make a newly allocated + * copy of the buffers that the source buffer list contains. * * Returns: (transfer full): a new copy of @list. * @@ -530,10 +522,10 @@ gst_buffer_list_copy_deep (const GstBufferList * list) * gst_buffer_list_calculate_size: * @list: a #GstBufferList * - * Calculates the size of the data contained in buffer list by adding the + * Calculates the size of the data contained in @list by adding the * size of all buffers. * - * Returns: the size of the data contained in buffer list in bytes. + * Returns: the size of the data contained in @list in bytes. * * Since: 1.14 */ @@ -611,7 +603,7 @@ gst_clear_buffer_list (GstBufferList ** list_ptr) * gst_buffer_list_copy: (skip) * @list: a #GstBufferList * - * Create a shallow copy of the given buffer list. This will make a newly + * Creates a shallow copy of the given buffer list. This will make a newly * allocated copy of the source list with copies of buffer pointers. The * refcount of buffers pointed to will be increased by one. * diff --git a/gst/gstbufferlist.h b/gst/gstbufferlist.h index 87132c9..6077717 100644 --- a/gst/gstbufferlist.h +++ b/gst/gstbufferlist.h @@ -38,7 +38,7 @@ typedef struct _GstBufferList GstBufferList; /** * GstBufferListFunc: - * @buffer: (out) (nullable): pointer the buffer + * @buffer: (out) (nullable): pointer to the buffer * @idx: the index of @buffer * @user_data: user data passed to gst_buffer_list_foreach() * -- 2.7.4