diff options
55 files changed, 1080 insertions, 803 deletions
@@ -297,7 +297,7 @@ DllMain (HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpvReserved) * threading system as one of the very first things in your program * (see the example at the beginning of this section). * - * Returns: a pointer to GStreamer's option group. + * Returns: (transfer full): a pointer to GStreamer's option group. */ GOptionGroup * @@ -398,7 +398,7 @@ gst_init_get_option_group (void) /** * gst_init_check: - * @argc: (inout): pointer to application's argc + * @argc: (inout) (allow-none): pointer to application's argc * @argv: (inout) (array length=argc) (allow-none): pointer to application's argv * @err: pointer to a #GError to which a message will be posted on error * @@ -457,7 +457,7 @@ gst_init_check (int *argc, char **argv[], GError ** err) /** * gst_init: - * @argc: (inout): pointer to application's argc + * @argc: (inout) (allow-none): pointer to application's argc * @argv: (inout) (array length=argc) (allow-none): pointer to application's argv * * Initializes the GStreamer library, setting up internal path lists, @@ -1125,10 +1125,10 @@ gst_deinit (void) /** * gst_version: - * @major: pointer to a guint to store the major version number - * @minor: pointer to a guint to store the minor version number - * @micro: pointer to a guint to store the micro version number - * @nano: pointer to a guint to store the nano version number + * @major: (out): pointer to a guint to store the major version number + * @minor: (out): pointer to a guint to store the minor version number + * @micro: (out): pointer to a guint to store the micro version number + * @nano: (out): pointer to a guint to store the nano version number * * Gets the version number of the GStreamer library. */ @@ -1152,7 +1152,8 @@ gst_version (guint * major, guint * minor, guint * micro, guint * nano) * This function returns a string that is useful for describing this version * of GStreamer to the outside world: user agent strings, logging, ... * - * Returns: a newly allocated string describing this version of GStreamer. + * Returns: (transfer full): a newly allocated string describing this version + * of GStreamer. */ gchar * diff --git a/gst/gstbin.c b/gst/gstbin.c index bb549a5529..bfd53d226a 100644 --- a/gst/gstbin.c +++ b/gst/gstbin.c @@ -588,7 +588,7 @@ gst_bin_dispose (GObject * object) * * Creates a new bin with the given name. * - * Returns: a new #GstBin + * Returns: (transfer full): a new #GstBin */ GstElement * gst_bin_new (const gchar * name) @@ -1186,7 +1186,7 @@ had_parent: /** * gst_bin_add: * @bin: a #GstBin - * @element: the #GstElement to add + * @element: (transfer full): the #GstElement to add * * Adds the given element to the bin. Sets the element's parent, and thus * takes ownership of the element. An element can only be added to one bin. @@ -1482,7 +1482,7 @@ already_removing: /** * gst_bin_remove: * @bin: a #GstBin - * @element: the #GstElement to remove + * @element: (transfer none): the #GstElement to remove * * Removes the element from the bin, unparenting it as well. * Unparenting the element means that the element will be dereferenced, @@ -1547,7 +1547,7 @@ iterate_child (GstIterator * it, GstElement * child) * * MT safe. Caller owns returned value. * - * Returns: a #GstIterator of #GstElement, or NULL + * Returns: (transfer full): a #GstIterator of #GstElement, or NULL */ GstIterator * gst_bin_iterate_elements (GstBin * bin) @@ -1597,7 +1597,7 @@ iterate_child_recurse (GstIterator * it, GstElement * child) * * MT safe. Caller owns returned value. * - * Returns: a #GstIterator of #GstElement, or NULL + * Returns: (transfer full): a #GstIterator of #GstElement, or NULL */ GstIterator * gst_bin_iterate_recurse (GstBin * bin) @@ -1668,7 +1668,7 @@ sink_iterator_filter (GstElement * child, GstBin * bin) * * MT safe. Caller owns returned value. * - * Returns: a #GstIterator of #GstElement, or NULL + * Returns: (transfer full): a #GstIterator of #GstElement, or NULL */ GstIterator * gst_bin_iterate_sinks (GstBin * bin) @@ -1730,7 +1730,7 @@ src_iterator_filter (GstElement * child, GstBin * bin) * * MT safe. Caller owns returned value. * - * Returns: a #GstIterator of #GstElement, or NULL + * Returns: (transfer full): a #GstIterator of #GstElement, or NULL */ GstIterator * gst_bin_iterate_sources (GstBin * bin) @@ -2083,7 +2083,7 @@ gst_bin_sort_iterator_new (GstBin * bin) * * MT safe. Caller owns returned value. * - * Returns: a #GstIterator of #GstElement, or NULL + * Returns: (transfer full): a #GstIterator of #GstElement, or NULL */ GstIterator * gst_bin_iterate_sorted (GstBin * bin) @@ -3688,7 +3688,7 @@ compare_name (GstElement * element, const gchar * name) * * MT safe. Caller owns returned reference. * - * Returns: the #GstElement with the given name, or NULL + * Returns: (transfer full): the #GstElement with the given name, or NULL */ GstElement * gst_bin_get_by_name (GstBin * bin, const gchar * name) @@ -3722,7 +3722,7 @@ gst_bin_get_by_name (GstBin * bin, const gchar * name) * * MT safe. Caller owns returned reference. * - * Returns: the #GstElement with the given name, or NULL + * Returns: (transfer full): the #GstElement with the given name, or NULL */ GstElement * gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name) @@ -3779,7 +3779,7 @@ compare_interface (GstElement * element, gpointer interface) * * MT safe. Caller owns returned reference. * - * Returns: A #GstElement inside the bin implementing the interface + * Returns: (transfer full): A #GstElement inside the bin implementing the interface */ GstElement * gst_bin_get_by_interface (GstBin * bin, GType iface) @@ -3813,8 +3813,8 @@ gst_bin_get_by_interface (GstBin * bin, GType iface) * * MT safe. Caller owns returned value. * - * Returns: a #GstIterator of #GstElement for all elements in the bin - * implementing the given interface, or NULL + * Returns: (transfer full): a #GstIterator of #GstElement for all elements + * in the bin implementing the given interface, or NULL */ GstIterator * gst_bin_iterate_all_by_interface (GstBin * bin, GType iface) diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c index 46b53abeb1..871b34d968 100644 --- a/gst/gstbuffer.c +++ b/gst/gstbuffer.c @@ -323,7 +323,8 @@ gst_buffer_init (GstBuffer * buffer) * Creates a newly allocated buffer without any data. * * MT safe. - * Returns: the new #GstBuffer. + * + * Returns: (transfer full): the new #GstBuffer. */ GstBuffer * gst_buffer_new (void) @@ -352,7 +353,8 @@ gst_buffer_new (void) * Note that when @size == 0, the buffer data pointer will be NULL. * * MT safe. - * Returns: the new #GstBuffer. + * + * Returns: (transfer full): the new #GstBuffer. */ GstBuffer * gst_buffer_new_and_alloc (guint size) @@ -397,7 +399,8 @@ gst_buffer_new_and_alloc (guint size) * * MT safe. * - * Returns: a new #GstBuffer, or NULL if the memory couldn't be allocated. + * Returns: (transfer full): a new #GstBuffer, or NULL if the memory couldn't + * be allocated. * * Since: 0.10.13 */ @@ -448,7 +451,7 @@ gst_buffer_try_new_and_alloc (guint size) * Gets the media type of the buffer. This can be NULL if there * is no media type attached to this buffer. * - * Returns: a reference to the #GstCaps. unref after usage. + * Returns: (transfer full): a reference to the #GstCaps. unref after usage. * Returns NULL if there were no caps on this buffer. */ /* this is not made atomic because if the buffer were reffed from multiple @@ -472,7 +475,7 @@ gst_buffer_get_caps (GstBuffer * buffer) /** * gst_buffer_set_caps: * @buffer: a #GstBuffer. - * @caps: a #GstCaps. + * @caps: (transfer none): a #GstCaps. * * Sets the media type on the buffer. The refcount of the caps will * be increased and any previous caps on the buffer will be @@ -514,7 +517,7 @@ gst_buffer_is_metadata_writable (GstBuffer * buf) /** * gst_buffer_make_metadata_writable: - * @buf: a #GstBuffer + * @buf: (transfer full): a #GstBuffer * * Similar to gst_buffer_make_writable, but does not ensure that the buffer * data array is writable. Instead, this just ensures that the returned buffer @@ -524,7 +527,8 @@ gst_buffer_is_metadata_writable (GstBuffer * buf) * After calling this function, @buf should not be referenced anymore. The * result of this function has guaranteed writable metadata. * - * Returns: A new #GstBuffer with writable metadata. + * Returns: (transfer full): a new #GstBuffer with writable metadata, which + * may or may not be the same as @buf. */ GstBuffer * gst_buffer_make_metadata_writable (GstBuffer * buf) @@ -561,8 +565,9 @@ gst_buffer_make_metadata_writable (GstBuffer * buf) * to #GST_CLOCK_TIME_NONE and #GST_BUFFER_OFFSET_NONE. * * MT safe. - * Returns: the new #GstBuffer. - * Returns NULL if the arguments were invalid. + * + * Returns: (transfer full): the new #GstBuffer or NULL if the arguments were + * invalid. */ GstBuffer * gst_buffer_create_sub (GstBuffer * buffer, guint offset, guint size) @@ -680,8 +685,9 @@ gst_buffer_is_span_fast (GstBuffer * buf1, GstBuffer * buf2) * gst_buffer_is_span_fast() to determine if a memcpy will be needed. * * MT safe. - * Returns: the new #GstBuffer that spans the two source buffers. - * Returns NULL if the arguments are invalid. + * + * Returns: (transfer full): the new #GstBuffer that spans the two source + * buffers, or NULL if the arguments are invalid. */ GstBuffer * gst_buffer_span (GstBuffer * buf1, guint32 offset, GstBuffer * buf2, diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h index 730ff81bd6..e454d93331 100644 --- a/gst/gstbuffer.h +++ b/gst/gstbuffer.h @@ -333,7 +333,7 @@ G_STMT_START { \ * GstBuffer instances can potentially increase the number * of memcpy operations in a pipeline. * - * Returns: @buf + * Returns: (transfer full): @buf */ #ifdef _FOOL_GTK_DOC_ G_INLINE_FUNC GstBuffer * gst_buffer_ref (GstBuffer * buf); @@ -347,7 +347,7 @@ gst_buffer_ref (GstBuffer * buf) /** * gst_buffer_unref: - * @buf: a #GstBuffer. + * @buf: (transfer full): a #GstBuffer. * * Decreases the refcount of the buffer. If the refcount reaches 0, the buffer * will be freed. If GST_BUFFER_MALLOCDATA() is non-NULL, this pointer will @@ -371,7 +371,7 @@ 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. + * Returns: (transfer full): a new copy of @buf. */ #ifdef _FOOL_GTK_DOC_ G_INLINE_FUNC GstBuffer * gst_buffer_copy (const GstBuffer * buf); @@ -428,11 +428,14 @@ void gst_buffer_copy_metadata (GstBuffer *dest, const GstBuffe #define gst_buffer_is_writable(buf) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf)) /** * gst_buffer_make_writable: - * @buf: a #GstBuffer + * @buf: (transfer full): a #GstBuffer * * Makes a writable buffer from the given buffer. If the source buffer is * already writable, this will simply return the same buffer. A copy will * otherwise be made using gst_buffer_copy(). + * + * Returns: (transfer full): a writable buffer which may or may not be the + * same as @buf */ #define gst_buffer_make_writable(buf) GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf))) @@ -443,9 +446,10 @@ GstBuffer* gst_buffer_make_metadata_writable (GstBuffer *buf); /** * gst_buffer_replace: - * @obuf: pointer to a pointer to a #GstBuffer to be replaced. - * @nbuf: pointer to a #GstBuffer that will replace the buffer pointed to by - * @obuf. + * @obuf: (inout) (transfer full): pointer to a pointer to a #GstBuffer to be + * replaced. + * @nbuf: (transfer none) (allow-none): pointer to a #GstBuffer that will + * replace the buffer pointed to by @obuf. * * Modifies a pointer to a #GstBuffer to point to a different #GstBuffer. The * modification is done atomically (so this is useful for ensuring thread safety @@ -474,7 +478,7 @@ GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset /** * gst_value_set_buffer: * @v: a #GValue to receive the data - * @b: a #GstBuffer to assign to the GstValue + * @b: (transfer none): a #GstBuffer to assign to the GstValue * * Sets @b as the value of @v. Caller retains reference to buffer. */ @@ -482,7 +486,7 @@ GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset /** * gst_value_take_buffer: * @v: a #GValue to receive the data - * @b: a #GstBuffer to assign to the GstValue + * @b: (transfer full): a #GstBuffer to assign to the GstValue * * Sets @b as the value of @v. Caller gives away reference to buffer. */ @@ -494,6 +498,8 @@ GstBuffer* gst_buffer_span (GstBuffer *buf1, guint32 offset * Receives a #GstBuffer as the value of @v. Does not return a reference to * the buffer, so the pointer is only valid for as long as the caller owns * a reference to @v. + * + * Returns: (transfer none): buffer */ #define gst_value_get_buffer(v) GST_BUFFER_CAST (gst_value_get_mini_object(v)) diff --git a/gst/gstbufferlist.c b/gst/gstbufferlist.c index bfba8176c0..46a4459024 100644 --- a/gst/gstbufferlist.c +++ b/gst/gstbufferlist.c @@ -248,7 +248,10 @@ gst_buffer_list_class_init (GstBufferListClass * list_class) * Creates a new, empty #GstBufferList. The caller is responsible for unreffing * the returned #GstBufferList. * - * Returns: the new #GstBufferList. gst_buffer_list_unref() after usage. + * Free-function: gst_buffer_list_unref + * + * Returns: (transfer full): the new #GstBufferList. gst_buffer_list_unref() + * after usage. * * Since: 0.10.24 */ @@ -377,8 +380,8 @@ gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func, * Note that this function is not efficient for iterating over the entire list. * Use an iterator or gst_buffer_list_foreach() instead. * - * Returns: the buffer at @idx in @group or NULL when there is no buffer. The - * buffer remains valid as long as @list is valid. + * Returns: (transfer none): the buffer at @idx in @group or NULL when there + * is no buffer. The buffer remains valid as long as @list is valid. * * Since: 0.10.24 */ @@ -426,8 +429,10 @@ gst_buffer_list_get (GstBufferList * list, guint group, guint idx) * Iterate the buffers in @list. The owner of the iterator must also be the * owner of a reference to @list while the returned iterator is in use. * - * Returns: a new #GstBufferListIterator of the buffers in @list. - * gst_buffer_list_iterator_free() after usage + * Free-function: gst_buffer_list_iterator_free + * + * Returns: (transfer full): a new #GstBufferListIterator of the buffers in + * @list. gst_buffer_list_iterator_free() after usage * * Since: 0.10.24 */ @@ -448,7 +453,7 @@ gst_buffer_list_iterate (GstBufferList * list) /** * gst_buffer_list_iterator_free: - * @it: the #GstBufferListIterator to free + * @it: (transfer full): the #GstBufferListIterator to free * * Free the iterator. * @@ -500,7 +505,7 @@ gst_buffer_list_iterator_n_buffers (const GstBufferListIterator * it) /** * gst_buffer_list_iterator_add: * @it: a #GstBufferListIterator - * @buffer: a #GstBuffer + * @buffer: (transfer full): a #GstBuffer * * Inserts @buffer into the #GstBufferList iterated with @it. The buffer is * inserted into the current group, immediately before the buffer that would be @@ -529,7 +534,7 @@ gst_buffer_list_iterator_add (GstBufferListIterator * it, GstBuffer * buffer) /** * gst_buffer_list_iterator_add_list: * @it: a #GstBufferListIterator - * @list: a #GList + * @list: (transfer full) (element-type Gst.Buffer): a #GList of buffers * * Inserts @list of buffers into the #GstBufferList iterated with @it. The list is * inserted into the current group, immediately before the buffer that would be @@ -610,7 +615,8 @@ gst_buffer_list_iterator_add_group (GstBufferListIterator * it) * The caller will not get a new ref to the returned #GstBuffer and must not * unref it. * - * Returns: the next buffer in the current group of the buffer list, or NULL + * Returns: (transfer none): the next buffer in the current group of the + * buffer list, or NULL * * Since: 0.10.24 */ @@ -707,7 +713,7 @@ gst_buffer_list_iterator_remove (GstBufferListIterator * it) /** * gst_buffer_list_iterator_take: * @it: a #GstBufferListIterator - * @buffer: a #GstBuffer + * @buffer: (transfer full): a #GstBuffer * * Replaces the last buffer returned by gst_buffer_list_iterator_next() with * @buffer in the #GstBufferList iterated with @it and takes ownership of @@ -719,6 +725,8 @@ gst_buffer_list_iterator_remove (GstBufferListIterator * it) * gst_buffer_list_iterator_steal() and takes ownership of @buffer (i.e. the * refcount of @buffer is not increased). * + * FIXME 0.11: this conditional taking-ownership is not good for bindings + * * Since: 0.10.24 */ void @@ -742,7 +750,8 @@ gst_buffer_list_iterator_take (GstBufferListIterator * it, GstBuffer * buffer) * Returns the last buffer returned by gst_buffer_list_iterator_next() without * modifying the refcount of the buffer. * - * Returns: the last buffer returned by gst_buffer_list_iterator_next() + * Returns: (transfer none): the last buffer returned by + * gst_buffer_list_iterator_next() * * Since: 0.10.24 */ @@ -776,7 +785,7 @@ gst_buffer_list_iterator_steal (GstBufferListIterator * it) * * See #GstBufferListDoFunction for more details. * - * Returns: the return value from @do_func + * Returns: (transfer none): the return value from @do_func * * Since: 0.10.24 */ @@ -818,7 +827,8 @@ gst_buffer_list_iterator_do (GstBufferListIterator * it, * This function will not move the implicit cursor or in any other way affect * the state of the iterator @it or the list. * - * Returns: a new #GstBuffer, gst_buffer_unref() after usage, or NULL + * Returns: (transfer full): a new #GstBuffer, gst_buffer_unref() after usage, + * or NULL * * Since: 0.10.24 */ diff --git a/gst/gstbufferlist.h b/gst/gstbufferlist.h index f7de45658f..519063f6dd 100644 --- a/gst/gstbufferlist.h +++ b/gst/gstbufferlist.h @@ -41,7 +41,7 @@ typedef struct _GstBufferListIterator GstBufferListIterator; /** * GstBufferListDoFunction: - * @buffer: the #GstBuffer + * @buffer: (transfer full): the #GstBuffer * @user_data: user data * * A function for accessing the last buffer returned by @@ -56,8 +56,8 @@ typedef struct _GstBufferListIterator GstBufferListIterator; * unreffed. If NULL is returned, the buffer will be removed from the list. The * list must be writable. * - * Returns: the buffer to replace @buffer in the list, or NULL to remove @buffer - * from the list + * Returns: (transfer full): the buffer to replace @buffer in the list, or NULL + * to remove @buffer from the list * * Since: 0.10.24 */ @@ -125,7 +125,7 @@ GstBufferList *gst_buffer_list_new (void); * additional references to GstBufferList instances can potentially increase * the number of memcpy operations in a pipeline. * - * Returns: @list + * Returns: (transfer full): @list * * Since: 0.10.24 */ @@ -142,7 +142,7 @@ gst_buffer_list_ref (GstBufferList * list) /** * gst_buffer_list_unref: - * @list: a #GstBufferList + * @list: (transfer full): a #GstBufferList * * Decreases the refcount of the buffer list. If the refcount reaches 0, the * buffer list will be freed. @@ -168,7 +168,7 @@ gst_buffer_list_unref (GstBufferList * list) * allocated copy of the source list with copies of buffer pointers. The * refcount of buffers pointed to will be increased by one. * - * Returns: a new copy of @list. + * Returns: (transfer full): a new copy of @list. * * Since: 0.10.24 */ @@ -194,12 +194,15 @@ gst_buffer_list_copy (const GstBufferList * list) /** * gst_buffer_list_make_writable: - * @list: a #GstBufferList + * @list: (transfer full): a #GstBufferList * * Makes a writable buffer list from the given buffer list. If the source buffer * list is already writable, this will simply return the same buffer list. A * copy will otherwise be made using gst_buffer_list_copy(). * + * Returns: (transfer full): a writable list, which may or may not be the + * same as @list + * * Since: 0.10.24 */ #define gst_buffer_list_make_writable(list) GST_BUFFER_LIST_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (list))) diff --git a/gst/gstbus.c b/gst/gstbus.c index 284a40a1ea..a12bc866ed 100644 --- a/gst/gstbus.c +++ b/gst/gstbus.c @@ -265,7 +265,7 @@ gst_bus_set_main_context (GstBus * bus, GMainContext * ctx) * * Creates a new #GstBus instance. * - * Returns: a new #GstBus instance + * Returns: (transfer full): a new #GstBus instance */ GstBus * gst_bus_new (void) @@ -281,7 +281,7 @@ gst_bus_new (void) /** * gst_bus_post: * @bus: a #GstBus to post on - * @message: The #GstMessage to post + * @message: (transfer full): the #GstMessage to post * * Post a message on the given bus. Ownership of the message * is taken by the bus. @@ -468,10 +468,10 @@ gst_bus_set_flushing (GstBus * bus, gboolean flushing) * @timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a * matching message was posted on the bus. * - * Returns: a #GstMessage matching the filter in @types, or NULL if no matching - * message was found on the bus until the timeout expired. - * The message is taken from the bus and needs to be unreffed with - * gst_message_unref() after usage. + * Returns: (transfer full): a #GstMessage matching the filter in @types, + * or NULL if no matching message was found on the bus until the timeout + * expired. The message is taken from the bus and needs to be unreffed + * with gst_message_unref() after usage. * * MT safe. * @@ -558,8 +558,8 @@ beach: * #GST_CLOCK_TIME_NONE, this function will block forever until a message was * posted on the bus. * - * Returns: The #GstMessage that is on the bus after the specified timeout - * or NULL if the bus is empty after the timeout expired. + * Returns: (transfer full): the #GstMessage that is on the bus after the + * specified timeout or NULL if the bus is empty after the timeout expired. * The message is taken from the bus and needs to be unreffed with * gst_message_unref() after usage. * @@ -585,10 +585,10 @@ gst_bus_timed_pop (GstBus * bus, GstClockTime timeout) * message that does match @type. If there is no message matching @type on * the bus, all messages will be discarded. * - * Returns: The next #GstMessage matching @type that is on the bus, or NULL if - * the bus is empty or there is no message matching @type. - * The message is taken from the bus and needs to be unreffed with - * gst_message_unref() after usage. + * Returns: (transfer full): the next #GstMessage matching @type that is on + * the bus, or NULL if the bus is empty or there is no message matching + * @type. The message is taken from the bus and needs to be unreffed with + * gst_message_unref() after usage. * * MT safe. * @@ -609,9 +609,9 @@ gst_bus_pop_filtered (GstBus * bus, GstMessageType types) * * Get a message from the bus. * - * Returns: The #GstMessage that is on the bus, or NULL if the bus is empty. - * The message is taken from the bus and needs to be unreffed with - * gst_message_unref() after usage. + * Returns: (transfer full): the #GstMessage that is on the bus, or NULL if the + * bus is empty. The message is taken from the bus and needs to be unreffed + * with gst_message_unref() after usage. * * MT safe. */ @@ -631,7 +631,8 @@ gst_bus_pop (GstBus * bus) * on the bus' message queue. A reference is returned, and needs to be unreffed * by the caller. * - * Returns: The #GstMessage that is on the bus, or NULL if the bus is empty. + * Returns: (transfer full): the #GstMessage that is on the bus, or NULL if the + * bus is empty. * * MT safe. */ @@ -808,7 +809,7 @@ static GSourceFuncs gst_bus_source_funcs = { * a message is on the bus. After the GSource is dispatched, the * message is popped off the bus and unreffed. * - * Returns: A #GSource that can be added to a mainloop. + * Returns: (transfer full): a #GSource that can be added to a mainloop. */ GSource * gst_bus_create_watch (GstBus * bus) @@ -1025,9 +1026,9 @@ poll_destroy_timeout (GstBusPollData * poll_data) * better handled by setting up an asynchronous bus watch and doing things * from there. * - * Returns: The message that was received, or NULL if the poll timed out. - * The message is taken from the bus and needs to be unreffed with - * gst_message_unref() after usage. + * Returns: (transfer full): the message that was received, or NULL if the + * poll timed out. The message is taken from the bus and needs to be + * unreffed with gst_message_unref() after usage. */ GstMessage * gst_bus_poll (GstBus * bus, GstMessageType events, GstClockTimeDiff timeout) diff --git a/gst/gstcaps.c b/gst/gstcaps.c index 822a6b0bdd..edd366536c 100644 --- a/gst/gstcaps.c +++ b/gst/gstcaps.c @@ -157,7 +157,7 @@ gst_caps_get_type (void) * #GstCaps contains no media formats. * Caller is responsible for unreffing the returned caps. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_new_empty (void) @@ -187,7 +187,7 @@ gst_caps_new_empty (void) * Creates a new #GstCaps that indicates that it is compatible with * any media format. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_new_any (void) @@ -210,7 +210,7 @@ gst_caps_new_any (void) * as gst_structure_new(). * Caller is responsible for unreffing the returned caps. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_new_simple (const char *media_type, const char *fieldname, ...) @@ -239,7 +239,7 @@ gst_caps_new_simple (const char *media_type, const char *fieldname, ...) * arguments. The list must be NULL-terminated. The structures * are not copied; the returned #GstCaps owns the structures. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_new_full (GstStructure * struct1, ...) @@ -263,7 +263,7 @@ gst_caps_new_full (GstStructure * struct1, ...) * arguments. The list must be NULL-terminated. The structures * are not copied; the returned #GstCaps owns the structures. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_new_full_valist (GstStructure * structure, va_list var_args) @@ -293,7 +293,7 @@ gst_caps_new_full_valist (GstStructure * structure, va_list var_args) * * When you are finished with the caps, call gst_caps_unref() on it. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_copy (const GstCaps * caps) @@ -346,7 +346,7 @@ _gst_caps_free (GstCaps * caps) /** * gst_caps_make_writable: - * @caps: the #GstCaps to make writable + * @caps: (transfer full): the #GstCaps to make writable * * Returns a writable copy of @caps. * @@ -360,7 +360,7 @@ _gst_caps_free (GstCaps * caps) * that it returns. Don't access the argument after calling this function. See * also: gst_caps_ref(). * - * Returns: the same #GstCaps object. + * Returns: (transfer full): the same #GstCaps object. */ GstCaps * gst_caps_make_writable (GstCaps * caps) @@ -394,7 +394,7 @@ gst_caps_make_writable (GstCaps * caps) * implicitly by e.g. gst_caps_new_simple(), or via taking one explicitly with * this function. * - * Returns: the same #GstCaps object. + * Returns: (transfer full): the same #GstCaps object. */ GstCaps * gst_caps_ref (GstCaps * caps) @@ -414,7 +414,7 @@ gst_caps_ref (GstCaps * caps) /** * gst_caps_unref: - * @caps: the #GstCaps to unref + * @caps: (transfer full): the #GstCaps to unref * * Unref a #GstCaps and and free all its structures and the * structures' values when the refcount reaches 0. @@ -454,9 +454,9 @@ gst_static_caps_get_type (void) * * Converts a #GstStaticCaps to a #GstCaps. * - * Returns: A pointer to the #GstCaps. Unref after usage. Since the - * core holds an additional ref to the returned caps, - * use gst_caps_make_writable() on the returned caps to modify it. + * Returns: (transfer full): a pointer to the #GstCaps. Unref after usage. + * Since the core holds an additional ref to the returned caps, + * use gst_caps_make_writable() on the returned caps to modify it. */ GstCaps * gst_static_caps_get (GstStaticCaps * static_caps) @@ -545,7 +545,8 @@ gst_caps_remove_and_get_structure (GstCaps * caps, guint idx) * Retrieves the stucture with the given index from the list of structures * contained in @caps. The caller becomes the owner of the returned structure. * - * Returns: a pointer to the #GstStructure corresponding to @index. + * Returns: (transfer full): a pointer to the #GstStructure corresponding + * to @index. * * Since: 0.10.30 */ @@ -640,7 +641,7 @@ gst_caps_structure_is_subset (const GstStructure * minuend, /** * gst_caps_append: * @caps1: the #GstCaps that will be appended to - * @caps2: the #GstCaps to append + * @caps2: (transfer full): the #GstCaps to append * * Appends the structures contained in @caps2 to @caps1. The structures in * @caps2 are not copied -- they are transferred to @caps1, and then @caps2 is @@ -679,7 +680,7 @@ gst_caps_append (GstCaps * caps1, GstCaps * caps2) /** * gst_caps_merge: * @caps1: the #GstCaps that will take the new entries - * @caps2: the #GstCaps to merge in + * @caps2: (transfer full): the #GstCaps to merge in * * Appends the structures contained in @caps2 to @caps1 if they are not yet * expressed by @caps1. The structures in @caps2 are not copied -- they are @@ -734,7 +735,7 @@ gst_caps_merge (GstCaps * caps1, GstCaps * caps2) /** * gst_caps_append_structure: * @caps: the #GstCaps that will be appended to - * @structure: the #GstStructure to append + * @structure: (transfer full): the #GstStructure to append * * Appends @structure to @caps. The structure is not copied; @caps * becomes the owner of @structure. @@ -780,7 +781,7 @@ gst_caps_remove_structure (GstCaps * caps, guint idx) /** * gst_caps_merge_structure: * @caps: the #GstCaps that will the the new structure - * @structure: the #GstStructure to merge + * @structure: (transfer full): the #GstStructure to merge * * Appends @structure to @caps if its not already expressed by @caps. The * structure is not copied; @caps becomes the owner of @structure. @@ -855,7 +856,8 @@ gst_caps_get_size (const GstCaps * caps) * You do not need to free or unref the structure returned, it * belongs to the #GstCaps. * - * Returns: a pointer to the #GstStructure corresponding to @index + * Returns: (transfer none): a pointer to the #GstStructure corresponding + * to @index */ GstStructure * gst_caps_get_structure (const GstCaps * caps, guint index) @@ -874,7 +876,7 @@ gst_caps_get_structure (const GstCaps * caps, guint index) * Creates a new #GstCaps and appends a copy of the nth structure * contained in @caps. * - * Returns: the new #GstCaps + * Returns: (transfer full): the new #GstCaps */ GstCaps * gst_caps_copy_nth (const GstCaps * caps, guint nth) @@ -2005,7 +2007,7 @@ gst_caps_load_thyself (xmlNodePtr parent) /** * gst_caps_replace: - * @caps: a pointer to #GstCaps + * @caps: (inout) (transfer full): a pointer to #GstCaps * @newcaps: a #GstCaps to replace *caps * * Replaces *caps with @newcaps. Unrefs the #GstCaps in the location @@ -2050,7 +2052,7 @@ gst_caps_replace (GstCaps ** caps, GstCaps * newcaps) * ]| * This prints the caps in human readble form. * - * Returns: a newly allocated string representing @caps. + * Returns: (transfer full): a newly allocated string representing @caps. */ gchar * gst_caps_to_string (const GstCaps * caps) @@ -2146,7 +2148,7 @@ gst_caps_from_string_inplace (GstCaps * caps, const gchar * string) * * Converts @caps from a string representation. * - * Returns: a newly allocated #GstCaps + * Returns: (transfer full): a newly allocated #GstCaps */ GstCaps * gst_caps_from_string (const gchar * string) diff --git a/gst/gstchildproxy.c b/gst/gstchildproxy.c index 13aa71b809..65e9527a4d 100644 --- a/gst/gstchildproxy.c +++ b/gst/gstchildproxy.c @@ -71,7 +71,8 @@ static guint signals[LAST_SIGNAL] = { 0 }; * * Implementors can use #GstObject together with gst_object_get_name() * - * Returns: the child object or %NULL if not found. Unref after usage. + * Returns: (transfer full): the child object or %NULL if not found. Unref + * after usage. * * MT safe. */ @@ -120,8 +121,8 @@ gst_child_proxy_get_child_by_name (GstChildProxy * parent, const gchar * name) * * Fetches a child by its number. * - * Returns: the child object or %NULL if not found (index too high). Unref - * after usage. + * Returns: (transfer full): the child object or %NULL if not found (index + * too high). Unref after usage. * * MT safe. */ @@ -156,8 +157,10 @@ gst_child_proxy_get_children_count (GstChildProxy * parent) * gst_child_proxy_lookup: * @object: object to lookup the property in * @name: name of the property to look up - * @target: pointer to a #GstObject that takes the real object to set property on - * @pspec: pointer to take the #GParamSpec describing the property + * @target: (out) (allow-none) (transfer full): pointer to a #GstObject that + * takes the real object to set property on + * @pspec: (out) (allow-none) (transfer full): pointer to take the #GParamSpec + * describing the property * * Looks up which object and #GParamSpec would be effected by the given @name. * @@ -223,7 +226,7 @@ gst_child_proxy_lookup (GstObject * object, const gchar * name, * gst_child_proxy_get_property: * @object: object to query * @name: name of the property - * @value: a #GValue that should take the result. + * @value: (out caller-allocates): a #GValue that should take the result. * * Gets a single property using the GstChildProxy mechanism. * You are responsible for for freeing it by calling g_value_unset() diff --git a/gst/gstclock.c b/gst/gstclock.c index 91ae04f14e..125998bc4f 100644 --- a/gst/gstclock.c +++ b/gst/gstclock.c @@ -254,7 +254,7 @@ gst_clock_single_shot_id_reinit (GstClock * clock, GstClockID id, * * Increase the refcount of given @id. * - * Returns: The same #GstClockID with increased refcount. + * Returns: (transfer full): The same #GstClockID with increased refcount. * * MT safe. */ @@ -287,7 +287,7 @@ _gst_clock_id_free (GstClockID id) /** * gst_clock_id_unref: - * @id: The #GstClockID to unref + * @id: (transfer full): The #GstClockID to unref * * Unref given @id. When the refcount reaches 0 the * #GstClockID will be freed. @@ -317,7 +317,10 @@ gst_clock_id_unref (GstClockID id) * notification at the requested time. The single shot id should be * unreffed after usage. * - * Returns: A #GstClockID that can be used to request the time notification. + * Free-function: gst_clock_id_unref + * + * Returns: (transfer full): a #GstClockID that can be used to request the + * time notification. * * MT safe. */ @@ -341,7 +344,10 @@ gst_clock_new_single_shot_id (GstClock * clock, GstClockTime time) * will then be fired with the given @interval. @id should be unreffed * after usage. * - * Returns: A #GstClockID that can be used to request the time notification. + * Free-function: gst_clock_id_unref + * + * Returns: (transfer full): a #GstClockID that can be used to request the + * time notification. * * MT safe. */ @@ -408,7 +414,8 @@ gst_clock_id_get_time (GstClockID id) /** * gst_clock_id_wait * @id: The #GstClockID to wait on - * @jitter: A pointer that will contain the jitter, can be %NULL. + * @jitter (out) (allow-none): a pointer that will contain the jitter, + * can be %NULL. * * Perform a blocking wait on @id. * @id should have been created with gst_clock_new_single_shot_id() @@ -1027,10 +1034,10 @@ gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime /** * gst_clock_get_calibration * @clock: a #GstClock - * @internal: a location to store the internal time - * @external: a location to store the external time - * @rate_num: a location to store the rate numerator - * @rate_denom: a location to store the rate denominator + * @internal: (out) (allow-none): a location to store the internal time + * @external: (out) (allow-none): a location to store the external time + * @rate_num: (out) (allow-none): a location to store the rate numerator + * @rate_denom: (out) (allow-none): a location to store the rate denominator * * Gets the internal rate and reference time of @clock. See * gst_clock_set_calibration() for more information. @@ -1088,7 +1095,7 @@ gst_clock_slave_callback (GstClock * master, GstClockTime time, /** * gst_clock_set_master * @clock: a #GstClock - * @master: a master #GstClock + * @master: (allow-none): a master #GstClock * * Set @master as the master clock for @clock. @clock will be automatically * calibrated so that gst_clock_get_time() reports the same time as the @@ -1166,8 +1173,8 @@ not_supported: * Get the master clock that @clock is slaved to or %NULL when the clock is * not slaved to any master clock. * - * Returns: a master #GstClock or %NULL when this clock is not slaved to a - * master clock. Unref after usage. + * Returns: (transfer full): a master #GstClock or %NULL when this clock is + * not slaved to a master clock. Unref after usage. * * MT safe. */ @@ -1314,7 +1321,7 @@ invalid: * @clock: a #GstClock * @slave: a time on the slave * @master: a time on the master - * @r_squared: a pointer to hold the result + * @r_squared: (out): a pointer to hold the result * * The time @master of the master clock and the time @slave of the slave * clock are added to the list of observations. If enough observations diff --git a/gst/gstdatetime.c b/gst/gstdatetime.c index acb820909e..40596dfc6d 100644 --- a/gst/gstdatetime.c +++ b/gst/gstdatetime.c @@ -152,7 +152,9 @@ * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by * @secs. The #GstDateTime is in the local timezone. * - * Return value: the newly created #GstDateTime + * Free-function: gst_date_time_unref + * + * Return value: (transfer full): the newly created #GstDateTime * * Since: 0.10.31 */ @@ -164,7 +166,9 @@ * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by * @secs. The #GstDateTime is in the UTC timezone. * - * Return value: the newly created #GstDateTime + * Free-function: gst_date_time_unref + * + * Return value: (transfer full): the newly created #GstDateTime * * Since: 0.10.31 */ @@ -186,7 +190,9 @@ * 1 to 31, @hour from 0 to 23, @minutes and @seconds from 0 to 59 and * @microsecond from 0 to 999999. * - * Return value: the newly created #GstDateTime + * Free-function: gst_date_time_unref + * + * Return value: (transfer full): the newly created #GstDateTime * * Since: 0.10.31 */ @@ -213,7 +219,9 @@ * some fractional timezones, while it still keeps the readability of * represeting it in hours for most timezones. * - * Return value: the newly created #GstDateTime + * Free-function: gst_date_time_unref + * + * Return value: (transfer full): the newly created #GstDateTime * * Since: 0.10.31 */ @@ -223,8 +231,10 @@ * * Creates a new #GstDateTime representing the current date and time. * - * Return value: the newly created #GstDateTime which should be freed with - * gst_date_time_unref(). + * Free-function: gst_date_time_unref + * + * Return value: (transfer full): the newly created #GstDateTime which should + * be freed with gst_date_time_unref(). * * Since: 0.10.31 */ @@ -235,8 +245,10 @@ * Creates a new #GstDateTime that represents the current instant at Universal * coordinated time. * - * Return value: the newly created #GstDateTime which should be freed with - * gst_date_time_unref(). + * Free-function: gst_date_time_unref + * + * Return value: (transfer full): the newly created #GstDateTime which should + * be freed with gst_date_time_unref(). * * Since: 0.10.31 */ @@ -767,7 +779,7 @@ gst_date_time_free (GstDateTime * datetime) * * Atomically increments the reference count of @datetime by one. * - * Return value: the reference @datetime + * Return value: (transfer full): the reference @datetime * * Since: 0.10.31 */ @@ -782,7 +794,7 @@ gst_date_time_ref (GstDateTime * datetime) /** * gst_date_time_unref: - * @datetime: a #GstDateTime + * @datetime: (transfer full): a #GstDateTime * * Atomically decrements the reference count of @datetime by one. When the * reference count reaches zero, the structure is freed. diff --git a/gst/gstelement.c b/gst/gstelement.c index 49e8b0b4ac..a290581a93 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -630,7 +630,7 @@ gst_element_is_indexable (GstElement * element) /** * gst_element_set_index: * @element: a #GstElement. - * @index: a #GstIndex. + * @index: (transfer none): a #GstIndex. * * Set @index on the element. The refcount of the index * will be increased, any previously set index is unreffed. @@ -657,7 +657,7 @@ gst_element_set_index (GstElement * element, GstIndex * index) * * Gets the index from the element. * - * Returns: a #GstIndex or %NULL when no index was set on the + * Returns: (transfer full): a #GstIndex or %NULL when no index was set on the * element. unref after usage. * * MT safe. @@ -681,7 +681,7 @@ gst_element_get_index (GstElement * element) /** * gst_element_add_pad: * @element: a #GstElement to add the pad to. - * @pad: the #GstPad to add to the element. + * @pad: (transfer full): the #GstPad to add to the element. * * Adds a pad (link point) to @element. @pad's parent will be set to @element; * see gst_object_set_parent() for refcounting information. @@ -797,7 +797,7 @@ no_direction: /** * gst_element_remove_pad: * @element: a #GstElement to remove pad from. - * @pad: the #GstPad to remove from the element. + * @pad: (transfer none): the #GstPad to remove from the element. * * Removes @pad from @element. @pad will be destroyed if it has not been * referenced elsewhere using gst_object_unparent(). @@ -933,8 +933,8 @@ pad_compare_name (GstPad * pad1, const gchar * name) * Retrieves a pad from @element by name. This version only retrieves * already-existing (i.e. 'static') pads. * - * Returns: the requested #GstPad if found, otherwise %NULL. unref after - * usage. + * Returns: (transfer full): the requested #GstPad if found, otherwise %NULL. + * unref after usage. * * MT safe. */ @@ -994,7 +994,8 @@ gst_element_request_pad (GstElement * element, GstPadTemplate * templ, * request pads. The pad should be released with * gst_element_release_request_pad(). * - * Returns: requested #GstPad if found, otherwise %NULL. Release after usage. + * Returns: (transfer full): requested #GstPad if found, otherwise %NULL. + * Release after usage. */ GstPad * gst_element_get_request_pad (GstElement * element, const gchar * name) @@ -1141,7 +1142,8 @@ gst_element_iterate_pad_list (GstElement * element, GList ** padlist) * Retrieves an iterattor of @element's pads. The iterator should * be freed after usage. * - * Returns: the #GstIterator of #GstPad. Unref each pad after use. + * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad + * after use. * * MT safe. */ @@ -1159,7 +1161,8 @@ gst_element_iterate_pads (GstElement * element) * * Retrieves an iterator of @element's source pads. * - * Returns: the #GstIterator of #GstPad. Unref each pad after use. + * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad + * after use. * * MT safe. */ @@ -1177,7 +1180,8 @@ gst_element_iterate_src_pads (GstElement * element) * * Retrieves an iterator of @element's sink pads. * - * Returns: the #GstIterator of #GstPad. Unref each pad after use. + * Returns: (transfer full): the #GstIterator of #GstPad. Unref each pad + * after use. * * MT safe. */ @@ -1192,7 +1196,7 @@ gst_element_iterate_sink_pads (GstElement * element) /** * gst_element_class_add_pad_template: * @klass: the #GstElementClass to add the pad template to. - * @templ: a #GstPadTemplate to add to the element class. + * @templ: (transfer none): a #GstPadTemplate to add to the element class. * * Adds a padtemplate to an element class. This is mainly used in the _base_init * functions of classes. @@ -1345,7 +1349,8 @@ gst_element_class_set_details_simple (GstElementClass * klass, * that has subclasses, make sure to pass the g_class parameter of the * #GInstanceInitFunc here.</note> * - * Returns: the #GList of padtemplates. + * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of + * pad templates. */ GList * gst_element_class_get_pad_template_list (GstElementClass * element_class) @@ -1365,8 +1370,8 @@ gst_element_class_get_pad_template_list (GstElementClass * element_class) * that has subclasses, make sure to pass the g_class parameter of the * #GInstanceInitFunc here.</note> * - * Returns: the #GstPadTemplate with the given name, or %NULL if none was found. - * No unreferencing is necessary. + * Returns: (transfer none): the #GstPadTemplate with the given name, or %NULL + * if none was found. No unreferencing is necessary. */ GstPadTemplate * gst_element_class_get_pad_template (GstElementClass * element_class, @@ -1495,7 +1500,7 @@ gst_element_default_send_event (GstElement * element, GstEvent * event) /** * gst_element_send_event: * @element: a #GstElement to send the event to. - * @event: the #GstEvent to send to the element. + * @event: (transfer full): the #GstEvent to send to the element. * * Sends an event to an element. If the element doesn't implement an * event handler, the event will be pushed on a random linked sink pad for @@ -1640,7 +1645,7 @@ gst_element_default_query (GstElement * element, GstQuery * query) /** * gst_element_query: * @element: a #GstElement to perform the query on. - * @query: the #GstQuery. + * @query: (transfer none): the #GstQuery. * * Performs a query on the given element. * @@ -1678,7 +1683,7 @@ gst_element_query (GstElement * element, GstQuery * query) /** * gst_element_post_message: * @element: a #GstElement posting the message - * @message: a #GstMessage to post + * @message: (transfer full): a #GstMessage to post * * Post a message on the element's #GstBus. This function takes ownership of the * message; if you want to access the message after this call, you should add an @@ -1731,7 +1736,8 @@ no_bus: * * 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 "" + * Returns: (transfer full): a newly allocated string, or %NULL if the format + * was %NULL or "" * * MT safe. */ @@ -1758,10 +1764,12 @@ _gst_element_error_printf (const gchar * format, ...) * @type: the #GstMessageType * @domain: the GStreamer GError domain this message belongs to * @code: the GError code belonging to the domain - * @text: an allocated text string to be used as a replacement for the - * default message connected to code, or %NULL - * @debug: an allocated debug message to be used as a replacement for the - * default debugging information, or %NULL + * @text: (allow-none) (transfer full): an allocated text string to be used + * as a replacement for the default message connected to code, + * or %NULL + * @debug: (allow-none) (transfer full): an allocated debug message to be + * used as a replacement for the default debugging information, + * or %NULL * @file: the source code file where the error was generated * @function: the source code function where the error was generated * @line: the source code line where the error was generated @@ -2100,9 +2108,10 @@ interrupted: /** * gst_element_get_state: * @element: a #GstElement to get the state of. - * @state: (out): a pointer to #GstState to hold the state. Can be %NULL. - * @pending: (out): a pointer to #GstState to hold the pending state. - * Can be %NULL. + * @state: (out) (allow-none): a pointer to #GstState to hold the state. + * Can be %NULL. + * @pending: (out) (allow-none): a pointer to #GstState to hold the pending + * state. Can be %NULL. * @timeout: a #GstClockTime to specify the timeout for an async * state change or %GST_CLOCK_TIME_NONE for infinite timeout. * @@ -2888,8 +2897,8 @@ was_ok: * * Retrieves the factory that was used to create this element. * - * Returns: the #GstElementFactory used for creating this element. - * no refcounting is needed. + * Returns: (transfer none): the #GstElementFactory used for creating this + * element. no refcounting is needed. */ GstElementFactory * gst_element_get_factory (GstElement * element) @@ -3137,7 +3146,7 @@ gst_element_set_bus_func (GstElement * element, GstBus * bus) /** * gst_element_set_bus: * @element: a #GstElement to set the bus of. - * @bus: the #GstBus to set. + * @bus: (transfer none): the #GstBus to set. * * Sets the bus of the element. Increases the refcount on the bus. * For internal use only, unless you're testing elements. @@ -3164,7 +3173,7 @@ gst_element_set_bus (GstElement * element, GstBus * bus) * Returns the bus of the element. Note that only a #GstPipeline will provide a * bus for the application. * - * Returns: the element's #GstBus. unref after usage. + * Returns: (transfer full): the element's #GstBus. unref after usage. * * MT safe. */ diff --git a/gst/gstelement.h b/gst/gstelement.h index 440350cfc7..62892d6683 100644 --- a/gst/gstelement.h +++ b/gst/gstelement.h @@ -696,7 +696,7 @@ GType gst_element_get_type (void); * For a nameless element, this returns NULL, which you can safely g_free() * as well. * - * Returns: the name of @elem. g_free() after usage. MT safe. + * Returns: (transfer full): the name of @elem. g_free() after usage. MT safe. * */ #define gst_element_get_name(elem) gst_object_get_name(GST_OBJECT_CAST(elem)) @@ -714,7 +714,7 @@ GType gst_element_get_type (void); * gst_element_get_parent: * @elem: a #GstElement to get the parent of. * - * Gets the parent of an element. + * Returns: (transfer full): the parent of an element. */ #define gst_element_get_parent(elem) gst_object_get_parent(GST_OBJECT_CAST(elem)) diff --git a/gst/gstelementfactory.c b/gst/gstelementfactory.c index 6e197f3a7f..31b74b0f93 100644 --- a/gst/gstelementfactory.c +++ b/gst/gstelementfactory.c @@ -125,7 +125,7 @@ gst_element_factory_finalize (GObject * object) * Search for an element factory of the given name. Refs the returned * element factory; caller is responsible for unreffing. * - * Returns: #GstElementFactory if found, NULL otherwise + * Returns: (transfer full): #GstElementFactory if found, NULL otherwise */ GstElementFactory * gst_element_factory_find (const gchar * name) @@ -193,8 +193,9 @@ gst_element_factory_cleanup (GstElementFactory * factory) /** * gst_element_register: - * @plugin: #GstPlugin to register the element with, or NULL for a static - * element (note that passing NULL only works in GStreamer 0.10.13 and later) + * @plugin: (allow-none): #GstPlugin to register the element with, or NULL for + * a static element (note that passing NULL only works in GStreamer 0.10.13 + * and later) * @name: name of elements of this type * @rank: rank of element (higher rank means more importance when autoplugging) * @type: GType of element to register @@ -342,7 +343,8 @@ detailserror: * It will be given the name supplied, since all elements require a name as * their first argument. * - * Returns: new #GstElement or NULL if the element couldn't be created + * Returns: (transfer full): new #GstElement or NULL if the element couldn't + * be created */ GstElement * gst_element_factory_create (GstElementFactory * factory, const gchar * name) @@ -427,7 +429,7 @@ no_element: * consisting of the element factory name and a number. * If name is given, it will be given the name supplied. * - * Returns: new #GstElement or NULL if unable to create element + * Returns: (transfer full): new #GstElement or NULL if unable to create element */ GstElement * gst_element_factory_make (const gchar * factoryname, const gchar * name) @@ -650,7 +652,8 @@ __gst_element_factory_add_interface (GstElementFactory * elementfactory, * * Gets the #GList of #GstStaticPadTemplate for this factory. * - * Returns: the padtemplates + * Returns: (transfer none) (element-type Gst.StaticPadTemplate): the + * static pad templates */ G_CONST_RETURN GList * gst_element_factory_get_static_pad_templates (GstElementFactory * factory) @@ -685,7 +688,8 @@ gst_element_factory_get_uri_type (GstElementFactory * factory) * array, as it is still owned by the element factory. Use g_strdupv() to * make a copy of the protocol string array if you need to. * - * Returns: the supported protocols or NULL + * Returns: (transfer none) (array zero-terminated=1): the supported protocols + * or NULL */ gchar ** gst_element_factory_get_uri_protocols (GstElementFactory * factory) @@ -826,8 +830,9 @@ element_filter (GstPluginFeature * feature, FilterData * data) * with a rank greater or equal to @minrank will be returned. * The list of factories is returned by decreasing rank. * - * Returns: a #GList of #GstElementFactory elements. Use - * gst_plugin_feature_list_free() after usage. + * Returns: (transfer full) (element-type Gst.ElementFactory): a #GList of + * #GstElementFactory elements. Use gst_plugin_feature_list_free() after + * usage. * * Since: 0.10.31 */ @@ -854,7 +859,8 @@ gst_element_factory_list_get_elements (GstElementFactoryListType type, /** * gst_element_factory_list_filter: - * @list: a #GList of #GstElementFactory to filter + * @list: (transfer none) (element-type Gst.ElementFactory): a #GList of + * #GstElementFactory to filter * @caps: a #GstCaps * @direction: a #GstPadDirection to filter on * @subsetonly: whether to filter on caps subsets or not. @@ -866,8 +872,9 @@ gst_element_factory_list_get_elements (GstElementFactoryListType type, * are a complete superset of @caps will be returned. Else any element * whose pad templates caps can intersect with @caps will be returned. * - * Returns: a #GList of #GstElementFactory elements that match the - * given requisits. Use #gst_plugin_feature_list_free after usage. + * Returns: (transfer full) (element-type Gst.ElementFactory): a #GList of + * #GstElementFactory elements that match the given requisits. + * Use #gst_plugin_feature_list_free after usage. * * Since: 0.10.31 */ diff --git a/gst/gsterror.c b/gst/gsterror.c index c683e47071..a9b13ff1d4 100644 --- a/gst/gsterror.c +++ b/gst/gsterror.c @@ -300,8 +300,8 @@ QUARK_FUNC (stream); * * Get a string describing the error message in the current locale. * - * Returns: a newly allocated string describing the error message in the - * current locale. + * Returns: (transfer full) (type gchar*): a newly allocated string describing + * the error message in the current locale. */ gchar * gst_error_get_message (GQuark domain, gint code) diff --git a/gst/gstevent.c b/gst/gstevent.c index c69e3b3440..6d2cc8bc2f 100644 --- a/gst/gstevent.c +++ b/gst/gstevent.c @@ -279,8 +279,8 @@ gst_event_new (GstEventType type) /** * gst_event_new_custom: * @type: The type of the new event - * @structure: The structure for the event. The event will take ownership of - * the structure. + * @structure: (transfer full): the structure for the event. The event will + * take ownership of the structure. * * Create a new custom-typed event. This can be used for anything not * handled by other event-specific functions to pass an event to another @@ -293,7 +293,7 @@ gst_event_new (GstEventType type) * New custom events can also be created by subclassing the event type if * needed. * - * Returns: The new custom event. + * Returns: (transfer full): the new custom event. */ GstEvent * gst_event_new_custom (GstEventType type, GstStructure * structure) @@ -431,7 +431,7 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum) * This event is typically generated after a seek to flush out all queued data * in the pipeline so that the new media is played as soon as possible. * - * Returns: A new flush start event. + * Returns: (transfer full): a new flush start event. */ GstEvent * gst_event_new_flush_start (void) @@ -453,7 +453,7 @@ gst_event_new_flush_start (void) * This event is typically generated to complete a seek and to resume * dataflow. * - * Returns: A new flush stop event. + * Returns: (transfer full): a new flush stop event. */ GstEvent * gst_event_new_flush_stop (void) @@ -478,7 +478,7 @@ gst_event_new_flush_stop (void) * * The EOS event itself will not cause any state transitions of the pipeline. * - * Returns: The new EOS event. + * Returns: (transfer full): the new EOS event. */ GstEvent * gst_event_new_eos (void) @@ -500,7 +500,7 @@ gst_event_new_eos (void) * This method calls gst_event_new_new_segment_full() passing a default * value of 1.0 for applied_rate * - * Returns: A new newsegment event. + * Returns: (transfer full): a new newsegment event. */ GstEvent * gst_event_new_new_segment (gboolean update, gdouble rate, GstFormat format, @@ -575,7 +575,7 @@ gst_event_parse_new_segment (GstEvent * event, gboolean * update, * * position + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate) * - * Returns: A new newsegment event. + * Returns: (transfer full): a new newsegment event. * * Since: 0.10.6 */ @@ -687,7 +687,7 @@ gst_event_parse_new_segment_full (GstEvent * event, gboolean * update, * * Generates a metadata tag event from the given @taglist. * - * Returns: a new #GstEvent + * Returns: (transfer full): a new #GstEvent */ GstEvent * gst_event_new_tag (GstTagList * taglist) @@ -700,7 +700,7 @@ gst_event_new_tag (GstTagList * taglist) /** * gst_event_parse_tag: * @event: a tag event - * @taglist: (out): pointer to metadata list + * @taglist: (out) (transfer none): pointer to metadata list * * Parses a tag @event and stores the results in the given @taglist location. */ @@ -727,7 +727,7 @@ gst_event_parse_tag (GstEvent * event, GstTagList ** taglist) * * When the @async flag is set, a thread boundary is prefered. * - * Returns: a new #GstEvent + * Returns: (transfer full): a new #GstEvent */ GstEvent * gst_event_new_buffer_size (GstFormat format, gint64 minsize, @@ -829,7 +829,7 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format, * The application can use general event probes to intercept the QoS * event and implement custom application specific QoS handling. * - * Returns: A new QOS event. + * Returns: (transfer full): a new QOS event. */ GstEvent * gst_event_new_qos (gdouble proportion, GstClockTimeDiff diff, @@ -931,7 +931,7 @@ gst_event_parse_qos (GstEvent * event, gdouble * proportion, * #GST_QUERY_POSITION and update the playback segment current position with a * #GST_SEEK_TYPE_SET to the desired position. * - * Returns: A new seek event. + * Returns: (transfer full): a new seek event. */ GstEvent * gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags, @@ -1027,12 +1027,12 @@ gst_event_parse_seek (GstEvent * event, gdouble * rate, /** * gst_event_new_navigation: - * @structure: description of the event. The event will take ownership of the - * structure. + * @structure: (transfer full): description of the event. The event will take + * ownership of the structure. * * Create a new navigation event from the given description. * - * Returns: a new #GstEvent + * Returns: (transfer full): a new #GstEvent */ GstEvent * gst_event_new_navigation (GstStructure * structure) @@ -1053,7 +1053,7 @@ gst_event_new_navigation (GstStructure * structure) * The latency is mostly used in live sinks and is always expressed in * the time format. * - * Returns: a new #GstEvent + * Returns: (transfer full): a new #GstEvent * * Since: 0.10.12 */ @@ -1115,7 +1115,7 @@ gst_event_parse_latency (GstEvent * event, GstClockTime * latency) * The @intermediate flag instructs the pipeline that this step operation is * part of a larger step operation. * - * Returns: a new #GstEvent + * Returns: (transfer full): a new #GstEvent * * Since: 0.10.24 */ @@ -1144,11 +1144,12 @@ gst_event_new_step (GstFormat format, guint64 amount, gdouble rate, /** * gst_event_parse_step: * @event: The event to query - * @format: (out): A pointer to store the format in. - * @amount: (out): A pointer to store the amount in. - * @rate: (out): A pointer to store the rate in. - * @flush: (out): A pointer to store the flush boolean in. - * @intermediate: (out): A pointer to store the intermediate boolean in. + * @format: (out) (allow-none): a pointer to store the format in + * @amount: (out) (allow-none): a pointer to store the amount in + * @rate: (out) (allow-none): a pointer to store the rate in + * @flush: (out) (allow-none): a pointer to store the flush boolean in + * @intermediate: (out) (allow-none): a pointer to store the intermediate + * boolean in * * Parse the step event. * @@ -1183,13 +1184,13 @@ gst_event_parse_step (GstEvent * event, GstFormat * format, guint64 * amount, /** * gst_event_new_sink_message: - * @msg: The #GstMessage to be posted + * @msg: (transfer none): the #GstMessage to be posted * * Create a new sink-message event. The purpose of the sink-message event is * to instruct a sink to post the message contained in the event synchronized * with the stream. * - * Returns: a new #GstEvent + * Returns: (transfer full): a new #GstEvent * * Since: 0.10.26 */ @@ -1213,7 +1214,7 @@ gst_event_new_sink_message (GstMessage * msg) /** * gst_event_parse_sink_message: * @event: The event to query - * @msg: (out): A pointer to store the #GstMessage in. + * @msg: (out) (transfer full): a pointer to store the #GstMessage in. * * Parse the sink-message event. Unref @msg after usage. * diff --git a/gst/gstevent.h b/gst/gstevent.h index 7ee460d533..9568514866 100644 --- a/gst/gstevent.h +++ b/gst/gstevent.h @@ -224,9 +224,10 @@ typedef struct _GstEventClass GstEventClass; /** * gst_event_replace: - * @old_event: pointer to a pointer to a #GstEvent to be replaced. - * @new_event: pointer to a #GstEvent that will replace the event pointed to - * by @old_event. + * @old_event: (inout) (transfer full): pointer to a pointer to a #GstEvent + * to be replaced. + * @new_event: (allow-none) (transfer none): pointer to a #GstEvent that will + * replace the event pointed to by @old_event. * * Modifies a pointer to a #GstEvent to point to a different #GstEvent. The * modification is done atomically (so this is useful for ensuring thread safety @@ -356,7 +357,7 @@ GType gst_event_get_type (void); * * Increase the refcount of this event. * - * Returns: @event (for convenience when doing assignments) + * Returns: (transfer full): @event (for convenience when doing assignments) */ #ifdef _FOOL_GTK_DOC_ G_INLINE_FUNC GstEvent * gst_event_ref (GstEvent * event); @@ -370,7 +371,7 @@ gst_event_ref (GstEvent * event) /** * gst_event_unref: - * @event: The event to refcount + * @event: (transfer full): the event to refcount * * Decrease the refcount of an event, freeing it if the refcount reaches 0. */ @@ -391,7 +392,7 @@ gst_event_unref (GstEvent * event) * * Copy the event using the event specific copy function. * - * Returns: the new event + * Returns: (transfer full): the new event */ #ifdef _FOOL_GTK_DOC_ G_INLINE_FUNC GstEvent * gst_event_copy (const GstEvent * event); diff --git a/gst/gstfilter.c b/gst/gstfilter.c index 42ff87a6a4..a0eb7e5984 100644 --- a/gst/gstfilter.c +++ b/gst/gstfilter.c @@ -56,9 +56,9 @@ * @data wil be made in any other way when prepending @data to the list of * results. * - * Returns: the list of results. Free with g_list_free() when no longer needed - * (the data contained in the list is a flat copy and does need to be - * unreferenced or freed). + * Returns: (transfer container): the list of results. Free with g_list_free() + * when no longer needed (the data contained in the list is a flat copy + * and does need to be unreferenced or freed). */ GList * gst_filter_run (const GList * list, GstFilterFunc func, gboolean first, diff --git a/gst/gstfilter.h b/gst/gstfilter.h index c52de151ae..1728f000ea 100644 --- a/gst/gstfilter.h +++ b/gst/gstfilter.h @@ -29,7 +29,7 @@ G_BEGIN_DECLS * @obj: the object * @user_data: filter data * - * Function prototype for a filter callback taht can be use in gst_filter_run(). + * Function prototype for a filter callback that can be use in gst_filter_run(). * The function should apply its filtering to @obj. Additional data passed to * gst_filter_run() are in @data. * diff --git a/gst/gstformat.c b/gst/gstformat.c index faa6471dd6..263fa1d307 100644 --- a/gst/gstformat.c +++ b/gst/gstformat.c @@ -247,7 +247,7 @@ gst_format_get_details (GstFormat format) * Iterate all the registered formats. The format definition is read * only. * - * Returns: A GstIterator of #GstFormatDefinition. + * Returns: (transfer full): a GstIterator of #GstFormatDefinition. */ GstIterator * gst_format_iterate_definitions (void) diff --git a/gst/gstghostpad.c b/gst/gstghostpad.c index a126f7c4e8..f6280af772 100644 --- a/gst/gstghostpad.c +++ b/gst/gstghostpad.c @@ -1023,7 +1023,7 @@ construct_failed: /** * gst_ghost_pad_new_no_target: - * @name: the name of the new pad, or NULL to assign a default name. + * @name: (allow-none): the name of the new pad, or NULL to assign a default name. * @dir: the direction of the ghostpad * * Create a new ghostpad without a target with the given direction. @@ -1032,7 +1032,7 @@ construct_failed: * * The created ghostpad will not have a padtemplate. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. */ GstPad * gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir) @@ -1050,15 +1050,15 @@ gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir) /** * gst_ghost_pad_new: - * @name: the name of the new pad, or NULL to assign a default name. - * @target: the pad to ghost. + * @name: (allow-none): the name of the new pad, or NULL to assign a default name + * @target: (transfer none): the pad to ghost. * * Create a new ghostpad with @target as the target. The direction will be taken * from the target pad. @target must be unlinked. * * Will ref the target. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. */ GstPad * gst_ghost_pad_new (const gchar * name, GstPad * target) @@ -1089,16 +1089,16 @@ set_target_failed: /** * gst_ghost_pad_new_from_template: - * @name: the name of the new pad, or NULL to assign a default name. - * @target: the pad to ghost. - * @templ: the #GstPadTemplate to use on the ghostpad. + * @name: (allow-none): the name of the new pad, or NULL to assign a default name. + * @target: (transfer none): the pad to ghost. + * @templ: (transfer none): the #GstPadTemplate to use on the ghostpad. * * Create a new ghostpad with @target as the target. The direction will be taken * from the target pad. The template used on the ghostpad will be @template. * * Will ref the target. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. * * Since: 0.10.10 */ @@ -1136,13 +1136,13 @@ set_target_failed: /** * gst_ghost_pad_new_no_target_from_template: - * @name: the name of the new pad, or NULL to assign a default name. - * @templ: the #GstPadTemplate to create the ghostpad from. + * @name: (allow-none): the name of the new pad, or NULL to assign a default name + * @templ: (transfer none): the #GstPadTemplate to create the ghostpad from. * * Create a new ghostpad based on @templ, without setting a target. The * direction will be taken from the @templ. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. * * Since: 0.10.10 */ @@ -1166,7 +1166,7 @@ gst_ghost_pad_new_no_target_from_template (const gchar * name, * * Get the target pad of @gpad. Unref target pad after usage. * - * Returns: the target #GstPad, can be NULL if the ghostpad + * Returns: (transfer full): the target #GstPad, can be NULL if the ghostpad * has no target set. Unref target pad after usage. */ GstPad * @@ -1186,14 +1186,14 @@ gst_ghost_pad_get_target (GstGhostPad * gpad) /** * gst_ghost_pad_set_target: * @gpad: the #GstGhostPad - * @newtarget: the new pad target + * @newtarget: (transfer none) (allow-none): the new pad target * * Set the new target of the ghostpad @gpad. Any existing target * is unlinked and links to the new target are established. if @newtarget is * NULL the target will be cleared. * - * Returns: TRUE if the new target could be set. This function can return FALSE - * when the internal pads could not be linked. + * Returns: (transfer full): TRUE if the new target could be set. This function + * can return FALSE when the internal pads could not be linked. */ gboolean gst_ghost_pad_set_target (GstGhostPad * gpad, GstPad * newtarget) diff --git a/gst/gstindex.c b/gst/gstindex.c index f7809e0831..b686eeebfa 100644 --- a/gst/gstindex.c +++ b/gst/gstindex.c @@ -29,6 +29,8 @@ * in a pipeline. */ +/* FIXME: complete gobject annotations */ + #include "gst_private.h" #include "gstinfo.h" @@ -281,7 +283,7 @@ gst_index_group_free (GstIndexGroup * group) * * Create a new tileindex object * - * Returns: a new index object + * Returns: (transfer full): a new index object */ GstIndex * gst_index_new (void) @@ -501,7 +503,9 @@ gst_index_set_resolver_full (GstIndex * index, GstIndexResolver resolver, * * Copies an entry and returns the result. * - * Returns: a newly allocated #GstIndexEntry. + * Free-function: gst_index_entry_free + * + * Returns: (transfer full): a newly allocated #GstIndexEntry. */ GstIndexEntry * gst_index_entry_copy (GstIndexEntry * entry) @@ -514,7 +518,7 @@ gst_index_entry_copy (GstIndexEntry * entry) /** * gst_index_entry_free: - * @entry: the entry to free + * @entry: (transfer full): the entry to free * * Free the memory used by the given entry. */ @@ -553,7 +557,9 @@ gst_index_entry_free (GstIndexEntry * entry) * used to map dynamic GstFormat ids to their original * format key. * - * Returns: a pointer to the newly added entry in the index. + * Free-function: gst_index_entry_free + * + * Returns: (transfer full): a pointer to the newly added entry in the index. */ GstIndexEntry * gst_index_add_format (GstIndex * index, gint id, GstFormat format) diff --git a/gst/gstindexfactory.c b/gst/gstindexfactory.c index a8234ff46f..62c79fdccf 100644 --- a/gst/gstindexfactory.c +++ b/gst/gstindexfactory.c @@ -78,7 +78,7 @@ gst_index_factory_finalize (GObject * object) * * Create a new indexfactory with the given parameters * - * Returns: a new #GstIndexFactory. + * Returns: (transfer full): a new #GstIndexFactory. */ GstIndexFactory * gst_index_factory_new (const gchar * name, const gchar * longdesc, GType type) @@ -109,6 +109,7 @@ gst_index_factory_destroy (GstIndexFactory * factory) g_return_if_fail (factory != NULL); /* we don't free the struct bacause someone might have a handle to it.. */ + /* FIXME: gst_index_factory_destroy */ } /** @@ -117,7 +118,7 @@ gst_index_factory_destroy (GstIndexFactory * factory) * * Search for an indexfactory of the given name. * - * Returns: #GstIndexFactory if found, NULL otherwise + * Returns: (transfer full): #GstIndexFactory if found, NULL otherwise */ GstIndexFactory * gst_index_factory_find (const gchar * name) @@ -143,7 +144,7 @@ gst_index_factory_find (const gchar * name) * Create a new #GstIndex instance from the * given indexfactory. * - * Returns: A new #GstIndex instance. + * Returns: (transfer full): a new #GstIndex instance. */ GstIndex * gst_index_factory_create (GstIndexFactory * factory) @@ -173,7 +174,7 @@ gst_index_factory_create (GstIndexFactory * factory) * Create a new #GstIndex instance from the * indexfactory with the given name. * - * Returns: A new #GstIndex instance. + * Returns: (transfer full): a new #GstIndex instance. */ GstIndex * gst_index_factory_make (const gchar * name) diff --git a/gst/gstinfo.c b/gst/gstinfo.c index 312b9b8108..e92f060e06 100644 --- a/gst/gstinfo.c +++ b/gst/gstinfo.c @@ -439,7 +439,8 @@ _gst_debug_init (void) * @file: the file that emitted the message, usually the __FILE__ identifier * @function: the function that emitted the message * @line: the line from that the message was emitted, usually __LINE__ - * @object: the object this message relates to or NULL if none + * @object: (transfer none) (allow-none): the object this message relates to, + * or NULL if none * @format: a printf style format string * @...: optional arguments for the format * @@ -465,7 +466,8 @@ gst_debug_log (GstDebugCategory * category, GstDebugLevel level, * @file: the file that emitted the message, usually the __FILE__ identifier * @function: the function that emitted the message * @line: the line from that the message was emitted, usually __LINE__ - * @object: the object this message relates to or NULL if none + * @object: (transfer none) (allow-none): the object this message relates to, + * or NULL if none * @format: a printf style format string * @args: optional arguments for the format * @@ -734,7 +736,8 @@ gst_debug_print_segment (gpointer ptr) * terminals. * You need to free the string after use. * - * Returns: a string containing the color definition + * Returns: (transfer full) (type gchar*): a string containing the color + * definition */ gchar * gst_debug_construct_term_color (guint colorinfo) @@ -883,7 +886,8 @@ static const gchar *levelcolormap[GST_LEVEL_COUNT] = { * @function: the function that emitted the message * @line: the line from that the message was emitted, usually __LINE__ * @message: the actual message - * @object: the object this message relates to or NULL if none + * @object: (transfer none) (allow-none): the object this message relates to, + * or NULL if none * @unused: an unused variable, reserved for some user_data. * * The default logging handler used by GStreamer. Logging functions get called @@ -1034,7 +1038,7 @@ gst_debug_level_get_name (GstDebugLevel level) /** * gst_debug_add_log_function: * @func: the function to use - * @data: user data + * @data: (closure): user data * * Adds the logging function to the list of logging functions. * Be sure to use #G_GNUC_NO_INSTRUMENT on that function, it is needed. @@ -1509,7 +1513,8 @@ gst_debug_category_get_description (GstDebugCategory * category) * may change anytime. * The caller has to free the list after use. * - * Returns: the list of categories + * Returns: (transfer container) (element-type Gst.DebugCategory): the list of + * debug categories */ GSList * gst_debug_get_all_categories (void) diff --git a/gst/gstmessage.c b/gst/gstmessage.c index 76ceb9ac08..5aaa3f1b9d 100644 --- a/gst/gstmessage.c +++ b/gst/gstmessage.c @@ -246,14 +246,14 @@ _gst_message_copy (GstMessage * message) * gst_message_new_custom: * @type: The #GstMessageType to distinguish messages * @src: The object originating the message. - * @structure: The structure for the message. The message will take ownership of - * the structure. + * @structure: (transfer full): the structure for the message. The message + * will take ownership of the structure. * * Create a new custom-typed message. This can be used for anything not * handled by other message-specific functions to pass a message to the * app. The structure field can be NULL. * - * Returns: The new message. + * Returns: (transfer full): The new message. * * MT safe. */ @@ -342,13 +342,13 @@ gst_message_set_seqnum (GstMessage * message, guint32 seqnum) /** * gst_message_new_eos: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * * Create a new eos message. This message is generated and posted in * the sink elements of a GstBin. The bin will only forward the EOS * message to the application if all sinks have posted an EOS message. * - * Returns: The new eos message. + * Returns: (transfer full): The new eos message. * * MT safe. */ @@ -364,8 +364,8 @@ gst_message_new_eos (GstObject * src) /** * gst_message_new_error: - * @src: The object originating the message. - * @error: The GError for this message. + * @src: (transfer none): The object originating the message. + * @error: (transfer none): The GError for this message. * @debug: A debugging string. * * Create a new error message. The message will copy @error and @@ -373,7 +373,7 @@ gst_message_new_eos (GstObject * src) * occured. The pipeline will probably (partially) stop. The application * receiving this message should stop the pipeline. * - * Returns: The new error message. + * Returns: (transfer full): the new error message. * * MT safe. */ @@ -393,14 +393,14 @@ gst_message_new_error (GstObject * src, GError * error, const gchar * debug) /** * gst_message_new_warning: - * @src: The object originating the message. - * @error: The GError for this message. + * @src: (transfer none): The object originating the message. + * @error: (transfer none): The GError for this message. * @debug: A debugging string. * * Create a new warning message. The message will make copies of @error and * @debug. * - * Returns: The new warning message. + * Returns: (transfer full): The new warning message. * * MT safe. */ @@ -420,8 +420,8 @@ gst_message_new_warning (GstObject * src, GError * error, const gchar * debug) /** * gst_message_new_info: - * @src: The object originating the message. - * @error: The GError for this message. + * @src: (transfer none): The object originating the message. + * @error: (transfer none): The GError for this message. * @debug: A debugging string. * * Create a new info message. The message will make copies of @error and @@ -429,7 +429,7 @@ gst_message_new_warning (GstObject * src, GError * error, const gchar * debug) * * MT safe. * - * Returns: The new info message. + * Returns: (transfer full): the new info message. * * Since: 0.10.12 */ @@ -449,13 +449,13 @@ gst_message_new_info (GstObject * src, GError * error, const gchar * debug) /** * gst_message_new_tag: - * @src: The object originating the message. - * @tag_list: The tag list for the message. + * @src: (transfer none): The object originating the message. + * @tag_list: (transfer full): the tag list for the message. * * Create a new tag message. The message will take ownership of the tag list. * The message is posted by elements that discovered a new taglist. * - * Returns: The new tag message. + * Returns: (transfer full): the new tag message. * * MT safe. */ @@ -474,16 +474,16 @@ gst_message_new_tag (GstObject * src, GstTagList * tag_list) /** * gst_message_new_tag_full: - * @src: The object originating the message. - * @pad: The originating pad for the tag. - * @tag_list: The tag list for the message. + * @src: (transfer none): the object originating the message. + * @pad: (transfer none): the originating pad for the tag. + * @tag_list: (transfer full): the tag list for the message. * * Create a new tag message. The message will take ownership of the tag list. * The message is posted by elements that discovered a new taglist. * * MT safe. * - * Returns: The new tag message. + * Returns: (transfer full): the new tag message. * * Since: 0.10.24 */ @@ -507,7 +507,7 @@ gst_message_new_tag_full (GstObject * src, GstPad * pad, GstTagList * tag_list) /** * gst_message_new_buffering: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * @percent: The buffering percent * * Create a new buffering message. This message can be posted by an element that @@ -523,7 +523,7 @@ gst_message_new_tag_full (GstObject * src, GstPad * pad, GstTagList * tag_list) * * MT safe. * - * Returns: The new buffering message. + * Returns: (transfer full): The new buffering message. * * Since: 0.10.11 */ @@ -549,7 +549,7 @@ gst_message_new_buffering (GstObject * src, gint percent) /** * gst_message_new_state_changed: - * @src: the object originating the message + * @src: (transfer none): the object originating the message * @oldstate: the previous state * @newstate: the new (current) state * @pending: the pending (target) state @@ -557,7 +557,7 @@ gst_message_new_buffering (GstObject * src, gint percent) * Create a state change message. This message is posted whenever an element * changed its state. * - * Returns: The new state change message. + * Returns: (transfer full): the new state change message. * * MT safe. */ @@ -579,13 +579,13 @@ gst_message_new_state_changed (GstObject * src, /** * gst_message_new_state_dirty: - * @src: the object originating the message + * @src: (transfer none): the object originating the message * * Create a state dirty message. This message is posted whenever an element * changed its state asynchronously and is used internally to update the * states of container objects. * - * Returns: The new state dirty message. + * Returns: (transfer full): the new state dirty message. * * MT safe. */ @@ -601,8 +601,8 @@ gst_message_new_state_dirty (GstObject * src) /** * gst_message_new_clock_provide: - * @src: The object originating the message. - * @clock: The clock it provides + * @src: (transfer none): the object originating the message. + * @clock: (transfer none): the clock it provides * @ready: TRUE if the sender can provide a clock * * Create a clock provide message. This message is posted whenever an @@ -612,7 +612,7 @@ gst_message_new_state_dirty (GstObject * src) * This message is mainly used internally to manage the clock * selection. * - * Returns: The new provide clock message. + * Returns: (transfer full): the new provide clock message. * * MT safe. */ @@ -633,8 +633,8 @@ gst_message_new_clock_provide (GstObject * src, GstClock * clock, /** * gst_message_new_clock_lost: - * @src: The object originating the message. - * @clock: the clock that was lost + * @src: (transfer none): the object originating the message. + * @clock: (transfer none): the clock that was lost * * Create a clock lost message. This message is posted whenever the * clock is not valid anymore. @@ -643,7 +643,7 @@ gst_message_new_clock_provide (GstObject * src, GstClock * clock, * select a new clock again when it goes to PLAYING. It might therefore * be needed to set the pipeline to PAUSED and PLAYING again. * - * Returns: The new clock lost message. + * Returns: (transfer full): The new clock lost message. * * MT safe. */ @@ -662,13 +662,13 @@ gst_message_new_clock_lost (GstObject * src, GstClock * clock) /** * gst_message_new_new_clock: - * @src: The object originating the message. - * @clock: the new selected clock + * @src: (transfer none): The object originating the message. + * @clock: (transfer none): the new selected clock * * Create a new clock message. This message is posted whenever the * pipeline selectes a new clock for the pipeline. * - * Returns: The new new clock message. + * Returns: (transfer full): The new new clock message. * * MT safe. */ @@ -687,9 +687,9 @@ gst_message_new_new_clock (GstObject * src, GstClock * clock) /** * gst_message_new_structure_change: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * @type: The change type. - * @owner: The owner element of @src. + * @owner: (transfer none): The owner element of @src. * @busy: Whether the structure change is busy. * * Create a new structure change message. This message is posted when the @@ -698,7 +698,7 @@ gst_message_new_new_clock (GstObject * src, GstClock * clock) * * @src should be the sinkpad that unlinked or linked. * - * Returns: The new structure change message. + * Returns: (transfer full): the new structure change message. * * MT safe. * @@ -728,7 +728,7 @@ gst_message_new_structure_change (GstObject * src, GstStructureChangeType type, /** * gst_message_new_segment_start: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * @format: The format of the position being played * @position: The position of the segment being played * @@ -737,7 +737,7 @@ gst_message_new_structure_change (GstObject * src, GstStructureChangeType type, * is not received by the application but is used for maintenance reasons in * container elements. * - * Returns: The new segment start message. + * Returns: (transfer full): the new segment start message. * * MT safe. */ @@ -758,7 +758,7 @@ gst_message_new_segment_start (GstObject * src, GstFormat format, /** * gst_message_new_segment_done: - * @src: The object originating the message. + * @src: (transfer none): the object originating the message. * @format: The format of the position being done * @position: The position of the segment being done * @@ -767,7 +767,7 @@ gst_message_new_segment_start (GstObject * src, GstFormat format, * is received by the application after all elements that posted a segment_start * have posted the segment_done. * - * Returns: The new segment done message. + * Returns: (transfer full): the new segment done message. * * MT safe. */ @@ -788,14 +788,14 @@ gst_message_new_segment_done (GstObject * src, GstFormat format, /** * gst_message_new_application: - * @src: The object originating the message. - * @structure: The structure for the message. The message will take ownership of - * the structure. + * @src: (transfer none): the object originating the message. + * @structure: (transfer full): the structure for the message. The message + * will take ownership of the structure. * * Create a new application-typed message. GStreamer will never create these * messages; they are a gift from us to you. Enjoy. * - * Returns: The new application message. + * Returns: (transfer full): The new application message. * * MT safe. */ @@ -807,16 +807,16 @@ gst_message_new_application (GstObject * src, GstStructure * structure) /** * gst_message_new_element: - * @src: The object originating the message. - * @structure: The structure for the message. The message will take ownership of - * the structure. + * @src: (transfer none): The object originating the message. + * @structure: (transfer full): The structure for the message. The message + * will take ownership of the structure. * * Create a new element-specific message. This is meant as a generic way of * allowing one-way communication from an element to an application, for example * "the firewire cable was unplugged". The format of the message should be * documented in the element's documentation. The structure field can be NULL. * - * Returns: The new element message. + * Returns: (transfer full): The new element message. * * MT safe. */ @@ -828,7 +828,7 @@ gst_message_new_element (GstObject * src, GstStructure * structure) /** * gst_message_new_duration: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * @format: The format of the duration * @duration: The new duration * @@ -840,7 +840,7 @@ gst_message_new_element (GstObject * src, GstStructure * structure) * cached duration should be discarded. The new duration can then be * retrieved via a query. * - * Returns: The new duration message. + * Returns: (transfer full): The new duration message. * * MT safe. */ @@ -860,14 +860,14 @@ gst_message_new_duration (GstObject * src, GstFormat format, gint64 duration) /** * gst_message_new_async_start: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * @new_base_time: if a new base_time should be set on the element * * This message is posted by elements when they start an ASYNC state change. * @new_base_time is set to TRUE when the element lost its state when it was * PLAYING. * - * Returns: The new async_start message. + * Returns: (transfer full): The new async_start message. * * MT safe. * @@ -888,11 +888,11 @@ gst_message_new_async_start (GstObject * src, gboolean new_base_time) /** * gst_message_new_async_done: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * * The message is posted when elements completed an ASYNC state change. * - * Returns: The new async_done message. + * Returns: (transfer full): The new async_done message. * * MT safe. * @@ -910,12 +910,12 @@ gst_message_new_async_done (GstObject * src) /** * gst_message_new_latency: - * @src: The object originating the message. + * @src: (transfer none): The object originating the message. * * This message can be posted by elements when their latency requirements have * changed. * - * Returns: The new latency message. + * Returns: (transfer full): The new latency message. * * MT safe. * @@ -933,14 +933,14 @@ gst_message_new_latency (GstObject * src) /** * gst_message_new_request_state: - * @src: The object originating the message. + * @src: (transfer none): the object originating the message. * @state: The new requested state * * This message can be posted by elements when they want to have their state * changed. A typical use case would be an audio server that wants to pause the * pipeline because a higher priority stream is being played. * - * Returns: The new requst state message. + * Returns: (transfer full): the new requst state message. * * MT safe. * @@ -965,8 +965,8 @@ gst_message_new_request_state (GstObject * src, GstState state) * * Access the structure of the message. * - * Returns: The structure of the message. The structure is still - * owned by the message, which means that you should not free it and + * Returns: (transfer none): The structure of the message. The structure is + * still owned by the message, which means that you should not free it and * that the pointer becomes invalid when you free the message. * * MT safe. @@ -982,7 +982,7 @@ gst_message_get_structure (GstMessage * message) /** * gst_message_parse_tag: * @message: A valid #GstMessage of type GST_MESSAGE_TAG. - * @tag_list: (out): Return location for the tag-list. + * @tag_list: (out callee-allocates): return location for the tag-list. * * Extracts the tag list from the GstMessage. The tag list returned in the * output argument is a copy; the caller must free it when done. @@ -1025,8 +1025,9 @@ gst_message_parse_tag (GstMessage * message, GstTagList ** tag_list) /** * gst_message_parse_tag_full: * @message: A valid #GstMessage of type GST_MESSAGE_TAG. - * @pad: (out): Location where the originating pad is stored, unref after usage - * @tag_list: (out): Return location for the tag-list. + * @pad: (out callee-allocates): location where the originating pad is stored, + * unref after usage + * @tag_list: (out callee-allocates): return location for the tag-list. * * Extracts the tag list from the GstMessage. The tag list returned in the * output argument is a copy; the caller must free it when done. @@ -1066,7 +1067,7 @@ gst_message_parse_tag_full (GstMessage * message, GstPad ** pad, /** * gst_message_parse_buffering: * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING. - * @percent: (out): Return location for the percent. + * @percent: (out) (allow-none): Return location for the percent. * * Extracts the buffering percent from the GstMessage. see also * gst_message_new_buffering(). @@ -1114,10 +1115,11 @@ gst_message_set_buffering_stats (GstMessage * message, GstBufferingMode mode, /** * gst_message_parse_buffering_stats: * @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING. - * @mode: (out): a buffering mode - * @avg_in: (out): the average input rate - * @avg_out: (out): the average output rate - * @buffering_left: (out): amount of buffering time left in milliseconds. + * @mode: (out) (allow-none): a buffering mode, or NULL + * @avg_in: (out) (allow-none): the average input rate, or NULL + * @avg_out: (out) (allow-none): the average output rate, or NULL + * @buffering_left: (out) (allow-none): amount of buffering time left in + * milliseconds, or NULL * * Extracts the buffering stats values from @message. * @@ -1148,9 +1150,9 @@ gst_message_parse_buffering_stats (GstMessage * message, /** * gst_message_parse_state_changed: * @message: a valid #GstMessage of type GST_MESSAGE_STATE_CHANGED - * @oldstate: (out): the previous state, or NULL - * @newstate: (out): the new (current) state, or NULL - * @pending: (out): the pending (target) state, or NULL + * @oldstate: (out) (allow-none): the previous state, or NULL + * @newstate: (out) (allow-none): the new (current) state, or NULL + * @pending: (out) (allow-none): the pending (target) state, or NULL * * Extracts the old and new states from the GstMessage. * @@ -1198,8 +1200,9 @@ gst_message_parse_state_changed (GstMessage * message, /** * gst_message_parse_clock_provide: * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_PROVIDE. - * @clock: (out): A pointer to hold a clock object. - * @ready: (out): A pointer to hold the ready flag. + * @clock: (out) (allow-none) (transfer none): a pointer to hold a clock + * object, or NULL + * @ready: (out) (allow-none): a pointer to hold the ready flag, or NULL * * Extracts the clock and ready flag from the GstMessage. * The clock object returned remains valid until the message is freed. @@ -1231,7 +1234,7 @@ gst_message_parse_clock_provide (GstMessage * message, GstClock ** clock, /** * gst_message_parse_clock_lost: * @message: A valid #GstMessage of type GST_MESSAGE_CLOCK_LOST. - * @clock: (out): A pointer to hold the lost clock + * @clock: (out) (allow-none) (transfer none): a pointer to hold the lost clock * * Extracts the lost clock from the GstMessage. * The clock object returned remains valid until the message is freed. @@ -1258,7 +1261,8 @@ gst_message_parse_clock_lost (GstMessage * message, GstClock ** clock) /** * gst_message_parse_new_clock: * @message: A valid #GstMessage of type GST_MESSAGE_NEW_CLOCK. - * @clock: A pointer to hold the selected new clock + * @clock: (out) (allow-none) (transfer none): a pointer to hold the selected + * new clock * * Extracts the new clock from the GstMessage. * The clock object returned remains valid until the message is freed. @@ -1286,9 +1290,10 @@ gst_message_parse_new_clock (GstMessage * message, GstClock ** clock) * gst_message_parse_structure_change: * @message: A valid #GstMessage of type GST_MESSAGE_STRUCTURE_CHANGE. * @type: (out): A pointer to hold the change type - * @owner: (out): The owner element of the message source - * @busy: (out): A pointer to hold whether the change is in progress or has been - * completed + * @owner: (out) (allow-none) (transfer none): The owner element of the + * message source + * @busy: (out) (allow-none): a pointer to hold whether the change is in + * progress or has been completed * * Extracts the change type and completion status from the GstMessage. * @@ -1324,8 +1329,9 @@ gst_message_parse_structure_change (GstMessage * message, /** * gst_message_parse_error: * @message: A valid #GstMessage of type GST_MESSAGE_ERROR. - * @gerror: (out): Location for the GError - * @debug: (out): Location for the debug message, or NULL + * @gerror: (out) (allow-none) (transfer full): location for the GError + * @debug: (out) (allow-none) (transfer full): location for the debug message, + * or NULL * * Extracts the GError and debug string from the GstMessage. The values returned * in the output arguments are copies; the caller must free them when done. @@ -1382,8 +1388,9 @@ gst_message_parse_error (GstMessage * message, GError ** gerror, gchar ** debug) /** * gst_message_parse_warning: * @message: A valid #GstMessage of type GST_MESSAGE_WARNING. - * @gerror: (out): Location for the GError - * @debug: (out): Location for the debug message, or NULL + * @gerror: (out) (allow-none) (transfer full): location for the GError + * @debug: (out) (allow-none) (transfer full): location for the debug message, + * or NULL * * Extracts the GError and debug string from the GstMessage. The values returned * in the output arguments are copies; the caller must free them when done. @@ -1420,8 +1427,9 @@ gst_message_parse_warning (GstMessage * message, GError ** gerror, /** * gst_message_parse_info: * @message: A valid #GstMessage of type GST_MESSAGE_INFO. - * @gerror: (out): Location for the GError - * @debug: (out): Location for the debug message, or NULL + * @gerror: (out) (allow-none) (transfer full): location for the GError + * @debug: (out) (allow-none) (transfer full): location for the debug message, + * or NULL * * Extracts the GError and debug string from the GstMessage. The values returned * in the output arguments are copies; the caller must free them when done. @@ -1589,12 +1597,12 @@ gst_message_parse_request_state (GstMessage * message, GstState * state) * gst_message_new_stream_status: * @src: The object originating the message. * @type: The stream status type. - * @owner: The owner element of @src. + * @owner: (transfer none): the owner element of @src. * * Create a new stream status message. This message is posted when a streaming * thread is created/destroyed or when the state changed. * - * Returns: The new stream status message. + * Returns: (transfer full): the new stream status message. * * MT safe. * @@ -1619,7 +1627,7 @@ gst_message_new_stream_status (GstObject * src, GstStreamStatusType type, * gst_message_parse_stream_status: * @message: A valid #GstMessage of type GST_MESSAGE_STREAM_STATUS. * @type: (out): A pointer to hold the status type - * @owner: (out): The owner element of the message source + * @owner: (out) (transfer none): The owner element of the message source * * Extracts the stream status type and owner the GstMessage. The returned * owner remains valid for as long as the reference to @message is valid and @@ -1712,7 +1720,7 @@ gst_message_get_stream_status_object (GstMessage * message) * @duration will contain the amount of time (in GST_FORMAT_TIME) of the stepped * @amount of media in format @format. * - * Returns: The new step_done message. + * Returns: (transfer full): the new step_done message. * * MT safe. * @@ -1742,13 +1750,13 @@ gst_message_new_step_done (GstObject * src, GstFormat format, guint64 amount, /** * gst_message_parse_step_done: * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE. - * @format: (out): result location for the format - * @amount: (out): result location for the amount - * @rate: (out): result location for the rate - * @flush: (out): result location for the flush flag - * @intermediate: (out): result location for the intermediate flag - * @duration: (out): result location for the duration - * @eos: (out): result location for the EOS flag + * @format: (out) (allow-none): result location for the format + * @amount: (out) (allow-none): result location for the amount + * @rate: (out) (allow-none): result location for the rate + * @flush: (out) (allow-none): result location for the flush flag + * @intermediate: (out) (allow-none): result location for the intermediate flag + * @duration: (out) (allow-none): result location for the duration + * @eos: (out) (allow-none): result location for the EOS flag * * Extract the values the step_done message. * @@ -1795,7 +1803,7 @@ gst_message_parse_step_done (GstMessage * message, GstFormat * format, * message is emited, the application can queue a new step operation in the * element. * - * Returns: The new step_start message. + * Returns: (transfer full): The new step_start message. * * MT safe. * @@ -1823,12 +1831,12 @@ gst_message_new_step_start (GstObject * src, gboolean active, GstFormat format, /** * gst_message_parse_step_start: * @message: A valid #GstMessage of type GST_MESSAGE_STEP_DONE. - * @active: (out): result location for the active flag - * @format: (out): result location for the format - * @amount: (out): result location for the amount - * @rate: (out): result location for the rate - * @flush: (out): result location for the flush flag - * @intermediate: (out): result location for the intermediate flag + * @active: (out) (allow-none): result location for the active flag + * @format: (out) (allow-none): result location for the format + * @amount: (out) (allow-none): result location for the amount + * @rate: (out) (allow-none): result location for the rate + * @flush: (out) (allow-none): result location for the flush flag + * @intermediate: (out) (allow-none): result location for the intermediate flag * * Extract the values from step_start message. * @@ -1876,7 +1884,7 @@ gst_message_parse_step_start (GstMessage * message, gboolean * active, * buffer that generated the QoS event. Values can be left to * GST_CLOCK_TIME_NONE when unknown. * - * Returns: The new qos message. + * Returns: (transfer full): The new qos message. * * MT safe. * @@ -1971,11 +1979,15 @@ gst_message_set_qos_stats (GstMessage * message, GstFormat format, /** * gst_message_parse_qos: * @message: A valid #GstMessage of type GST_MESSAGE_QOS. - * @live: (out): if the message was generated by a live element - * @running_time: (out): the running time of the buffer that generated the message - * @stream_time: (out): the stream time of the buffer that generated the message - * @timestamp: (out): the timestamps of the buffer that generated the message - * @duration: (out): the duration of the buffer that generated the message + * @live: (out) (allow-none): if the message was generated by a live element + * @running_time: (out) (allow-none): the running time of the buffer that + * generated the message + * @stream_time: (out) (allow-none): the stream time of the buffer that + * generated the message + * @timestamp: (out) (allow-none): the timestamps of the buffer that + * generated the message + * @duration: (out) (allow-none): the duration of the buffer that + * generated the message * * Extract the timestamps and live status from the QoS message. * @@ -2006,11 +2018,13 @@ gst_message_parse_qos (GstMessage * message, gboolean * live, /** * gst_message_parse_qos_values: * @message: A valid #GstMessage of type GST_MESSAGE_QOS. - * @jitter: (out): The difference of the running-time against the deadline. - * @proportion: (out): Long term prediction of the ideal rate relative to normal rate - * to get optimal quality. - * @quality: (out): An element dependent integer value that specifies the current - * quality level of the element. The default maximum quality is 1000000. + * @jitter: (out) (allow-none): The difference of the running-time against + * the deadline. + * @proportion: (out) (allow-none): Long term prediction of the ideal rate + * relative to normal rate to get optimal quality. + * @quality: (out) (allow-none): An element dependent integer value that + * specifies the current quality level of the element. The default + * maximum quality is 1000000. * * Extract the QoS values that have been calculated/analysed from the QoS data * @@ -2034,13 +2048,14 @@ gst_message_parse_qos_values (GstMessage * message, gint64 * jitter, /** * gst_message_parse_qos_stats: * @message: A valid #GstMessage of type GST_MESSAGE_QOS. - * @format: (out): Units of the 'processed' and 'dropped' fields. Video sinks and video - * filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters - * will likely use GST_FORMAT_DEFAULT (samples). - * @processed: (out): Total number of units correctly processed since the last state - * change to READY or a flushing operation. - * @dropped: (out): Total number of units dropped since the last state change to READY - * or a flushing operation. + * @format: (out) (allow-none): Units of the 'processed' and 'dropped' fields. + * Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). + * Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT + * (samples). + * @processed: (out) (allow-none): Total number of units correctly processed + * since the last state change to READY or a flushing operation. + * @dropped: (out) (allow-none): Total number of units dropped since the last + * state change to READY or a flushing operation. * * Extract the QoS stats representing the history of the current continuous * pipeline playback period. diff --git a/gst/gstmessage.h b/gst/gstmessage.h index d845c32972..c5a5a7a55d 100644 --- a/gst/gstmessage.h +++ b/gst/gstmessage.h @@ -330,7 +330,7 @@ gst_message_unref (GstMessage * msg) * * Creates a copy of the message. Returns a copy of the message. * - * Returns: a new copy of @msg. + * Returns: (transfer full): a new copy of @msg. * * MT safe */ @@ -346,10 +346,12 @@ gst_message_copy (const GstMessage * msg) /** * gst_message_make_writable: - * @msg: the message to make writable + * @msg: (transfer full): the message to make writable * * Checks if a message is writable. If not, a writable copy is made and - * returned. Returns a message (possibly a duplicate) that is writable. + * returned. + * + * Returns: (transfer full): a message (possibly a duplicate) that is writable. * * MT safe */ diff --git a/gst/gstminiobject.c b/gst/gstminiobject.c index 3bacaf2904..332b962a4c 100644 --- a/gst/gstminiobject.c +++ b/gst/gstminiobject.c @@ -177,7 +177,7 @@ gst_mini_object_finalize (GstMiniObject * obj) * * MT safe * - * Returns: the new mini-object. + * Returns: (transfer full): the new mini-object. */ GstMiniObject * gst_mini_object_new (GType type) @@ -217,7 +217,7 @@ gst_mini_object_new (GType type) * * MT safe * - * Returns: the new mini-object. + * Returns: (transfer full): the new mini-object. */ GstMiniObject * gst_mini_object_copy (const GstMiniObject * mini_object) @@ -255,7 +255,7 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object) /** * gst_mini_object_make_writable: - * @mini_object: the mini-object to make writable + * @mini_object: (transfer full): the mini-object to make writable * * Checks if a mini-object is writable. If not, a writable copy is made and * returned. This gives away the reference to the original mini object, @@ -263,7 +263,8 @@ gst_mini_object_is_writable (const GstMiniObject * mini_object) * * MT safe * - * Returns: a mini-object (possibly the same pointer) that is writable. + * Returns: (transfer full): a mini-object (possibly the same pointer) that + * is writable. */ GstMiniObject * gst_mini_object_make_writable (GstMiniObject * mini_object) @@ -371,7 +372,8 @@ gst_mini_object_unref (GstMiniObject * mini_object) /** * gst_mini_object_replace: - * @olddata: pointer to a pointer to a mini-object to be replaced + * @olddata: (inout) (transfer full): pointer to a pointer to a mini-object to + * be replaced * @newdata: pointer to new mini-object * * Modifies a pointer to point to a new mini-object. The modification @@ -475,8 +477,8 @@ gst_value_mini_object_lcopy (const GValue * value, guint n_collect_values, /** * gst_value_set_mini_object: - * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type - * @mini_object: mini object value to set + * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type + * @mini_object: (transfer none): mini object value to set * * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to * @mini_object. @@ -496,8 +498,8 @@ gst_value_set_mini_object (GValue * value, GstMiniObject * mini_object) /** * gst_value_take_mini_object: - * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type - * @mini_object: mini object value to take + * @value: a valid #GValue of %GST_TYPE_MINI_OBJECT derived type + * @mini_object: (transfer full): mini object value to take * * Set the contents of a %GST_TYPE_MINI_OBJECT derived #GValue to * @mini_object. @@ -527,7 +529,7 @@ gst_value_take_mini_object (GValue * value, GstMiniObject * mini_object) * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue. * Does not increase the refcount of the returned object. * - * Returns: mini object contents of @value + * Returns: (transfer none): mini object contents of @value */ GstMiniObject * gst_value_get_mini_object (const GValue * value) @@ -544,7 +546,7 @@ gst_value_get_mini_object (const GValue * value) * Get the contents of a %GST_TYPE_MINI_OBJECT derived #GValue, * increasing its reference count. * - * Returns: mini object contents of @value + * Returns: (transfer full): mini object contents of @value * * Since: 0.10.20 */ diff --git a/gst/gstobject.c b/gst/gstobject.c index 86948a6231..d4f755dfa6 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -409,8 +409,9 @@ gst_object_sink (gpointer object) /** * gst_object_replace: - * @oldobj: pointer to a place of a #GstObject to replace - * @newobj: a new #GstObject + * @oldobj: (inout) (transfer full): pointer to a place of a #GstObject to + * replace + * @newobj: (transfer none): a new #GstObject * * Unrefs the #GstObject pointed to by @oldobj, refs @newobj and * puts @newobj in *@oldobj. Be carefull when calling this @@ -558,8 +559,9 @@ gst_object_dispatch_properties_changed (GObject * object, * @object: the #GObject that signalled the notify. * @orig: a #GstObject that initiated the notify. * @pspec: a #GParamSpec of the property. - * @excluded_props: a set of user-specified properties to exclude or - * NULL to show all changes. + * @excluded_props: (array zero-terminated=1) (element-type gchar*) + * (allow-none):a set of user-specified properties to exclude or + * NULL to show all changes. * * A default deep_notify signal callback for an object. The user data * should contain a pointer to an array of strings that should be excluded @@ -727,7 +729,9 @@ had_parent: * For a nameless object, this returns NULL, which you can safely g_free() * as well. * - * Returns: the name of @object. g_free() after usage. + * Free-function: g_free + * + * Returns: (transfer full): the name of @object. g_free() after usage. * * MT safe. This function grabs and releases @object's LOCK. */ @@ -875,8 +879,8 @@ had_parent: * Returns the parent of @object. This function increases the refcount * of the parent object so you should gst_object_unref() it after usage. * - * Returns: parent of @object, this can be NULL if @object has no - * parent. unref after usage. + * Returns: (transfer full): parent of @object, this can be NULL if @object + * has no parent. unref after usage. * * MT safe. Grabs and releases @object's LOCK. */ @@ -965,7 +969,8 @@ gst_object_has_ancestor (GstObject * object, GstObject * ancestor) /** * gst_object_check_uniqueness: - * @list: a list of #GstObject to check through + * @list: (transfer none) (element-type Gst.Object): a list of #GstObject to + * check through * @name: the name to search for * * Checks to see if there is any object named @name in @list. This function @@ -1107,7 +1112,9 @@ gst_object_get_property (GObject * object, guint prop_id, * Generates a string describing the path of @object in * the object hierarchy. Only useful (or used) for debugging. * - * Returns: a string describing the path of @object. You must + * Free-function: g_free + * + * Returns: (transfer full): a string describing the path of @object. You must * g_free() the string after usage. * * MT safe. Grabs and releases the #GstObject's LOCK for all objects diff --git a/gst/gstpad.c b/gst/gstpad.c index be66607967..9c46704c64 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -529,7 +529,7 @@ gst_pad_get_property (GObject * object, guint prop_id, * will be assigned. * This function makes a copy of the name so you can safely free the name. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. * * MT safe. */ @@ -550,7 +550,7 @@ gst_pad_new (const gchar * name, GstPadDirection direction) * will be assigned. * This function makes a copy of the name so you can safely free the name. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. */ GstPad * gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name) @@ -571,7 +571,7 @@ gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name) * will be assigned. * This function makes a copy of the name so you can safely free the name. * - * Returns: a new #GstPad, or NULL in case of an error. + * Returns: (transfer full): a new #GstPad, or NULL in case of an error. */ GstPad * gst_pad_new_from_static_template (GstStaticPadTemplate * templ, @@ -1019,7 +1019,7 @@ gst_pad_is_active (GstPad * pad) * @blocked: boolean indicating whether the pad should be blocked or unblocked * @callback: #GstPadBlockCallback that will be called when the * operation succeeds - * @user_data: user data passed to the callback + * @user_data: (closure): user data passed to the callback * @destroy_data: #GDestroyNotify for user_data * * Blocks or unblocks the dataflow on a pad. The provided callback @@ -1115,7 +1115,7 @@ had_right_state: * @blocked: boolean indicating whether the pad should be blocked or unblocked * @callback: #GstPadBlockCallback that will be called when the * operation succeeds - * @user_data: user data passed to the callback + * @user_data: (closure): user data passed to the callback * * Blocks or unblocks the dataflow on a pad. The provided callback * is called when the operation succeeds; this happens right before the next @@ -1422,7 +1422,8 @@ gst_pad_set_query_type_function (GstPad * pad, * Get an array of supported queries that can be performed * on this pad. * - * Returns: a zero-terminated array of #GstQueryType. + * Returns: (transfer none) (array zero-terminated=1): a zero-terminated array + * of #GstQueryType. */ const GstQueryType * gst_pad_get_query_types (GstPad * pad) @@ -1457,8 +1458,9 @@ gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data) * Invoke the default dispatcher for the query types on * the pad. * - * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the - * internally-linked pads has a query types function. + * Returns: (transfer none) (array zero-terminated=1): a zero-terminated array + * of #GstQueryType, or NULL if none of the internally-linked pads has a + * query types function. */ const GstQueryType * gst_pad_get_query_types_default (GstPad * pad) @@ -2182,8 +2184,8 @@ gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ) * * Gets the template for @pad. * - * Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL - * if this pad has no template. + * Returns: (transfer none): the #GstPadTemplate from which this pad was + * instantiated, or %NULL if this pad has no template. * * FIXME: currently returns an unrefcounted padtemplate. */ @@ -2281,7 +2283,7 @@ done: * Gets the capabilities this pad can produce or consume. Preferred function if * one only wants to read or intersect the caps. * - * Returns: the caps of the pad with incremented ref-count. + * Returns: (transfer full): the caps of the pad with incremented ref-count. * * Since: 0.10.26 */ @@ -2314,7 +2316,7 @@ gst_pad_get_caps_reffed (GstPad * pad) * the pad's get_caps function; * this returns the pad template caps if not explicitly set. * - * Returns: a newly allocated copy of the #GstCaps of this pad. + * Returns: (transfer full): a newly allocated copy of the #GstCaps of this pad * * MT safe. */ @@ -2340,7 +2342,7 @@ gst_pad_get_caps (GstPad * pad) * Gets the capabilities of the peer connected to this pad. Preferred function * if one only wants to read or intersect the caps. * - * Returns: the caps of the pad with incremented ref-count. + * Returns: (transfer full): the caps of the pad with incremented ref-count * * Since: 0.10.26 */ @@ -2383,9 +2385,9 @@ no_peer: * Gets the capabilities of the peer connected to this pad. Similar to * gst_pad_get_caps(). * - * Returns: a newly allocated copy of the #GstCaps of the peer pad. Use - * gst_caps_unref() to get rid of it. This function returns %NULL if there is - * no peer pad. + * Returns: (transfer full): a newly allocated copy of the #GstCaps of the + * peer pad. Use gst_caps_unref() to get rid of it. This function + * returns %NULL if there is no peer pad. */ GstCaps * gst_pad_peer_get_caps (GstPad * pad) @@ -2649,7 +2651,7 @@ no_peer: /** * gst_pad_set_caps: * @pad: a #GstPad to set the capabilities of. - * @caps: a #GstCaps to set. + * @caps: (transfer none): a #GstCaps to set. * * Sets the capabilities of this pad. The caps must be fixed. Any previous * caps on the pad will be unreffed. This function refs the caps so you should @@ -2792,8 +2794,8 @@ not_accepted: * * Gets the capabilities for @pad's template. * - * Returns: the #GstCaps of this pad template. If you intend to keep a - * reference on the caps, make a copy (see gst_caps_copy ()). + * Returns: (transfer none): the #GstCaps of this pad template. If you intend + * to keep a reference on the caps, make a copy (see gst_caps_copy ()). */ const GstCaps * gst_pad_get_pad_template_caps (GstPad * pad) @@ -2815,7 +2817,7 @@ gst_pad_get_pad_template_caps (GstPad * pad) * Gets the peer of @pad. This function refs the peer pad so * you need to unref it after use. * - * Returns: the peer #GstPad. Unref after usage. + * Returns: (transfer full): the peer #GstPad. Unref after usage. * * MT safe. */ @@ -2846,8 +2848,9 @@ gst_pad_get_peer (GstPad * pad) * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference * on the resulting caps. * - * Returns: the allowed #GstCaps of the pad link. Unref the caps when you no - * longer need it. This function returns NULL when @pad has no peer. + * Returns: (transfer full): the allowed #GstCaps of the pad link. Unref the + * caps when you no longer need it. This function returns NULL when @pad + * has no peer. * * MT safe. */ @@ -2905,9 +2908,9 @@ no_peer: * always negotiated before sinkpads so it is possible that the negotiated caps * on the srcpad do not match the negotiated caps of the peer. * - * Returns: the negotiated #GstCaps of the pad link. Unref the caps when - * you no longer need it. This function returns NULL when the @pad has no - * peer or is not negotiated yet. + * Returns: (transfer full): the negotiated #GstCaps of the pad link. Unref + * the caps when you no longer need it. This function returns NULL when + * the @pad has no peer or is not negotiated yet. * * MT safe. */ @@ -3174,8 +3177,8 @@ gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps, * @pad: a source #GstPad * @offset: the offset of the new buffer in the stream * @size: the size of the new buffer - * @caps: the caps of the new buffer - * @buf: a newly allocated buffer + * @caps: (transfer none): the caps of the new buffer + * @buf: (out callee-allocates): a newly allocated buffer * * In addition to the function gst_pad_alloc_buffer(), this function * automatically calls gst_pad_set_caps() when the caps of the @@ -3331,8 +3334,11 @@ no_parent: * Each #GstPad element yielded by the iterator will have its refcount increased, * so unref after use. * - * Returns: a new #GstIterator of #GstPad or %NULL when the pad does not have an - * iterator function configured. Use gst_iterator_free() after usage. + * Free-function: gst_iterator_free + * + * Returns: (transfer full): a new #GstIterator of #GstPad or %NULL when the + * pad does not have an iterator function configured. Use + * gst_iterator_free() after usage. * * Since: 0.10.21 */ @@ -3369,7 +3375,8 @@ add_unref_pad_to_list (GstPad * pad, GList ** list) * * The caller must free this list after use with g_list_free(). * - * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent. + * Returns: (transfer full) (element-type Gst.Pad): a newly allocated #GList + * of pads, or NULL if the pad has no parent. * * Not MT safe. * @@ -3466,7 +3473,8 @@ no_parent: * * Not MT safe. * - * Returns: a newly allocated #GList of pads, free with g_list_free(). + * Returns: (transfer full) (element-type Gst.Pad): a newly allocated #GList + * of pads, free with g_list_free(). * * Deprecated: This function does not ref the pads in the list so that they * could become invalid by the time the application accesses them. It's also @@ -3584,7 +3592,7 @@ no_iter: /** * gst_pad_event_default: * @pad: a #GstPad to call the default event handler on. - * @event: the #GstEvent to handle. + * @event: (transfer full): the #GstEvent to handle. * * Invokes the default event handler for the given pad. End-of-stream and * discontinuity events are handled specially, and then the event is sent to all @@ -3620,7 +3628,7 @@ gst_pad_event_default (GstPad * pad, GstEvent * event) * gst_pad_dispatcher: * @pad: a #GstPad to dispatch. * @dispatch: the #GstPadDispatcherFunction to call. - * @data: gpointer user data passed to the dispatcher function. + * @data: (closure): gpointer user data passed to the dispatcher function. * * Invokes the given dispatcher function on each respective peer of * all pads that are internally linked to the given pad. @@ -3688,7 +3696,7 @@ no_iter: /** * gst_pad_query: * @pad: a #GstPad to invoke the default query on. - * @query: the #GstQuery to perform. + * @query: (transfer none): the #GstQuery to perform. * * Dispatches a query to a pad. The query should have been allocated by the * caller via one of the type-specific allocation functions. The element that @@ -3728,7 +3736,7 @@ no_func: /** * gst_pad_peer_query: * @pad: a #GstPad to invoke the peer query on. - * @query: the #GstQuery to perform. + * @query: (transfer none): the #GstQuery to perform. * * Performs gst_pad_query() on the peer of @pad. * @@ -3778,7 +3786,7 @@ no_peer: /** * gst_pad_query_default: * @pad: a #GstPad to call the default query handler on. - * @query: the #GstQuery to handle. + * @query: (transfer none): the #GstQuery to handle. * * Invokes the default query handler for the given pad. * The query is sent to all pads internally linked to @pad. Note that @@ -4322,7 +4330,8 @@ no_function: /** * gst_pad_chain: * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. - * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not. + * @buffer: (transfer full): the #GstBuffer to send, return GST_FLOW_ERROR + * if not. * * Chain a buffer to @pad. * @@ -4358,7 +4367,8 @@ gst_pad_chain (GstPad * pad, GstBuffer * buffer) /** * gst_pad_chain_list: * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. - * @list: the #GstBufferList to send, return GST_FLOW_ERROR if not. + * @list: (transfer full): the #GstBufferList to send, return GST_FLOW_ERROR + * if not. * * Chain a bufferlist to @pad. * @@ -4594,7 +4604,8 @@ _priv_gst_pad_invalidate_cache (GstPad * pad) /** * gst_pad_push: * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not. - * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not. + * @buffer: (transfer full): the #GstBuffer to push returns GST_FLOW_ERROR + * if not. * * Pushes a buffer to the peer of @pad. * @@ -4691,7 +4702,8 @@ slow_path: /** * gst_pad_push_list: * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not. - * @list: the #GstBufferList to push returns GST_FLOW_ERROR if not. + * @list: (transfer full): the #GstBufferList to push returns GST_FLOW_ERROR + * if not. * * Pushes a buffer list to the peer of @pad. * @@ -4965,7 +4977,8 @@ not_negotiated: * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not. * @offset: The start offset of the buffer * @size: The length of the buffer - * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL. + * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer, + * returns #GST_FLOW_ERROR if %NULL. * * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE * immediatly and @buffer is %NULL. @@ -4997,7 +5010,8 @@ gst_pad_get_range (GstPad * pad, guint64 offset, guint size, * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not. * @offset: The start offset of the buffer * @size: The length of the buffer - * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL. + * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer, returns + * GST_FLOW_ERROR if %NULL. * * Pulls a @buffer from the peer pad. * @@ -5115,7 +5129,7 @@ not_negotiated: /** * gst_pad_push_event: * @pad: a #GstPad to push the event to. - * @event: the #GstEvent to send to the pad. + * @event: (transfer full): the #GstEvent to send to the pad. * * Sends the event to the peer of the given pad. This function is * mainly used by elements to send events to their peer @@ -5236,7 +5250,7 @@ flushed: /** * gst_pad_send_event: * @pad: a #GstPad to send the event to. - * @event: the #GstEvent to send to the pad. + * @event: (transfer full): the #GstEvent to send to the pad. * * Sends the event to the pad. This function can be used * by applications to send events in the pipeline. diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c index df1ff7a8aa..ca2f949653 100644 --- a/gst/gstpadtemplate.c +++ b/gst/gstpadtemplate.c @@ -307,7 +307,7 @@ gst_static_pad_template_get_type (void) * * Converts a #GstStaticPadTemplate into a #GstPadTemplate. * - * Returns: a new #GstPadTemplate. + * Returns: (transfer full): a new #GstPadTemplate. */ /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */ GstPadTemplate * @@ -337,13 +337,14 @@ gst_static_pad_template_get (GstStaticPadTemplate * pad_template) * @name_template: the name template. * @direction: the #GstPadDirection of the template. * @presence: the #GstPadPresence of the pad. - * @caps: a #GstCaps set for the template. The caps are taken ownership of. + * @caps: (transfer full): a #GstCaps set for the template. The caps are + * taken ownership of. * * Creates a new pad template with a name according to the given template * and with the given arguments. This functions takes ownership of the provided * caps, so be sure to not use them afterwards. * - * Returns: a new #GstPadTemplate. + * Returns: (transfer full): a new #GstPadTemplate. */ GstPadTemplate * gst_pad_template_new (const gchar * name_template, @@ -378,7 +379,7 @@ gst_pad_template_new (const gchar * name_template, * * Gets the capabilities of the static pad template. * - * Returns: the #GstCaps of the static pad template. + * Returns: (transfer full): the #GstCaps of the static pad template. * Unref after usage. Since the core holds an additional * ref to the returned caps, use gst_caps_make_writable() * on the returned caps to modify it. @@ -397,8 +398,8 @@ gst_static_pad_template_get_caps (GstStaticPadTemplate * templ) * * Gets the capabilities of the pad template. * - * Returns: the #GstCaps of the pad template. If you need to keep a reference to - * the caps, take a ref (see gst_caps_ref ()). + * Returns: (transfer none): the #GstCaps of the pad template. If you need to + * keep a reference to the caps, take a ref (see gst_caps_ref ()). */ GstCaps * gst_pad_template_get_caps (GstPadTemplate * templ) diff --git a/gst/gstparse.c b/gst/gstparse.c index 97ec15af89..cc420abe60 100644 --- a/gst/gstparse.c +++ b/gst/gstparse.c @@ -68,8 +68,10 @@ gst_parse_error_quark (void) * Allocates a parse context for use with gst_parse_launch_full() or * gst_parse_launchv_full(). * - * Returns: a newly-allocated parse context. Free with gst_parse_context_free() - * when no longer needed. + * Free-function: gst_parse_context_free + * + * Returns: (transfer full): a newly-allocated parse context. Free with + * gst_parse_context_free() when no longer needed. * * Since: 0.10.20 */ @@ -90,7 +92,7 @@ gst_parse_context_new (void) /** * gst_parse_context_free: - * @context: a #GstParseContext + * @context: (transfer full): a #GstParseContext * * Frees a parse context previously allocated with gst_parse_context_new(). * @@ -116,8 +118,9 @@ gst_parse_context_free (GstParseContext * context) * or gst_parse_launchv_full(). Will only return results if an error code * of %GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned. * - * Returns: a NULL-terminated array of element factory name strings of - * missing elements. Free with g_strfreev() when no longer needed. + * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*): a + * NULL-terminated array of element factory name strings of missing + * elements. Free with g_strfreev() when no longer needed. * * Since: 0.10.20 */ @@ -172,14 +175,14 @@ _gst_parse_escape (const gchar * str) /** * gst_parse_launchv: - * @argv: null-terminated array of arguments + * @argv: (in) (array zero-terminated=1): null-terminated array of arguments * @error: pointer to a #GError * * Create a new element based on command line syntax. * @error will contain an error message if an erroneuos pipeline is specified. * An error does not mean that the pipeline could not be constructed. * - * Returns: a new element on success and %NULL on failure. + * Returns: (transfer full): a new element on success and %NULL on failure. */ GstElement * gst_parse_launchv (const gchar ** argv, GError ** error) @@ -189,8 +192,9 @@ gst_parse_launchv (const gchar ** argv, GError ** error) /** * gst_parse_launchv_full: - * @argv: null-terminated array of arguments - * @context: a parse context allocated with gst_parse_context_new(), or %NULL + * @argv: (in) (array zero-terminated=1): null-terminated array of arguments + * @context: (allow-none): a parse context allocated with + * gst_parse_context_new(), or %NULL * @flags: parsing options, or #GST_PARSE_FLAG_NONE * @error: pointer to a #GError (which must be initialised to %NULL) * @@ -198,10 +202,10 @@ gst_parse_launchv (const gchar ** argv, GError ** error) * @error will contain an error message if an erroneous pipeline is specified. * An error does not mean that the pipeline could not be constructed. * - * Returns: a new element on success; on failure, either %NULL or a - * partially-constructed bin or element will be returned and @error will be set - * (unless you passed #GST_PARSE_FLAG_FATAL_ERRORS in @flags, then %NULL will - * always be returned on failure) + * Returns: (transfer full): a new element on success; on failure, either %NULL + * or a partially-constructed bin or element will be returned and @error will + * be set (unless you passed #GST_PARSE_FLAG_FATAL_ERRORS in @flags, then + * %NULL will always be returned on failure) * * Since: 0.10.20 */ @@ -252,9 +256,9 @@ gst_parse_launchv_full (const gchar ** argv, GstParseContext * context, * the @error is set. In this case there was a recoverable parsing error and you * can try to play the pipeline. * - * Returns: a new element on success, %NULL on failure. If more than one toplevel - * element is specified by the @pipeline_description, all elements are put into - * a #GstPipeline, which than is returned. + * Returns: (transfer full): a new element on success, %NULL on failure. If + * more than one toplevel element is specified by the @pipeline_description, + * all elements are put into a #GstPipeline, which than is returned. */ GstElement * gst_parse_launch (const gchar * pipeline_description, GError ** error) @@ -265,7 +269,8 @@ gst_parse_launch (const gchar * pipeline_description, GError ** error) /** * gst_parse_launch_full: * @pipeline_description: the command line describing the pipeline - * @context: a parse context allocated with gst_parse_context_new(), or %NULL + * @context: (allow-none): a parse context allocated with + * gst_parse_context_new(), or %NULL * @flags: parsing options, or #GST_PARSE_FLAG_NONE * @error: the error message in case of an erroneous pipeline. * @@ -274,9 +279,9 @@ gst_parse_launch (const gchar * pipeline_description, GError ** error) * the @error is set. In this case there was a recoverable parsing error and you * can try to play the pipeline. * - * Returns: a new element on success, %NULL on failure. If more than one toplevel - * element is specified by the @pipeline_description, all elements are put into - * a #GstPipeline, which then is returned. + * Returns: (transfer full): a new element on success, %NULL on failure. If + * more than one toplevel element is specified by the @pipeline_description, + * all elements are put into a #GstPipeline, which then is returned. * * Since: 0.10.20 */ diff --git a/gst/gstpipeline.c b/gst/gstpipeline.c index 1458bcab3e..d80a38aa13 100644 --- a/gst/gstpipeline.c +++ b/gst/gstpipeline.c @@ -310,7 +310,7 @@ reset_start_time (GstPipeline * pipeline) * * Create a new pipeline with the given name. * - * Returns: newly created GstPipeline + * Returns: (transfer full): newly created GstPipeline * * MT safe. */ @@ -594,7 +594,7 @@ gst_pipeline_handle_message (GstBin * bin, GstMessage * message) * Gets the #GstBus of @pipeline. The bus allows applications to receive * #GstMessage packets. * - * Returns: a #GstBus, unref after usage. + * Returns: (transfer full): a #GstBus, unref after usage. * * MT safe. */ @@ -720,7 +720,7 @@ gst_pipeline_provide_clock_func (GstElement * element) * * Gets the current clock used by @pipeline. * - * Returns: a #GstClock, unref after usage. + * Returns: (transfer full): a #GstClock, unref after usage. */ GstClock * gst_pipeline_get_clock (GstPipeline * pipeline) @@ -734,7 +734,7 @@ gst_pipeline_get_clock (GstPipeline * pipeline) /** * gst_pipeline_use_clock: * @pipeline: a #GstPipeline - * @clock: the clock to use + * @clock: (transfer none): the clock to use * * Force @pipeline to use the given @clock. The pipeline will * always use the given clock even if new clock providers are added @@ -766,7 +766,7 @@ gst_pipeline_use_clock (GstPipeline * pipeline, GstClock * clock) /** * gst_pipeline_set_clock: * @pipeline: a #GstPipeline - * @clock: the clock to set + * @clock: (transfer none): the clock to set * * Set the clock for @pipeline. The clock will be distributed * to all the elements managed by the pipeline. diff --git a/gst/gstplugin.c b/gst/gstplugin.c index 2ee87511e0..f823a3b0ca 100644 --- a/gst/gstplugin.c +++ b/gst/gstplugin.c @@ -1025,8 +1025,8 @@ gst_plugin_get_origin (GstPlugin * plugin) * Gets the #GModule of the plugin. If the plugin isn't loaded yet, NULL is * returned. * - * Returns: module belonging to the plugin or NULL if the plugin isn't - * loaded yet. + * Returns: (transfer none): module belonging to the plugin or NULL if the + * plugin isn't loaded yet. */ GModule * gst_plugin_get_module (GstPlugin * plugin) @@ -1059,7 +1059,7 @@ gst_plugin_is_loaded (GstPlugin * plugin) * Gets the plugin specific data cache. If it is %NULL there is no cached data * stored. This is the case when the registry is getting rebuilt. * - * Returns: The cached data as a #GstStructure or %NULL. + * Returns: (transfer none): The cached data as a #GstStructure or %NULL. * * Since: 0.10.24 */ @@ -1074,7 +1074,7 @@ gst_plugin_get_cache_data (GstPlugin * plugin) /** * gst_plugin_set_cache_data: * @plugin: a plugin - * @cache_data: a structure containing the data to cache + * @cache_data: (transfer full): a structure containing the data to cache * * Adds plugin specific data to cache. Passes the ownership of the structure to * the @plugin. @@ -1281,7 +1281,7 @@ gst_plugin_find_feature_by_name (GstPlugin * plugin, const gchar * name) * * Load the named plugin. Refs the plugin. * - * Returns: A reference to a loaded plugin, or NULL on error. + * Returns: (transfer full): a reference to a loaded plugin, or NULL on error. */ GstPlugin * gst_plugin_load_by_name (const gchar * name) @@ -1311,7 +1311,7 @@ gst_plugin_load_by_name (const gchar * name) /** * gst_plugin_load: - * @plugin: plugin to load + * @plugin: (transfer none): plugin to load * * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is * untouched. The normal use pattern of this function goes like this: @@ -1324,7 +1324,7 @@ gst_plugin_load_by_name (const gchar * name) * plugin = loaded_plugin; * </programlisting> * - * Returns: A reference to a loaded plugin, or NULL on error. + * Returns: (transfer full): a reference to a loaded plugin, or NULL on error. */ GstPlugin * gst_plugin_load (GstPlugin * plugin) @@ -1351,7 +1351,7 @@ load_error: /** * gst_plugin_list_free: - * @list: list of #GstPlugin + * @list: (transfer full) (element-type Gst.Plugin): list of #GstPlugin * * Unrefs each member of @list, then frees the list. */ diff --git a/gst/gstpluginfeature.c b/gst/gstpluginfeature.c index 0c19b6a90c..2c44034bf5 100644 --- a/gst/gstpluginfeature.c +++ b/gst/gstpluginfeature.c @@ -72,7 +72,7 @@ gst_plugin_feature_finalize (GObject * object) /** * gst_plugin_feature_load: - * @feature: the plugin feature to check + * @feature: (transfer none): the plugin feature to check * * Loads the plugin containing @feature if it's not already loaded. @feature is * unaffected; use the return value instead. @@ -87,7 +87,7 @@ gst_plugin_feature_finalize (GObject * object) * feature = loaded_feature; * ]| * - * Returns: A reference to the loaded feature, or NULL on error. + * Returns: (transfer full): a reference to the loaded feature, or NULL on error */ GstPluginFeature * gst_plugin_feature_load (GstPluginFeature * feature) @@ -146,7 +146,7 @@ not_found: /** * gst_plugin_feature_type_name_filter: * @feature: the #GstPluginFeature - * @data: the type and name to check against + * @data: (in): the type and name to check against * * Compares type and name of plugin feature. Can be used with gst_filter_run(). * @@ -238,7 +238,8 @@ gst_plugin_feature_get_rank (GstPluginFeature * feature) /** * gst_plugin_feature_list_free: - * @list: list of #GstPluginFeature + * @list: (transfer full) (element-type Gst.PluginFeature): list + * of #GstPluginFeature * * Unrefs each member of @list, then frees the list. */ @@ -257,12 +258,14 @@ gst_plugin_feature_list_free (GList * list) /** * gst_plugin_feature_list_copy: - * @list: list of #GstPluginFeature + * @list: (transfer none) (element-type Gst.PluginFeature): list + * of #GstPluginFeature * * Copies the list of features. Caller should call @gst_plugin_feature_list_free * when done with the list. * - * Returns: a copy of @list, with each feature's reference count incremented. + * Returns: (transfer full) (element-type Gst.PluginFeature): a copy of @list, + * with each feature's reference count incremented. * * Since: 0.10.26 */ @@ -294,7 +297,8 @@ gst_plugin_feature_list_copy (GList * list) /** * gst_plugin_feature_list_debug: - * @list: a #GList of plugin features + * @list: (transfer none) (element-type Gst.PluginFeature): a #GList of + * plugin features * * Debug the plugin feature names in @list. * diff --git a/gst/gstpoll.c b/gst/gstpoll.c index 95ce83d4a2..af34f66198 100644 --- a/gst/gstpoll.c +++ b/gst/gstpoll.c @@ -533,8 +533,10 @@ gst_poll_collect_winsock_events (GstPoll * set) * is possible to restart or flush a call to gst_poll_wait() with * gst_poll_restart() and gst_poll_set_flushing() respectively. * - * Returns: a new #GstPoll, or %NULL in case of an error. Free with - * gst_poll_free(). + * Free-function: gst_poll_free + * + * Returns: (transfer full): a new #GstPoll, or %NULL in case of an error. + * Free with gst_poll_free(). * * Since: 0.10.18 */ @@ -603,8 +605,10 @@ no_socket_pair: * A timeout is performed with gst_poll_wait(). Multiple timeouts can be * performed from different threads. * - * Returns: a new #GstPoll, or %NULL in case of an error. Free with - * gst_poll_free(). + * Free-function: gst_poll_free + * + * Returns: (transfer full): a new #GstPoll, or %NULL in case of an error. + * Free with gst_poll_free(). * * Since: 0.10.23 */ @@ -626,7 +630,7 @@ done: /** * gst_poll_free: - * @set: a file descriptor set. + * @set: (transfer full): a file descriptor set. * * Free a file descriptor set. * diff --git a/gst/gstpreset.c b/gst/gstpreset.c index 3dced42722..d566065734 100644 --- a/gst/gstpreset.c +++ b/gst/gstpreset.c @@ -867,7 +867,8 @@ no_presets: * * Get a copy of preset names as a NULL terminated string array. * - * Returns: list with names, ue g_strfreev() after usage. + * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*): + * list with names, ue g_strfreev() after usage. * * Since: 0.10.20 */ @@ -885,7 +886,8 @@ gst_preset_get_preset_names (GstPreset * preset) * * Get a the names of the GObject properties that can be used for presets. * - * Returns: an array of property names which should be freed with g_strfreev() after use. + * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*): an + * array of property names which should be freed with g_strfreev() after use. * * Since: 0.10.20 */ @@ -1014,7 +1016,7 @@ gst_preset_set_meta (GstPreset * preset, const gchar * name, const gchar * tag, * @preset: a #GObject that implements #GstPreset * @name: preset name * @tag: meta data item name - * @value: value + * @value: (out callee-allocates): value * * Gets the @value for an existing meta data @tag. Meta data @tag names can be * something like e.g. "comment". Returned values need to be released when done. diff --git a/gst/gstquery.c b/gst/gstquery.c index 6c1596525c..9373175cae 100644 --- a/gst/gstquery.c +++ b/gst/gstquery.c @@ -334,7 +334,9 @@ gst_query_type_get_details (GstQueryType type) * Get a #GstIterator of all the registered query types. The definitions * iterated over are read only. * - * Returns: A #GstIterator of #GstQueryTypeDefinition. + * Free-function: gst_iterator_free + * + * Returns: (transfer full): a #GstIterator of #GstQueryTypeDefinition. */ GstIterator * gst_query_type_iterate_definitions (void) @@ -381,7 +383,9 @@ gst_query_new (GstQueryType type, GstStructure * structure) * when done with it. A position query is used to query the current position * of playback in the streams, in some format. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery */ GstQuery * gst_query_new_position (GstFormat format) @@ -419,8 +423,9 @@ gst_query_set_position (GstQuery * query, GstFormat format, gint64 cur) /** * gst_query_parse_position: * @query: a #GstQuery - * @format: (out): the storage for the #GstFormat of the position values (may be NULL) - * @cur: (out): the storage for the current position (may be NULL) + * @format: (out) (allow-none): the storage for the #GstFormat of the + * position values (may be NULL) + * @cur: (out) (allow-none): the storage for the current position (may be NULL) * * Parse a position query, writing the format into @format, and the position * into @cur, if the respective parameters are non-NULL. @@ -450,7 +455,9 @@ gst_query_parse_position (GstQuery * query, GstFormat * format, gint64 * cur) * Use gst_query_unref() when done with it. A duration query will give the * total length of the stream. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery */ GstQuery * gst_query_new_duration (GstFormat format) @@ -488,8 +495,9 @@ gst_query_set_duration (GstQuery * query, GstFormat format, gint64 duration) /** * gst_query_parse_duration: * @query: a #GstQuery - * @format: (out): the storage for the #GstFormat of the duration value, or NULL. - * @duration: (out): the storage for the total duration, or NULL. + * @format: (out) (allow-none): the storage for the #GstFormat of the duration + * value, or NULL. + * @duration: (out) (allow-none): the storage for the total duration, or NULL. * * Parse a duration query answer. Write the format of the duration into @format, * and the value into @duration, if the respective variables are non-NULL. @@ -519,7 +527,9 @@ gst_query_parse_duration (GstQuery * query, GstFormat * format, * by sinks to compensate for additional latency introduced by elements in the * pipeline. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a #GstQuery * * Since: 0.10.12 */ @@ -565,9 +575,9 @@ gst_query_set_latency (GstQuery * query, gboolean live, /** * gst_query_parse_latency: * @query: a #GstQuery - * @live: (out): storage for live or NULL - * @min_latency: (out): the storage for the min latency or NULL - * @max_latency: (out): the storage for the max latency or NULL + * @live: (out) (allow-none): storage for live or NULL + * @min_latency: (out) (allow-none): the storage for the min latency or NULL + * @max_latency: (out) (allow-none): the storage for the max latency or NULL * * Parse a latency query answer. * @@ -604,7 +614,9 @@ gst_query_parse_latency (GstQuery * query, gboolean * live, * when done with it. A convert query is used to ask for a conversion between * one format and another. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a #GstQuery */ GstQuery * gst_query_new_convert (GstFormat src_format, gint64 value, @@ -650,10 +662,13 @@ gst_query_set_convert (GstQuery * query, GstFormat src_format, gint64 src_value, /** * gst_query_parse_convert: * @query: a #GstQuery - * @src_format: (out): the storage for the #GstFormat of the source value, or NULL - * @src_value: (out): the storage for the source value, or NULL - * @dest_format: (out): the storage for the #GstFormat of the destination value, or NULL - * @dest_value: (out): the storage for the destination value, or NULL + * @src_format: (out) (allow-none): the storage for the #GstFormat of the + * source value, or NULL + * @src_value: (out) (allow-none): the storage for the source value, or NULL + * @dest_format: (out) (allow-none): the storage for the #GstFormat of the + * destination value, or NULL + * @dest_value: (out) (allow-none): the storage for the destination value, + * or NULL * * Parse a convert query answer. Any of @src_format, @src_value, @dest_format, * and @dest_value may be NULL, in which case that value is omitted. @@ -689,7 +704,9 @@ gst_query_parse_convert (GstQuery * query, GstFormat * src_format, * when done with it. A segment query is used to discover information about the * currently configured segment for playback. * - * Returns: a #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery */ GstQuery * gst_query_new_segment (GstFormat format) @@ -744,10 +761,11 @@ gst_query_set_segment (GstQuery * query, gdouble rate, GstFormat format, /** * gst_query_parse_segment: * @query: a #GstQuery - * @rate: (out): the storage for the rate of the segment, or NULL - * @format: (out): the storage for the #GstFormat of the values, or NULL - * @start_value: (out): the storage for the start value, or NULL - * @stop_value: (out): the storage for the stop value, or NULL + * @rate: (out) (allow-none): the storage for the rate of the segment, or NULL + * @format: (out) (allow-none): the storage for the #GstFormat of the values, + * or NULL + * @start_value: (out) (allow-none): the storage for the start value, or NULL + * @stop_value: (out) (allow-none): the storage for the stop value, or NULL * * Parse a segment query answer. Any of @rate, @format, @start_value, and * @stop_value may be NULL, which will cause this value to be omitted. @@ -785,7 +803,9 @@ gst_query_parse_segment (GstQuery * query, gdouble * rate, GstFormat * format, * Constructs a new custom application query object. Use gst_query_unref() * when done with it. * - * Returns: a #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery */ GstQuery * gst_query_new_application (GstQueryType type, GstStructure * structure) @@ -802,8 +822,9 @@ gst_query_new_application (GstQueryType type, GstStructure * structure) * * Get the structure of a query. * - * Returns: The #GstStructure of the query. The structure is still owned - * by the query and will therefore be freed when the query is unreffed. + * Returns: (transfer none): the #GstStructure of the query. The structure is + * still owned by the query and will therefore be freed when the query + * is unreffed. */ GstStructure * gst_query_get_structure (GstQuery * query) @@ -820,7 +841,9 @@ gst_query_get_structure (GstQuery * query) * Constructs a new query object for querying seeking properties of * the stream. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery */ GstQuery * gst_query_new_seeking (GstFormat format) @@ -865,10 +888,11 @@ gst_query_set_seeking (GstQuery * query, GstFormat format, /** * gst_query_parse_seeking: * @query: a GST_QUERY_SEEKING type query #GstQuery - * @format: (out): the format to set for the @segment_start and @segment_end values - * @seekable: (out): the seekable flag to set - * @segment_start: (out): the segment_start to set - * @segment_end: (out): the segment_end to set + * @format: (out) (allow-none): the format to set for the @segment_start + * and @segment_end values, or NULL + * @seekable: (out) (allow-none): the seekable flag to set, or NULL + * @segment_start: (out) (allow-none): the segment_start to set, or NULL + * @segment_end: (out) (allow-none): the segment_end to set, or NULL * * Parse a seeking query, writing the format into @format, and * other results into the passed parameters, if the respective parameters @@ -903,7 +927,9 @@ gst_query_parse_seeking (GstQuery * query, GstFormat * format, * Constructs a new query object for querying formats of * the stream. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery * * Since: 0.10.4 */ @@ -966,7 +992,8 @@ gst_query_set_formats (GstQuery * query, gint n_formats, ...) * gst_query_set_formatsv: * @query: a #GstQuery * @n_formats: the number of formats to set. - * @formats: An array containing @n_formats @GstFormat values. + * @formats: (in) (array length=n_formats): an array containing @n_formats + * @GstFormat values. * * Set the formats query result fields in @query. The number of formats passed * in the @formats array must be equal to @n_formats. @@ -1054,7 +1081,9 @@ gst_query_parse_formats_nth (GstQuery * query, guint nth, GstFormat * format) * Constructs a new query object for querying the buffering status of * a stream. * - * Returns: A #GstQuery + * Free-function: gst_query_new + * + * Returns: (transfer full): a new #GstQuery * * Since: 0.10.20 */ @@ -1108,8 +1137,8 @@ gst_query_set_buffering_percent (GstQuery * query, gboolean busy, gint percent) /** * gst_query_parse_buffering_percent * @query: A valid #GstQuery of type GST_QUERY_BUFFERING. - * @busy: (out): if buffering is busy - * @percent: (out): a buffering percent + * @busy: (out) (allow-none): if buffering is busy, or NULL + * @percent: (out) (allow-none): a buffering percent, or NULL * * Get the percentage of buffered data. This is a value between 0 and 100. * The @busy indicator is %TRUE when the buffering is in progress. @@ -1158,10 +1187,10 @@ gst_query_set_buffering_stats (GstQuery * query, GstBufferingMode mode, /** * gst_query_parse_buffering_stats: * @query: A valid #GstQuery of type GST_QUERY_BUFFERING. - * @mode: (out): a buffering mode - * @avg_in: (out): the average input rate - * @avg_out: (out): the average output rate - * @buffering_left: (out): amount of buffering time left + * @mode: (out) (allow-none): a buffering mode, or NULL + * @avg_in: (out) (allow-none): the average input rate, or NULL + * @avg_out: (out) (allow-none): the average output rat, or NULLe + * @buffering_left: (out) (allow-none): amount of buffering time left, or NULL * * Extracts the buffering stats values from @query. * @@ -1218,10 +1247,12 @@ gst_query_set_buffering_range (GstQuery * query, GstFormat format, /** * gst_query_parse_buffering_range: * @query: a GST_QUERY_BUFFERING type query #GstQuery - * @format: (out): the format to set for the @segment_start and @segment_end values - * @start: (out): the start to set - * @stop: (out): the stop to set - * @estimated_total: (out): estimated total amount of download time + * @format: (out) (allow-none): the format to set for the @segment_start + * and @segment_end values, or NULL + * @start: (out) (allow-none): the start to set, or NULL + * @stop: (out) (allow-none): the stop to set, or NULL + * @estimated_total: (out) (allow-none): estimated total amount of download + * time, or NULL * * Parse an available query, writing the format into @format, and * other results into the passed parameters, if the respective parameters @@ -1344,8 +1375,8 @@ gst_query_get_n_buffering_ranges (GstQuery * query) * gst_query_parse_nth_buffering_range * @query: a GST_QUERY_BUFFERING type query #GstQuery * @index: position in the buffered-ranges array to read - * @start: (out): the start position to set - * @stop: (out): the stop position to set + * @start: (out) (allow-none): the start position to set, or NULL + * @stop: (out) (allow-none): the stop position to set, or NULL * * Parse an available query and get the start and stop values stored * at the @index of the buffered ranges array. @@ -1389,7 +1420,9 @@ gst_query_parse_nth_buffering_range (GstQuery * query, guint index, * when done with it. An URI query is used to query the current URI * that is used by the source or sink. * - * Returns: A #GstQuery + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new #GstQuery * * Since: 0.10.22 */ @@ -1429,7 +1462,8 @@ gst_query_set_uri (GstQuery * query, const gchar * uri) /** * gst_query_parse_uri: * @query: a #GstQuery - * @uri: (out): the storage for the current URI (may be NULL) + * @uri: (out callee-allocates) (allow-none): the storage for the current URI + * (may be NULL) * * Parse an URI query, writing the URI into @uri as a newly * allocated string, if the respective parameters are non-NULL. diff --git a/gst/gstquery.h b/gst/gstquery.h index 0284a29ce8..09d022574c 100644 --- a/gst/gstquery.h +++ b/gst/gstquery.h @@ -228,7 +228,9 @@ gst_query_unref (GstQuery * q) * * Copies the given query using the copy function of the parent #GstStructure. * - * Returns: a new copy of @q. + * Free-function: gst_query_unref + * + * Returns: (transfer full): a new copy of @q. */ #ifdef _FOOL_GTK_DOC_ G_INLINE_FUNC GstQuery * gst_query_copy (const GstQuery * q); @@ -242,9 +244,11 @@ gst_query_copy (const GstQuery * q) /** * gst_query_make_writable: - * @q: a #GstQuery to make writable + * @q: (transfer full): a #GstQuery to make writable * * Makes a writable query from the given query. + * + * Returns: (transfer full): a new writable query (possibly same as @q) */ #define gst_query_make_writable(q) GST_QUERY_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (q))) diff --git a/gst/gstregistry.c b/gst/gstregistry.c index de9f0d306d..6b4be1896a 100644 --- a/gst/gstregistry.c +++ b/gst/gstregistry.c @@ -310,7 +310,7 @@ gst_registry_finalize (GObject * object) * Retrieves the default registry. The caller does not own a reference on the * registry, as it is alive as long as GStreamer is initialized. * - * Returns: The default #GstRegistry. + * Returns: (transfer none): The default #GstRegistry. */ GstRegistry * gst_registry_get_default (void) @@ -375,7 +375,8 @@ was_added: * * Get the list of paths for the given registry. * - * Returns: A Glist of paths as strings. g_list_free after use. + * Returns: (transfer container) (element-type char*): A #GList of paths as + * strings. g_list_free after use. * * MT safe. */ @@ -399,7 +400,7 @@ gst_registry_get_path_list (GstRegistry * registry) /** * gst_registry_add_plugin: * @registry: the registry to add the plugin to - * @plugin: the plugin to add + * @plugin: (transfer full): the plugin to add * * Add the plugin to the registry. The plugin-added signal will be emitted. * This function will sink @plugin. @@ -484,7 +485,7 @@ gst_registry_remove_features_for_plugin_unlocked (GstRegistry * registry, /** * gst_registry_remove_plugin: * @registry: the registry to remove the plugin from - * @plugin: the plugin to remove + * @plugin: (transfer none): the plugin to remove * * Remove the plugin from the registry. * @@ -511,7 +512,7 @@ gst_registry_remove_plugin (GstRegistry * registry, GstPlugin * plugin) /** * gst_registry_add_feature: * @registry: the registry to add the plugin to - * @feature: the feature to add + * @feature: (transfer full): the feature to add * * Add the feature to the registry. The feature-added signal will be emitted. * This function sinks @feature. @@ -567,7 +568,7 @@ gst_registry_add_feature (GstRegistry * registry, GstPluginFeature * feature) /** * gst_registry_remove_feature: * @registry: the registry to remove the feature from - * @feature: the feature to remove + * @feature: (transfer none): the feature to remove * * Remove the feature from the registry. * @@ -595,7 +596,7 @@ gst_registry_remove_feature (GstRegistry * registry, GstPluginFeature * feature) * @registry: registry to query * @filter: the filter to use * @first: only return first match - * @user_data: user data passed to the filter function + * @user_data: (closure): user data passed to the filter function * * Runs a filter against all plugins in the registry and returns a #GList with * the results. If the first flag is set, only the first match is @@ -603,7 +604,8 @@ gst_registry_remove_feature (GstRegistry * registry, GstPluginFeature * feature) * Every plugin is reffed; use gst_plugin_list_free() after use, which * will unref again. * - * Returns: a #GList of #GstPlugin. Use gst_plugin_list_free() after usage. + * Returns: (transfer full) (element-type Gst.Plugin): a #GList of #GstPlugin. + * Use gst_plugin_list_free() after usage. * * MT safe. */ @@ -714,15 +716,15 @@ gst_registry_get_typefind_factory_list (GstRegistry * registry) * @registry: registry to query * @filter: the filter to use * @first: only return first match - * @user_data: user data passed to the filter function + * @user_data: (closure): user data passed to the filter function * * Runs a filter against all features of the plugins in the registry * and returns a GList with the results. * If the first flag is set, only the first match is * returned (as a list with a single object). * - * Returns: a #GList of #GstPluginFeature. Use gst_plugin_feature_list_free() - * after usage. + * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of + * #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. * * MT safe. */ @@ -754,8 +756,8 @@ gst_registry_feature_filter (GstRegistry * registry, * Find the plugin with the given name in the registry. * The plugin will be reffed; caller is responsible for unreffing. * - * Returns: The plugin with the given name or NULL if the plugin was not found. - * gst_object_unref() after usage. + * Returns: (transfer full): the plugin with the given name or NULL if the + * plugin was not found. gst_object_unref() after usage. * * MT safe. */ @@ -788,8 +790,8 @@ gst_registry_find_plugin (GstRegistry * registry, const gchar * name) * * Find the pluginfeature with the given name and type in the registry. * - * Returns: The pluginfeature with the given name and type or NULL - * if the plugin was not found. gst_object_unref() after usage. + * Returns: (transfer full): the pluginfeature with the given name and type + * or NULL if the plugin was not found. gst_object_unref() after usage. * * MT safe. */ @@ -819,8 +821,8 @@ gst_registry_find_feature (GstRegistry * registry, const gchar * name, * * Retrieves a #GList of #GstPluginFeature of @type. * - * Returns: a #GList of #GstPluginFeature of @type. Use - * gst_plugin_feature_list_free() after usage. + * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of + * #GstPluginFeature of @type. Use gst_plugin_feature_list_free() after use * * MT safe. */ @@ -853,7 +855,8 @@ gst_registry_get_feature_list (GstRegistry * registry, GType type) * Get a copy of all plugins registered in the given registry. The refcount * of each element in the list in incremented. * - * Returns: a #GList of #GstPlugin. Use gst_plugin_list_free() after usage. + * Returns: (transfer full) (element-type Gst.Plugin): a #GList of #GstPlugin. + * Use gst_plugin_list_free() after usage. * * MT safe. */ @@ -888,8 +891,8 @@ gst_registry_lookup_feature_locked (GstRegistry * registry, const char *name) * * Find a #GstPluginFeature with @name in @registry. * - * Returns: a #GstPluginFeature with its refcount incremented, use - * gst_object_unref() after usage. + * Returns: (transfer full): a #GstPluginFeature with its refcount incremented, + * use gst_object_unref() after usage. * * MT safe. */ @@ -938,8 +941,8 @@ gst_registry_lookup_bn (GstRegistry * registry, const char *basename) * Look up a plugin in the given registry with the given filename. * If found, plugin is reffed. * - * Returns: the #GstPlugin if found, or NULL if not. gst_object_unref() - * after usage. + * Returns: (transfer full): the #GstPlugin if found, or NULL if not. + * gst_object_unref() after usage. */ GstPlugin * gst_registry_lookup (GstRegistry * registry, const char *filename) @@ -1276,8 +1279,8 @@ _gst_plugin_feature_filter_plugin_name (GstPluginFeature * feature, * * Retrieves a #GList of features of the plugin with name @name. * - * Returns: a #GList of #GstPluginFeature. Use gst_plugin_feature_list_free() - * after usage. + * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of + * #GstPluginFeature. Use gst_plugin_feature_list_free() after usage. */ GList * gst_registry_get_feature_list_by_plugin (GstRegistry * registry, diff --git a/gst/gstregistry.h b/gst/gstregistry.h index 2f38dcd21e..9ae9e6c036 100644 --- a/gst/gstregistry.h +++ b/gst/gstregistry.h @@ -127,7 +127,7 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo /** * gst_default_registry_add_plugin: - * @plugin: the plugin to add + * @plugin: (transfer full): the plugin to add * * Add the plugin to the default registry. * The plugin-added signal will be emitted. @@ -153,7 +153,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo * * Get the list of paths for the default registry. * - * Returns: A Glist of paths as strings. g_list_free after use. + * Returns: (transfer container) (element-type char*): a #GList of paths as + * strings. g_list_free() after use. */ #define gst_default_registry_get_path_list() \ gst_registry_get_path_list (gst_registry_get_default()) @@ -163,7 +164,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo * * Get a copy of all plugins registered in the default registry. * - * Returns: a copy of the list. Free after use. + * Returns: (transfer full) (element-type Gst.Plugin): a copy of the list. + * Free after use. */ #define gst_default_registry_get_plugin_list() \ gst_registry_get_plugin_list (gst_registry_get_default()) @@ -175,8 +177,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo * * Find the pluginfeature with the given name and type in the default registry. * - * Returns: The pluginfeature with the given name and type or NULL - * if the plugin was not found. + * Returns: (transfer full): the pluginfeature with the given name and type or + * NULL if the plugin was not found. */ #define gst_default_registry_find_feature(name,type) \ gst_registry_find_feature (gst_registry_get_default(),name,type) @@ -188,7 +190,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo * Find the plugin with the given name in the default registry. * The plugin will be reffed; caller is responsible for unreffing. * - * Returns: The plugin with the given name or NULL if the plugin was not found. + * Returns: (transfer full): The plugin with the given name or NULL if the + * plugin was not found. */ #define gst_default_registry_find_plugin(name) \ gst_registry_find_plugin (gst_registry_get_default(),name) @@ -204,7 +207,8 @@ gboolean gst_registry_xml_write_cache (GstRegistry * registry, const char *lo * If the first flag is set, only the first match is * returned (as a list with a single object). * - * Returns: a GList of plugin features, gst_plugin_feature_list_free after use. + * Returns: (transfer full) (element-type Gst.PluginFeature): a #GList of + * plugin features, gst_plugin_feature_list_free after use. */ #define gst_default_registry_feature_filter(filter,first,user_data) \ gst_registry_feature_filter (gst_registry_get_default(),filter,first,user_data) diff --git a/gst/gstsegment.c b/gst/gstsegment.c index 5b10a913d8..a70e8e6195 100644 --- a/gst/gstsegment.c +++ b/gst/gstsegment.c @@ -86,11 +86,13 @@ /** * gst_segment_copy: - * @segment: a #GstSegment + * @segment: (transfer none): a #GstSegment * * Create a copy of given @segment. * - * Returns: a new #GstSegment, free with gst_segment_free(). + * Free-function: gst_segment_free + * + * Returns: (transfer full): a new #GstSegment, free with gst_segment_free(). * * Since: 0.10.20 */ @@ -124,7 +126,9 @@ gst_segment_get_type (void) * Allocate a new #GstSegment structure and initialize it using * gst_segment_init(). * - * Returns: a new #GstSegment, free with gst_segment_free(). + * Free-function: gst_segment_free + * + * Returns: (transfer full): a new #GstSegment, free with gst_segment_free(). */ GstSegment * gst_segment_new (void) @@ -139,7 +143,7 @@ gst_segment_new (void) /** * gst_segment_free: - * @segment: a #GstSegment + * @segment: (in) (transfer full): a #GstSegment * * Free the allocated segment @segment. */ @@ -699,8 +703,8 @@ gst_segment_to_running_time (GstSegment * segment, GstFormat format, * @format: the format of the segment. * @start: the start position in the segment * @stop: the stop position in the segment - * @clip_start: the clipped start position in the segment - * @clip_stop: the clipped stop position in the segment + * @clip_start: (out) (allow-none): the clipped start position in the segment + * @clip_stop: (out) (allow-none): the clipped stop position in the segment * * Clip the given @start and @stop values to the segment boundaries given * in @segment. @start and @stop are compared and clipped to @segment diff --git a/gst/gststructure.c b/gst/gststructure.c index f961f0bc35..c83165ddc6 100644 --- a/gst/gststructure.c +++ b/gst/gststructure.c @@ -136,7 +136,9 @@ gst_structure_id_empty_new_with_size (GQuark quark, guint prealloc) * * Creates a new, empty #GstStructure with the given name as a GQuark. * - * Returns: a new, empty #GstStructure + * Free-function: gst_structure_free + * + * Returns: (transfer full): a new, empty #GstStructure */ GstStructure * gst_structure_id_empty_new (GQuark quark) @@ -184,7 +186,9 @@ gst_structure_validate_name (const gchar * name) * * See gst_structure_set_name() for constraints on the @name parameter. * - * Returns: a new, empty #GstStructure + * Free-function: gst_structure_free + * + * Returns: (transfer full): a new, empty #GstStructure */ GstStructure * gst_structure_empty_new (const gchar * name) @@ -205,7 +209,9 @@ gst_structure_empty_new (const gchar * name) * Variable arguments should be passed as field name, field type, * and value. Last variable argument should be NULL. * - * Returns: a new #GstStructure + * Free-function: gst_structure_free + * + * Returns: (transfer full): a new #GstStructure */ GstStructure * gst_structure_new (const gchar * name, const gchar * firstfield, ...) @@ -234,7 +240,9 @@ gst_structure_new (const gchar * name, const gchar * firstfield, ...) * * See gst_structure_set_name() for constraints on the @name parameter. * - * Returns: a new #GstStructure + * Free-function: gst_structure_free + * + * Returns: (transfer full): a new #GstStructure */ GstStructure * gst_structure_new_valist (const gchar * name, @@ -255,7 +263,7 @@ gst_structure_new_valist (const gchar * name, /** * gst_structure_set_parent_refcount: * @structure: a #GstStructure - * @refcount: a pointer to the parent's refcount + * @refcount: (in): a pointer to the parent's refcount * * Sets the parent_refcount field of #GstStructure. This field is used to * determine whether a structure is mutable or not. This function should only be @@ -283,7 +291,9 @@ gst_structure_set_parent_refcount (GstStructure * structure, gint * refcount) * * Duplicates a #GstStructure and all its fields and values. * - * Returns: a new #GstStructure. + * Free-function: gst_structure_free + * + * Returns: (transfer none): a new #GstStructure. */ GstStructure * gst_structure_copy (const GstStructure * structure) @@ -312,7 +322,7 @@ gst_structure_copy (const GstStructure * structure) /** * gst_structure_free: - * @structure: the #GstStructure to free + * @structure: (in) (transfer full): the #GstStructure to free * * Frees a #GstStructure and all its fields and values. The structure must not * have a parent when this function is called. @@ -709,7 +719,9 @@ gst_structure_id_set_valist (GstStructure * structure, * * The last variable argument must be NULL (or 0). * - * Returns: a new #GstStructure + * Free-function: gst_structure_free + * + * Returns: (transfer full): a new #GstStructure * * Since: 0.10.24 */ @@ -1048,7 +1060,7 @@ gst_structure_nth_field_name (const GstStructure * structure, guint index) * gst_structure_foreach: * @structure: a #GstStructure * @func: a function to call for each field - * @user_data: private data + * @user_data: (closure): private data * * Calls the provided function once for each field in the #GstStructure. The * function must not modify the fields. Also see gst_structure_map_in_place(). @@ -1084,7 +1096,7 @@ gst_structure_foreach (const GstStructure * structure, * gst_structure_map_in_place: * @structure: a #GstStructure * @func: a function to call for each field - * @user_data: private data + * @user_data: (closure): private data * * Calls the provided function once for each field in the #GstStructure. In * contrast to gst_structure_foreach(), the function may modify but not delete the @@ -1216,7 +1228,7 @@ gst_structure_has_field_typed (const GstStructure * structure, * gst_structure_get_boolean: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a #gboolean to set + * @value: (out): a pointer to a #gboolean to set * * Sets the boolean pointed to by @value corresponding to the value of the * given field. Caller is responsible for making sure the field exists @@ -1251,7 +1263,7 @@ gst_structure_get_boolean (const GstStructure * structure, * gst_structure_get_int: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to an int to set + * @value: (out): a pointer to an int to set * * Sets the int pointed to by @value corresponding to the value of the * given field. Caller is responsible for making sure the field exists @@ -1287,7 +1299,7 @@ gst_structure_get_int (const GstStructure * structure, * gst_structure_get_uint: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a uint to set + * @value: (out): a pointer to a uint to set * * Sets the uint pointed to by @value corresponding to the value of the * given field. Caller is responsible for making sure the field exists @@ -1325,7 +1337,7 @@ gst_structure_get_uint (const GstStructure * structure, * gst_structure_get_fourcc: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a 32bit unsigned int to set + * @value: (out): a pointer to a 32bit unsigned int to set * * Sets the Fourcc pointed to by @value corresponding to the value of the * given field. Caller is responsible for making sure the field exists @@ -1361,7 +1373,7 @@ gst_structure_get_fourcc (const GstStructure * structure, * gst_structure_get_date: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a #GDate to set + * @value: (out callee-allocates): a pointer to a #GDate to set * * Sets the date pointed to by @value corresponding to the date of the * given field. Caller is responsible for making sure the field exists @@ -1403,7 +1415,7 @@ gst_structure_get_date (const GstStructure * structure, const gchar * fieldname, * gst_structure_get_date_time: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a #GstDateTime to set + * @value: (out callee-allocates): a pointer to a #GstDateTime to set * * Sets the datetime pointed to by @value corresponding to the datetime of the * given field. Caller is responsible for making sure the field exists @@ -1445,7 +1457,7 @@ gst_structure_get_date_time (const GstStructure * structure, * gst_structure_get_clock_time: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a #GstClockTime to set + * @value: (out): a pointer to a #GstClockTime to set * * Sets the clock time pointed to by @value corresponding to the clock time * of the given field. Caller is responsible for making sure the field exists @@ -1481,7 +1493,7 @@ gst_structure_get_clock_time (const GstStructure * structure, * gst_structure_get_double: * @structure: a #GstStructure * @fieldname: the name of a field - * @value: a pointer to a gdouble to set + * @value: (out): a pointer to a gdouble to set * * Sets the double pointed to by @value corresponding to the value of the * given field. Caller is responsible for making sure the field exists @@ -1552,7 +1564,7 @@ gst_structure_get_string (const GstStructure * structure, * @structure: a #GstStructure * @fieldname: the name of a field * @enumtype: the enum type of a field - * @value: a pointer to an int to set + * @value: (out): a pointer to an int to set * * Sets the int pointed to by @value corresponding to the value of the * given field. Caller is responsible for making sure the field exists, @@ -1589,8 +1601,8 @@ gst_structure_get_enum (const GstStructure * structure, * gst_structure_get_fraction: * @structure: a #GstStructure * @fieldname: the name of a field - * @value_numerator: a pointer to an int to set - * @value_denominator: a pointer to an int to set + * @value_numerator: (out): a pointer to an int to set + * @value_denominator: (out): a pointer to an int to set * * Sets the integers pointed to by @value_numerator and @value_denominator * corresponding to the value of the given field. Caller is responsible @@ -1809,8 +1821,10 @@ priv_gst_structure_append_to_gstring (const GstStructure * structure, * ]| * This prints the structure in human readble form. * - * Returns: a pointer to string allocated by g_malloc(). g_free() after - * usage. + * Free-function: g_free + * + * Returns: (transfer full)L a pointer to string allocated by g_malloc(). + * g_free() after usage. */ gchar * gst_structure_to_string (const GstStructure * structure) @@ -2192,14 +2206,16 @@ gst_structure_parse_value (gchar * str, /** * gst_structure_from_string: * @string: a string representation of a #GstStructure. - * @end: pointer to store the end of the string in. + * @end: (out) (allow-none): pointer to store the end of the string in. * * Creates a #GstStructure from a string representation. * If end is not NULL, a pointer to the place inside the given string * where parsing ended will be returned. * - * Returns: a new #GstStructure or NULL when the string could not - * be parsed. Free with gst_structure_free() after use. + * Free-function: gst_structure_free + * + * Returns: (transfer full): a new #GstStructure or NULL when the string could + * not be parsed. Free with gst_structure_free() after use. */ GstStructure * gst_structure_from_string (const gchar * string, gchar ** end) diff --git a/gst/gstsystemclock.c b/gst/gstsystemclock.c index c5ae9329d8..53ab55412a 100644 --- a/gst/gstsystemclock.c +++ b/gst/gstsystemclock.c @@ -268,7 +268,7 @@ gst_system_clock_get_property (GObject * object, guint prop_id, GValue * value, * clock will be increased so you need to unref the clock after * usage. * - * Returns: the default clock. + * Returns: (transfer full): the default clock. * * MT safe. */ diff --git a/gst/gsttaglist.c b/gst/gsttaglist.c index 019c25cad3..1f64b47735 100644 --- a/gst/gsttaglist.c +++ b/gst/gsttaglist.c @@ -369,7 +369,7 @@ _gst_tag_initialize (void) /** * gst_tag_merge_use_first: - * @dest: uninitialized GValue to store result in + * @dest: (out caller-allocates): uninitialized GValue to store result in * @src: GValue to copy from * * This is a convenience function for the func argument of gst_tag_register(). @@ -386,7 +386,7 @@ gst_tag_merge_use_first (GValue * dest, const GValue * src) /** * gst_tag_merge_strings_with_comma: - * @dest: uninitialized GValue to store result in + * @dest: (out caller-allocates): uninitialized GValue to store result in * @src: GValue to copy from * * This is a convenience function for the func argument of gst_tag_register(). @@ -612,7 +612,9 @@ gst_tag_is_fixed (const gchar * tag) * * Creates a new empty GstTagList. * - * Returns: An empty tag list + * Free-function: gst_tag_list_free + * + * Returns: (transfer full): An empty tag list */ GstTagList * gst_tag_list_new (void) @@ -633,8 +635,10 @@ gst_tag_list_new (void) * function. The tag list will make copies of any arguments passed * (e.g. strings, buffers). * - * Returns: a new #GstTagList. Free with gst_tag_list_free() when no longer - * needed. + * Free-function: gst_tag_list_free + * + * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free() + * when no longer needed. * * Since: 0.10.24 */ @@ -662,8 +666,10 @@ gst_tag_list_new_full (const gchar * tag, ...) * Just like gst_tag_list_new_full(), only that it takes a va_list argument. * Useful mostly for language bindings. * - * Returns: a new #GstTagList. Free with gst_tag_list_free() when no longer - * needed. + * Free-function: gst_tag_list_free + * + * Returns: (transfer full): a new #GstTagList. Free with gst_tag_list_free() + * when no longer needed. * * Since: 0.10.24 */ @@ -829,7 +835,9 @@ gst_tag_list_insert (GstTagList * into, const GstTagList * from, * * Copies a given #GstTagList. * - * Returns: copy of the given list + * Free-function: gst_tag_list_free + * + * Returns: (transfer full): copy of the given list */ GstTagList * gst_tag_list_copy (const GstTagList * list) @@ -848,7 +856,9 @@ gst_tag_list_copy (const GstTagList * list) * Merges the two given lists into a new list. If one of the lists is NULL, a * copy of the other is returned. If both lists are NULL, NULL is returned. * - * Returns: the new list + * Free-function: gst_tag_list_free + * + * Returns: (transfer full): the new list */ GstTagList * gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2, @@ -880,7 +890,7 @@ gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2, /** * gst_tag_list_free: - * @list: the list to free + * @list: (in) (transfer full): the list to free * * Frees the given list and all associated values. */ @@ -1111,7 +1121,7 @@ structure_foreach_wrapper (GQuark field_id, const GValue * value, * gst_tag_list_foreach: * @list: list to iterate over * @func: function to be called for each tag - * @user_data: user specified data + * @user_data: (closure): user specified data * * Calls the given function for each tag inside the tag list. Note that if there * is no tag, the function won't be called at all. @@ -1141,8 +1151,8 @@ gst_tag_list_foreach (const GstTagList * list, GstTagForeachFunc func, * Gets the value that is at the given index for the given tag in the given * list. * - * Returns: The GValue for the specified entry or NULL if the tag wasn't - * available or the tag doesn't have as many entries + * Returns: (transfer none): The GValue for the specified entry or NULL if the + * tag wasn't available or the tag doesn't have as many entries */ G_CONST_RETURN GValue * gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag, @@ -1170,7 +1180,7 @@ gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag, /** * gst_tag_list_copy_value: - * @dest: uninitialized #GValue to copy into + * @dest: (out caller-allocates): uninitialized #GValue to copy into * @list: list to get the tag from * @tag: tag to read out * @@ -1268,7 +1278,7 @@ gst_tag_list_get_ ## name ## _index (const GstTagList *list, \ * gst_tag_list_get_char: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1281,7 +1291,7 @@ gst_tag_list_get_ ## name ## _index (const GstTagList *list, \ * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1294,7 +1304,7 @@ TAG_MERGE_FUNCS (char, gchar, TRUE) * gst_tag_list_get_uchar: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1307,7 +1317,7 @@ TAG_MERGE_FUNCS (char, gchar, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1320,7 +1330,7 @@ TAG_MERGE_FUNCS (uchar, guchar, TRUE) * gst_tag_list_get_boolean: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1333,7 +1343,7 @@ TAG_MERGE_FUNCS (uchar, guchar, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1346,7 +1356,7 @@ TAG_MERGE_FUNCS (boolean, gboolean, TRUE) * gst_tag_list_get_int: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1359,7 +1369,7 @@ TAG_MERGE_FUNCS (boolean, gboolean, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1372,7 +1382,7 @@ TAG_MERGE_FUNCS (int, gint, TRUE) * gst_tag_list_get_uint: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1385,7 +1395,7 @@ TAG_MERGE_FUNCS (int, gint, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1398,7 +1408,7 @@ TAG_MERGE_FUNCS (uint, guint, TRUE) * gst_tag_list_get_long: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1411,7 +1421,7 @@ TAG_MERGE_FUNCS (uint, guint, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1424,7 +1434,7 @@ TAG_MERGE_FUNCS (long, glong, TRUE) * gst_tag_list_get_ulong: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1437,7 +1447,7 @@ TAG_MERGE_FUNCS (long, glong, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1450,7 +1460,7 @@ TAG_MERGE_FUNCS (ulong, gulong, TRUE) * gst_tag_list_get_int64: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1463,7 +1473,7 @@ TAG_MERGE_FUNCS (ulong, gulong, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1476,7 +1486,7 @@ TAG_MERGE_FUNCS (int64, gint64, TRUE) * gst_tag_list_get_uint64: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1489,7 +1499,7 @@ TAG_MERGE_FUNCS (int64, gint64, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1502,7 +1512,7 @@ TAG_MERGE_FUNCS (uint64, guint64, TRUE) * gst_tag_list_get_float: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1515,7 +1525,7 @@ TAG_MERGE_FUNCS (uint64, guint64, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1528,7 +1538,7 @@ TAG_MERGE_FUNCS (float, gfloat, TRUE) * gst_tag_list_get_double: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1541,7 +1551,7 @@ TAG_MERGE_FUNCS (float, gfloat, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1554,7 +1564,7 @@ TAG_MERGE_FUNCS (double, gdouble, TRUE) * gst_tag_list_get_pointer: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out) (transfer none): location for the result * * Copies the contents for the given tag into the value, merging multiple values * into one if multiple values are associated with the tag. @@ -1567,7 +1577,7 @@ TAG_MERGE_FUNCS (double, gdouble, TRUE) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out) (transfer none): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1582,7 +1592,7 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL)) * gst_tag_list_get_string: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: location for the result + * @value: (out callee-allocates) (transfer full): location for the result * * Copies the contents for the given tag into the value, possibly merging * multiple values into one if multiple values are associated with the tag. @@ -1594,6 +1604,8 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL)) * freed by the caller using g_free when no longer needed. Since 0.10.24 the * returned string is also guaranteed to be non-NULL and non-empty. * + * Free-function: g_free + * * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * given list. */ @@ -1602,7 +1614,7 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL)) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out callee-allocates) (transfer full): location for the result * * Gets the value that is at the given index for the given tag in the given * list. @@ -1611,6 +1623,8 @@ TAG_MERGE_FUNCS (pointer, gpointer, (*value != NULL)) * freed by the caller using g_free when no longer needed. Since 0.10.24 the * returned string is also guaranteed to be non-NULL and non-empty. * + * Free-function: g_free + * * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * given list. */ @@ -1626,7 +1640,7 @@ TAG_MERGE_FUNCS (string, gchar *, (*value != NULL && **value != '\0')) * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out) (transfer none): location for the result * * Peeks at the value that is at the given index for the given tag in the given * list. @@ -1658,12 +1672,15 @@ gst_tag_list_peek_string_index (const GstTagList * list, * gst_tag_list_get_date: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: address of a GDate pointer variable to store the result into + * @value: (out callee-allocates) (transfer full): address of a GDate pointer + * variable to store the result into * * Copies the first date for the given tag in the taglist into the variable * pointed to by @value. Free the date with g_date_free() when it is no longer * needed. * + * Free-function: g_date_free + * * Returns: TRUE, if a date was copied, FALSE if the tag didn't exist in the * given list or if it was #NULL. */ @@ -1689,12 +1706,14 @@ gst_tag_list_get_date (const GstTagList * list, const gchar * tag, * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out callee-allocates) (transfer full): location for the result * * Gets the date that is at the given index for the given tag in the given * list and copies it into the variable pointed to by @value. Free the date * with g_date_free() when it is no longer needed. * + * Free-function: g_date_free + * * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * given list or if it was #NULL. */ @@ -1718,14 +1737,18 @@ gst_tag_list_get_date_index (const GstTagList * list, * gst_tag_list_get_date_time: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: address of a #GstDateTime pointer variable to store the result into + * @value: (out callee-allocates) (transfer full): address of a #GstDateTime + * pointer variable to store the result into * * Copies the first datetime for the given tag in the taglist into the variable * pointed to by @value. Unref the date with gst_date_time_unref() when * it is no longer needed. * - * Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in the - * given list or if it was #NULL. + * Free-function: gst_date_time_unref + * + * Returns: TRUE, if a datetime was copied, FALSE if the tag didn't exist in + * thegiven list or if it was #NULL. + * * Since: 0.10.31 */ gboolean @@ -1753,14 +1776,17 @@ gst_tag_list_get_date_time (const GstTagList * list, const gchar * tag, * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: location for the result + * @value: (out callee-allocates) (transfer full): location for the result * * Gets the datetime that is at the given index for the given tag in the given * list and copies it into the variable pointed to by @value. Unref the datetime * with gst_date_time_unref() when it is no longer needed. * + * Free-function: gst_date_time_unref + * * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the * given list or if it was #NULL. + * * Since: 0.10.31 */ gboolean @@ -1783,12 +1809,15 @@ gst_tag_list_get_date_time_index (const GstTagList * list, * gst_tag_list_get_buffer: * @list: a #GstTagList to get the tag from * @tag: tag to read out - * @value: address of a GstBuffer pointer variable to store the result into + * @value: (out callee-allocates) (transfer full): address of a GstBuffer + * pointer variable to store the result into * * Copies the first buffer for the given tag in the taglist into the variable * pointed to by @value. Free the buffer with gst_buffer_unref() when it is * no longer needed. * + * Free-function: gst_buffer_unref + * * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the * given list or if it was #NULL. * @@ -1816,12 +1845,15 @@ gst_tag_list_get_buffer (const GstTagList * list, const gchar * tag, * @list: a #GstTagList to get the tag from * @tag: tag to read out * @index: number of entry to read out - * @value: address of a GstBuffer pointer variable to store the result into + * @value: (out callee-allocates) (transfer full): address of a GstBuffer + * pointer variable to store the result into * * Gets the buffer that is at the given index for the given tag in the given * list and copies it into the variable pointed to by @value. Free the buffer * with gst_buffer_unref() when it is no longer needed. * + * Free-function: gst_buffer_unref + * * Returns: TRUE, if a buffer was copied, FALSE if the tag didn't exist in the * given list or if it was #NULL. * diff --git a/gst/gsttagsetter.c b/gst/gsttagsetter.c index 4da295ce8c..05dbbab439 100644 --- a/gst/gsttagsetter.c +++ b/gst/gsttagsetter.c @@ -368,8 +368,8 @@ gst_tag_setter_add_tag_value (GstTagSetter * setter, * * This function is not thread-safe. * - * Returns: a current snapshot of the taglist used in the setter - * or NULL if none is used. + * Returns: (transfer none): a current snapshot of the taglist used in the + * setter or NULL if none is used. */ G_CONST_RETURN GstTagList * gst_tag_setter_get_tag_list (GstTagSetter * setter) diff --git a/gst/gsttask.c b/gst/gsttask.c index 6a985d9870..5acbc85a10 100644 --- a/gst/gsttask.c +++ b/gst/gsttask.c @@ -379,7 +379,7 @@ gst_task_cleanup_all (void) /** * gst_task_create: * @func: The #GstTaskFunction to use - * @data: User data to pass to @func + * @data: (closure): User data to pass to @func * * Create a new Task that will repeatedly call the provided @func * with @data as a parameter. Typically the task will run in @@ -395,7 +395,7 @@ gst_task_cleanup_all (void) * gst_task_set_lock() function. This lock will always be acquired while * @func is called. * - * Returns: A new #GstTask. + * Returns: (transfer full): A new #GstTask. * * MT safe. */ @@ -489,7 +489,7 @@ gst_task_set_priority (GstTask * task, GThreadPriority priority) * * MT safe. * - * Returns: the #GstTaskPool used by @task. gst_object_unref() + * Returns: (transfer full): the #GstTaskPool used by @task. gst_object_unref() * after usage. * * Since: 0.10.24 @@ -514,7 +514,7 @@ gst_task_get_pool (GstTask * task) /** * gst_task_set_pool: * @task: a #GstTask - * @pool: a #GstTaskPool + * @pool: (transfer none): a #GstTaskPool * * Set @pool as the new GstTaskPool for @task. Any new streaming threads that * will be created by @task will now use @pool. @@ -550,8 +550,8 @@ gst_task_set_pool (GstTask * task, GstTaskPool * pool) /** * gst_task_set_thread_callbacks: * @task: The #GstTask to use - * @callbacks: a #GstTaskThreadCallbacks pointer - * @user_data: user data passed to the callbacks + * @callbacks: (in): a #GstTaskThreadCallbacks pointer + * @user_data: (closure): user data passed to the callbacks * @notify: called when @user_data is no longer referenced * * Set callbacks which will be executed when a new thread is needed, the thread diff --git a/gst/gsttaskpool.c b/gst/gsttaskpool.c index 67a6a9a6b8..d5981e63b7 100644 --- a/gst/gsttaskpool.c +++ b/gst/gsttaskpool.c @@ -158,7 +158,7 @@ gst_task_pool_finalize (GObject * object) * Create a new default task pool. The default task pool will use a regular * GThreadPool for threads. * - * Returns: a new #GstTaskPool. gst_object_unref() after usage. + * Returns: (transfer full): a new #GstTaskPool. gst_object_unref() after usage. * * Since: 0.10.24 */ @@ -224,7 +224,7 @@ gst_task_pool_cleanup (GstTaskPool * pool) * gst_task_pool_push: * @pool: a #GstTaskPool * @func: the function to call - * @user_data: data to pass to @func + * @user_data: (closure): data to pass to @func * @error: return location for an error * * Start the execution of a new thread from @pool. diff --git a/gst/gsttrace.c b/gst/gsttrace.c index 63ad47b1f7..437058974e 100644 --- a/gst/gsttrace.c +++ b/gst/gsttrace.c @@ -86,7 +86,7 @@ read_tsc (gint64 * dst) /** * gst_trace_read_tsc: - * @dst: pointer to hold the result. + * @dst: (out) pointer to hold the result. * * Read a platform independent timer value that can be used in * benchmarks. @@ -108,7 +108,9 @@ gint _gst_trace_on = 1; * Create a ringbuffer of @size in the file with @filename to * store trace results in. * - * Returns: a new #GstTrace. + * Free-function: gst_trace_destroy + * + * Returns: (transfer full): a new #GstTrace. */ GstTrace * gst_trace_new (const gchar * filename, gint size) @@ -138,7 +140,7 @@ gst_trace_new (const gchar * filename, gint size) /** * gst_trace_destroy: - * @trace: the #GstTrace to destroy + * @trace: (in) (transfer full): the #GstTrace to destroy * * Flush an close the previously allocated @trace. */ diff --git a/gst/gsttypefind.c b/gst/gsttypefind.c index 6a2bfe1880..e4254e19a7 100644 --- a/gst/gsttypefind.c +++ b/gst/gsttypefind.c @@ -56,7 +56,8 @@ gst_type_find_get_type (void) * @name: The name for registering * @rank: The rank (or importance) of this typefind function * @func: The #GstTypeFindFunction to use - * @extensions: Optional extensions that could belong to this type + * @extensions: (transfer none) (array zero-terminated=1) (element-type utf8): + * Optional extensions that could belong to this type * @possible_caps: Optionally the caps that could be returned when typefinding * succeeds * @data: Optional user data. This user data must be available until the plugin @@ -123,7 +124,8 @@ gst_type_find_register (GstPlugin * plugin, const gchar * name, guint rank, * the stream. The returned memory is valid until the typefinding function * returns and must not be freed. * - * Returns: the requested data, or NULL if that data is not available. + * Returns: (transfer none) (array length=size): the requested data, or NULL + * if that data is not available. */ guint8 * gst_type_find_peek (GstTypeFind * find, gint64 offset, guint size) diff --git a/gst/gsttypefindfactory.c b/gst/gsttypefindfactory.c index 7b57ca5da7..840916405f 100644 --- a/gst/gsttypefindfactory.c +++ b/gst/gsttypefindfactory.c @@ -149,7 +149,10 @@ gst_type_find_factory_dispose (GObject * object) * The returned factories are sorted by highest rank first, and then by * factory name. (behaviour change since 0.10.26) * - * Returns: the list of all registered #GstTypeFindFactory. + * Free-function: gst_plugin_feature_list_free + * + * Returns: (transfer full) (element-type Gst.TypeFindFactory): the list of all + * registered #GstTypeFindFactory. */ GList * gst_type_find_factory_get_list (void) @@ -164,7 +167,7 @@ gst_type_find_factory_get_list (void) * * Gets the #GstCaps associated with a typefind factory. * - * Returns: The #GstCaps associated with this factory + * Returns: (transfer none): the #GstCaps associated with this factory */ GstCaps * gst_type_find_factory_get_caps (GstTypeFindFactory * factory) @@ -183,7 +186,8 @@ gst_type_find_factory_get_caps (GstTypeFindFactory * factory) * copy it using g_strdupv(). This function may return NULL to indicate * a 0-length list. * - * Returns: a NULL-terminated array of extensions associated with this factory + * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): a + * NULL-terminated array of extensions associated with this factory */ gchar ** gst_type_find_factory_get_extensions (GstTypeFindFactory * factory) @@ -196,8 +200,8 @@ gst_type_find_factory_get_extensions (GstTypeFindFactory * factory) /** * gst_type_find_factory_call_function: * @factory: A #GstTypeFindFactory - * @find: A properly setup #GstTypeFind entry. The get_data and suggest_type - * members must be set. + * @find: (transfer none): a properly setup #GstTypeFind entry. The get_data + * and suggest_type members must be set. * * Calls the #GstTypeFindFunction associated with this factory. */ diff --git a/gst/gsturi.c b/gst/gsturi.c index 1e227e8101..247604c72f 100644 --- a/gst/gsturi.c +++ b/gst/gsturi.c @@ -101,7 +101,7 @@ gst_uri_handler_base_init (gpointer g_class) /** * GstURIHandler::new-uri: * @handler: The #GstURIHandler which emitted the signal - * @uri: The new URI, or NULL if the URI was removed + * @uri: (transfer none): The new URI, or NULL if the URI was removed * * The URI of the given @handler has changed. */ @@ -208,8 +208,7 @@ escape_string_internal (const gchar * string, UnsafeCharacterSet mask) return result; } -/** - * escape_string: +/* escape_string: * @string: string to be escaped * * Escapes @string, replacing any and all special characters @@ -251,8 +250,7 @@ unescape_character (const char *scanner) return (first_digit << 4) | second_digit; } -/** - * unescape_string: +/* unescape_string: * @escaped_string: an escaped URI, path, or other string * @illegal_characters: a string containing a sequence of characters * considered "illegal", '\0' is automatically in this list. @@ -388,7 +386,7 @@ gst_uri_get_protocol (const gchar * uri) /** * gst_uri_has_protocol: - * @uri: an URI string + * @uri: a URI string * @protocol: a protocol string (e.g. "http") * * Checks if the protocol of a given valid URI matches @protocol. @@ -423,8 +421,11 @@ gst_uri_has_protocol (const gchar * uri, const gchar * protocol) * the hostname if one is specified. The returned string must be freed using * g_free(). * - * Returns: The location for this URI. Returns NULL if the URI isn't valid. If - * the URI does not contain a location, an empty string is returned. + * Free-function: g_free + * + * Returns: (transfer full) (array zero-terminated=1): the location for this + * URI. Returns NULL if the URI isn't valid. If the URI does not contain + * a location, an empty string is returned. */ gchar * gst_uri_get_location (const gchar * uri) @@ -463,12 +464,15 @@ gst_uri_get_location (const gchar * uri) /** * gst_uri_construct: * @protocol: Protocol for URI - * @location: Location for URI + * @location: (array zero-terminated=1) (transfer none): Location for URI * * Constructs a URI for a given valid protocol and location. * - * Returns: a new string for this URI. Returns NULL if the given URI protocol - * is not valid, or the given location is NULL. + * Free-function: g_free + * + * Returns: (transfer full) (array zero-terminated=1): a new string for this + * URI. Returns NULL if the given URI protocol is not valid, or the given + * location is NULL. */ gchar * gst_uri_construct (const gchar * protocol, const gchar * location) @@ -582,11 +586,11 @@ gst_uri_protocol_is_supported (const GstURIType type, const gchar * protocol) * gst_element_make_from_uri: * @type: Whether to create a source or a sink * @uri: URI to create an element for - * @elementname: Name of created element, can be NULL. + * @elementname: (allow-none): Name of created element, can be NULL. * * Creates an element for handling the given URI. * - * Returns: a new element or NULL if none could be created + * Returns: (transfer full): a new element or NULL if none could be created */ GstElement * gst_element_make_from_uri (const GstURIType type, const gchar * uri, @@ -669,9 +673,9 @@ gst_uri_handler_get_uri_type (GstURIHandler * handler) * Gets the list of protocols supported by @handler. This list may not be * modified. * - * Returns: the supported protocols. - * Returns NULL if the @handler isn't implemented properly, or the @handler - * doesn't support any protocols. + * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): the + * supported protocols. Returns NULL if the @handler isn't implemented + * properly, or the @handler doesn't support any protocols. */ gchar ** gst_uri_handler_get_protocols (GstURIHandler * handler) @@ -702,9 +706,9 @@ gst_uri_handler_get_protocols (GstURIHandler * handler) * * Gets the currently handled URI. * - * Returns: the URI currently handled by the @handler. - * Returns NULL if there are no URI currently handled. The returned - * string must not be modified or freed. + * Returns: (transfer none): the URI currently handled by the @handler. + * Returns NULL if there are no URI currently handled. The + * returned string must not be modified or freed. */ G_CONST_RETURN gchar * gst_uri_handler_get_uri (GstURIHandler * handler) diff --git a/gst/gsturi.h b/gst/gsturi.h index 50da1c2d55..6193cf3014 100644 --- a/gst/gsturi.h +++ b/gst/gsturi.h @@ -75,11 +75,13 @@ typedef struct _GstURIHandlerInterface GstURIHandlerInterface; * @get_uri: Method to return the URI currently handled by the element. * @set_uri: Method to set a new URI. * @get_type_full: Variant of get_type which takes a GType argument. This is - * for use by bindings that need to pass context when creating a URI Handler. * If implemented, get_type will be used in preference to get_type_full. Since: 0.10.15. - * @get_protocols_full: Variant of get_type which takes a GType argument. - * This is for use by bindings that need to pass context when creating a URI - * Handler. If implemented, get_protocols will be used in preference to - * get_protocols_full. Since: 0.10.15. + * for use by bindings that need to pass context when creating a URI Handler. + * If implemented, get_type will be used in preference to get_type_full. + * Since: 0.10.15. + * @get_protocols_full: Variant of get_protocols which takes a GType argument. + * This is for use by bindings that need to pass context when creating a URI + * Handler. If implemented, get_protocols will be used in preference to + * get_protocols_full. Since: 0.10.15. * * Any #GstElement using this interface should implement these methods. */ diff --git a/gst/gstutils.c b/gst/gstutils.c index 511663555c..3a8c172fc9 100644 --- a/gst/gstutils.c +++ b/gst/gstutils.c @@ -82,7 +82,7 @@ gst_util_dump_mem (const guchar * mem, guint size) /** * gst_util_set_value_from_string: - * @value: the value to set + * @value: (out caller-allocates): the value to set * @value_str: the string to get the value from * * Converts the string to the type of the value and @@ -748,7 +748,7 @@ string_append_indent (GString * str, gint count) * gst_print_pad_caps: * @buf: the buffer to print the caps in * @indent: initial indentation - * @pad: the pad to print the caps from + * @pad: (transfer none): the pad to print the caps from * * Write the pad capabilities in a human readable format into * the given GString. @@ -777,7 +777,7 @@ gst_print_pad_caps (GString * buf, gint indent, GstPad * pad) * gst_print_element_args: * @buf: the buffer to print the args in * @indent: initial indentation - * @element: the element to print the args of + * @element: (transfer none): the element to print the args of * * Print the element argument in a human readable format in the given * GString. @@ -825,7 +825,7 @@ gst_print_element_args (GString * buf, gint indent, GstElement * element) /** * gst_element_create_all_pads: - * @element: a #GstElement to create pads for + * @element: (transfer none): a #GstElement to create pads for * * Creates a pad for each pad template that is always available. * This function is only useful during object intialization of @@ -858,14 +858,15 @@ gst_element_create_all_pads (GstElement * element) /** * gst_element_get_compatible_pad_template: - * @element: a #GstElement to get a compatible pad template for. - * @compattempl: the #GstPadTemplate to find a compatible template for. + * @element: (transfer none): a #GstElement to get a compatible pad template for + * @compattempl: (transfer none): the #GstPadTemplate to find a compatible + * template for * * Retrieves a pad template from @element that is compatible with @compattempl. * Pads from compatible templates can be linked together. * - * Returns: a compatible #GstPadTemplate, or NULL if none was found. No - * unreferencing is necessary. + * Returns: (transfer none): a compatible #GstPadTemplate, or NULL if none + * was found. No unreferencing is necessary. */ GstPadTemplate * gst_element_get_compatible_pad_template (GstElement * element, @@ -954,14 +955,15 @@ gst_element_request_pad (GstElement * element, GstPadTemplate * templ, /** * gst_element_get_pad_from_template: - * @element: a #GstElement. - * @templ: a #GstPadTemplate belonging to @element. + * @element: (transfer none): a #GstElement. + * @templ: (transfer none): a #GstPadTemplate belonging to @element. * * Gets a pad from @element described by @templ. If the presence of @templ is * #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES * templates. * - * Returns: the #GstPad, or NULL if one could not be found or created. + * Returns: (transfer full): the #GstPad, or NULL if one could not be found + * or created. */ static GstPad * gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ) @@ -1082,8 +1084,8 @@ gst_pad_check_link (GstPad * srcpad, GstPad * sinkpad) /** * gst_element_get_compatible_pad: - * @element: a #GstElement in which the pad should be found. - * @pad: the #GstPad to find a compatible one for. + * @element: (transfer none): a #GstElement in which the pad should be found. + * @pad: (transfer none): the #GstPad to find a compatible one for. * @caps: the #GstCaps to use as a filter. * * Looks for an unlinked pad to which the given pad can link. It is not @@ -1094,8 +1096,8 @@ gst_pad_check_link (GstPad * srcpad, GstPad * sinkpad) * and if none can be found, it will request a compatible REQUEST pad by looking * at the templates of @element. * - * Returns: the #GstPad to which a link can be made, or %NULL if one cannot be - * found. gst_object_unref() after usage. + * Returns: (transfer full): the #GstPad to which a link can be made, or %NULL + * if one cannot be found. gst_object_unref() after usage. */ GstPad * gst_element_get_compatible_pad (GstElement * element, GstPad * pad, @@ -1228,7 +1230,7 @@ gst_element_get_compatible_pad (GstElement * element, GstPad * pad, * * Gets a string representing the given state. * - * Returns: a string with the name of the state. + * Returns: (transfer none): a string with the name of the state. */ G_CONST_RETURN gchar * gst_element_state_get_name (GstState state) @@ -1272,7 +1274,8 @@ gst_element_state_get_name (GstState state) * * Gets a string representing the given state change result. * - * Returns: a string with the name of the state change result. + * Returns: (transfer none): a string with the name of the state + * result. * * Since: 0.10.11 */ @@ -1576,9 +1579,10 @@ pad_link_maybe_ghosting (GstPad * src, GstPad * sink, GstPadLinkCheck flags) /** * gst_element_link_pads_full: * @src: a #GstElement containing the source pad. - * @srcpadname: the name of the #GstPad in source element or NULL for any pad. - * @dest: the #GstElement containing the destination pad. - * @destpadname: the name of the #GstPad in destination element, + * @srcpadname: (allow-none): the name of the #GstPad in source element + * or NULL for any pad. + * @dest: (transfer none): the #GstElement containing the destination pad. + * @destpadname: (allow-none): the name of the #GstPad in destination element, * or NULL for any pad. * @flags: the #GstPadLinkCheck to be performed when linking pads. * @@ -1842,9 +1846,10 @@ gst_element_link_pads_full (GstElement * src, const gchar * srcpadname, /** * gst_element_link_pads: * @src: a #GstElement containing the source pad. - * @srcpadname: the name of the #GstPad in source element or NULL for any pad. - * @dest: the #GstElement containing the destination pad. - * @destpadname: the name of the #GstPad in destination element, + * @srcpadname: (allow-none): the name of the #GstPad in source element + * or NULL for any pad. + * @dest: (transfer none): the #GstElement containing the destination pad. + * @destpadname: (allow-none): the name of the #GstPad in destination element, * or NULL for any pad. * * Links the two named pads of the source and destination elements. @@ -1865,10 +1870,13 @@ gst_element_link_pads (GstElement * src, const gchar * srcpadname, /** * gst_element_link_pads_filtered: * @src: a #GstElement containing the source pad. - * @srcpadname: the name of the #GstPad in source element or NULL for any pad. - * @dest: the #GstElement containing the destination pad. - * @destpadname: the name of the #GstPad in destination element or NULL for any pad. - * @filter: the #GstCaps to filter the link, or #NULL for no filter. + * @srcpadname: (allow-none): the name of the #GstPad in source element + * or NULL for any pad. + * @dest: (transfer none): the #GstElement containing the destination pad. + * @destpadname: (allow-none): the name of the #GstPad in destination element + * or NULL for any pad. + * @filter: (transfer none) (allow-none): the #GstCaps to filter the link, + * or #NULL for no filter. * * Links the two named pads of the source and destination elements. Side effect * is that if one of the pads has no parent, it becomes a child of the parent of @@ -1949,8 +1957,8 @@ gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname, /** * gst_element_link: - * @src: a #GstElement containing the source pad. - * @dest: the #GstElement containing the destination pad. + * @src: (transfer none): a #GstElement containing the source pad. + * @dest: (transfer none): the #GstElement containing the destination pad. * * Links @src to @dest. The link must be from source to * destination; the other direction will not be tried. The function looks for @@ -1971,8 +1979,8 @@ gst_element_link (GstElement * src, GstElement * dest) /** * gst_element_link_many: - * @element_1: the first #GstElement in the link chain. - * @element_2: the second #GstElement in the link chain. + * @element_1: (transfer none): the first #GstElement in the link chain. + * @element_2: (transfer none): the second #GstElement in the link chain. * @...: the NULL-terminated list of elements to link in order. * * Chain together a series of elements. Uses gst_element_link(). @@ -2010,8 +2018,9 @@ gst_element_link_many (GstElement * element_1, GstElement * element_2, ...) /** * gst_element_link_filtered: * @src: a #GstElement containing the source pad. - * @dest: the #GstElement containing the destination pad. - * @filter: the #GstCaps to filter the link, or #NULL for no filter. + * @dest: (transfer none): the #GstElement containing the destination pad. + * @filter: (transfer none) (allow-none): the #GstCaps to filter the link, + * or #NULL for no filter. * * Links @src to @dest using the given caps as filtercaps. * The link must be from source to @@ -2033,9 +2042,9 @@ gst_element_link_filtered (GstElement * src, GstElement * dest, /** * gst_element_unlink_pads: - * @src: a #GstElement containing the source pad. + * @src: a (transfer none): #GstElement containing the source pad. * @srcpadname: the name of the #GstPad in source element. - * @dest: a #GstElement containing the destination pad. + * @dest: (transfer none): a #GstElement containing the destination pad. * @destpadname: the name of the #GstPad in destination element. * * Unlinks the two named pads of the source and destination elements. @@ -2088,8 +2097,8 @@ free_src: /** * gst_element_unlink_many: - * @element_1: the first #GstElement in the link chain. - * @element_2: the second #GstElement in the link chain. + * @element_1: (transfer none): the first #GstElement in the link chain. + * @element_2: (transfer none): the second #GstElement in the link chain. * @...: the NULL-terminated list of elements to unlink in order. * * Unlinks a series of elements. Uses gst_element_unlink(). @@ -2116,8 +2125,8 @@ gst_element_unlink_many (GstElement * element_1, GstElement * element_2, ...) /** * gst_element_unlink: - * @src: the source #GstElement to unlink. - * @dest: the sink #GstElement to unlink. + * @src: (transfer none): the source #GstElement to unlink. + * @dest: (transfer none): the sink #GstElement to unlink. * * Unlinks all source pads of the source element with all sink pads * of the sink element to which they are linked. @@ -2184,9 +2193,10 @@ gst_element_unlink (GstElement * src, GstElement * dest) /** * gst_element_query_position: * @element: a #GstElement to invoke the position query on. - * @format: a pointer to the #GstFormat asked for. + * @format: (inout): a pointer to the #GstFormat asked for. * On return contains the #GstFormat used. - * @cur: A location in which to store the current position, or NULL. + * @cur: (out) (allow-none): a location in which to store the current + * position, or NULL. * * Queries an element for the stream position. * @@ -2248,10 +2258,10 @@ gst_element_query_duration (GstElement * element, GstFormat * format, /** * gst_element_query_convert: * @element: a #GstElement to invoke the convert query on. - * @src_format: a #GstFormat to convert from. + * @src_format: (inout): a #GstFormat to convert from. * @src_val: a value to convert. - * @dest_format: a pointer to the #GstFormat to convert to. - * @dest_val: a pointer to the result. + * @dest_format: (inout): a pointer to the #GstFormat to convert to. + * @dest_val: (out): a pointer to the result. * * Queries an element to convert @src_val in @src_format to @dest_format. * @@ -2352,7 +2362,9 @@ gst_pad_use_fixed_caps (GstPad * pad) * will return the currently negotiated caps or the padtemplate * when NULL. * - * Returns: The currently negotiated caps or the padtemplate. + * Free-function: gst_caps_unref + * + * Returns: (transfer full): the currently negotiated caps or the padtemplate. */ GstCaps * gst_pad_get_fixed_caps_func (GstPad * pad) @@ -2394,8 +2406,8 @@ gst_pad_get_fixed_caps_func (GstPad * pad) * Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or * its parent is not an element, return NULL. * - * Returns: The parent of the pad. The caller has a reference on the parent, so - * unref when you're finished with it. + * Returns: (transfer full): the parent of the pad. The caller has a + * reference on the parent, so unref when you're finished with it. * * MT safe. */ @@ -2418,8 +2430,8 @@ gst_pad_get_parent_element (GstPad * pad) /** * gst_object_default_error: * @source: the #GstObject that initiated the error. - * @error: the GError. - * @debug: an additional debug information string, or NULL. + * @error: (in): the GError. + * @debug: (in) (allow-none): an additional debug information string, or NULL * * A default error function. * @@ -2440,8 +2452,8 @@ gst_object_default_error (GstObject * source, GError * error, gchar * debug) /** * gst_bin_add_many: * @bin: a #GstBin - * @element_1: the #GstElement element to add to the bin - * @...: additional elements to add to the bin + * @element_1: (transfer full): the #GstElement element to add to the bin + * @...: (transfer full): additional elements to add to the bin * * Adds a NULL-terminated list of elements to a bin. This function is * equivalent to calling gst_bin_add() for each member of the list. The return @@ -2469,8 +2481,8 @@ gst_bin_add_many (GstBin * bin, GstElement * element_1, ...) /** * gst_bin_remove_many: * @bin: a #GstBin - * @element_1: the first #GstElement to remove from the bin - * @...: NULL-terminated list of elements to remove from the bin + * @element_1: (transfer none): the first #GstElement to remove from the bin + * @...: (transfer none): NULL-terminated list of elements to remove from the bin * * Remove a list of elements from a bin. This function is equivalent * to calling gst_bin_remove() with each member of the list. @@ -2618,8 +2630,8 @@ gst_element_class_install_std_props (GstElementClass * klass, /** * gst_buffer_merge: - * @buf1: the first source #GstBuffer to merge. - * @buf2: the second source #GstBuffer to merge. + * @buf1: (transfer none): the first source #GstBuffer to merge. + * @buf2: (transfer none): the second source #GstBuffer to merge. * * Create a new buffer that is the concatenation of the two source * buffers. The original source buffers will not be modified or @@ -2629,7 +2641,10 @@ gst_element_class_install_std_props (GstElementClass * klass, * If the buffers point to contiguous areas of memory, the buffer * is created without copying the data. * - * Returns: the new #GstBuffer which is the concatenation of the source buffers. + * Free-function: gst_buffer_unref + * + * Returns: (transfer full): the new #GstBuffer which is the concatenation + * of the source buffers. */ GstBuffer * gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2) @@ -2675,7 +2690,7 @@ gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2) /** * gst_buffer_stamp: - * @dest: buffer to stamp + * @dest: (transfer none): buffer to stamp * @src: buffer to stamp from * * Copies additional information (the timestamp, duration, and offset start @@ -2730,7 +2745,9 @@ getcaps_fold_func (GstPad * pad, GValue * ret, GstPad * orig) * that can handle any stream format, but requires all its pads to have * the same caps. Two such elements are tee and adder. * - * Returns: the intersection of the other pads' allowed caps. + * Free-function: gst_caps_unref + * + * Returns: (transfer full): the intersection of the other pads' allowed caps. */ GstCaps * gst_pad_proxy_getcaps (GstPad * pad) @@ -2845,7 +2862,7 @@ setcaps_fold_func (GstPad * pad, GValue * ret, SetCapsFoldData * data) /** * gst_pad_proxy_setcaps * @pad: a #GstPad to proxy from - * @caps: the #GstCaps to link with + * @caps: (transfer none): the #GstCaps to link with * * Calls gst_pad_set_caps() for every other pad belonging to the * same element as @pad. If gst_pad_set_caps() fails on any pad, @@ -2956,9 +2973,10 @@ gst_pad_query_position (GstPad * pad, GstFormat * format, gint64 * cur) * gst_pad_query_peer_position: * @pad: a #GstPad on whose peer to invoke the position query on. * Must be a sink pad. - * @format: a pointer to the #GstFormat asked for. + * @format: (inout): a pointer to the #GstFormat asked for. * On return contains the #GstFormat used. - * @cur: A location in which to store the current position, or NULL. + * @cur: (out) (allow-none): a location in which to store the current + * position, or NULL. * * Queries the peer of a given sink pad for the stream position. * @@ -2986,9 +3004,10 @@ gst_pad_query_peer_position (GstPad * pad, GstFormat * format, gint64 * cur) /** * gst_pad_query_duration: * @pad: a #GstPad to invoke the duration query on. - * @format: a pointer to the #GstFormat asked for. + * @format: (inout): a pointer to the #GstFormat asked for. * On return contains the #GstFormat used. - * @duration: A location in which to store the total duration, or NULL. + * @duration: (out) (allow-none): a location in which to store the total + * duration, or NULL. * * Queries a pad for the total stream duration. * @@ -3018,9 +3037,10 @@ gst_pad_query_duration (GstPad * pad, GstFormat * format, gint64 * duration) * gst_pad_query_peer_duration: * @pad: a #GstPad on whose peer pad to invoke the duration query on. * Must be a sink pad. - * @format: a pointer to the #GstFormat asked for. + * @format: (inout) :a pointer to the #GstFormat asked for. * On return contains the #GstFormat used. - * @duration: A location in which to store the total duration, or NULL. + * @duration: (out) (allow-none): a location in which to store the total + * duration, or NULL. * * Queries the peer pad of a given sink pad for the total stream duration. * @@ -3051,8 +3071,8 @@ gst_pad_query_peer_duration (GstPad * pad, GstFormat * format, * @pad: a #GstPad to invoke the convert query on. * @src_format: a #GstFormat to convert from. * @src_val: a value to convert. - * @dest_format: a pointer to the #GstFormat to convert to. - * @dest_val: a pointer to the result. + * @dest_format: (inout): a pointer to the #GstFormat to convert to. + * @dest_val: (out): a pointer to the result. * * Queries a pad to convert @src_val in @src_format to @dest_format. * @@ -3091,8 +3111,8 @@ gst_pad_query_convert (GstPad * pad, GstFormat src_format, gint64 src_val, * Must be a sink pad. * @src_format: a #GstFormat to convert from. * @src_val: a value to convert. - * @dest_format: a pointer to the #GstFormat to convert to. - * @dest_val: a pointer to the result. + * @dest_format: (inout): a pointer to the #GstFormat to convert to. + * @dest_val: (out): a pointer to the result. * * Queries the peer pad of a given sink pad to convert @src_val in @src_format * to @dest_format. @@ -3123,7 +3143,7 @@ gst_pad_query_peer_convert (GstPad * pad, GstFormat src_format, gint64 src_val, /** * gst_atomic_int_set: - * @atomic_int: pointer to an atomic integer + * @atomic_int: (inout): pointer to an atomic integer * @value: value to set * * Unconditionally sets the atomic integer to @value. @@ -3146,7 +3166,7 @@ gst_atomic_int_set (gint * atomic_int, gint value) * gst_pad_add_data_probe: * @pad: pad to add the data probe handler to * @handler: function to call when data is passed over pad - * @data: data to pass along with the handler + * @data: (closure): data to pass along with the handler * * Adds a "data probe" to a pad. This function will be called whenever data * passes through a pad. In this case data means both events and buffers. The @@ -3182,8 +3202,9 @@ gst_pad_add_data_probe (GstPad * pad, GCallback handler, gpointer data) * gst_pad_add_data_probe_full: * @pad: pad to add the data probe handler to * @handler: function to call when data is passed over pad - * @data: data to pass along with the handler - * @notify: function to call when the probe is disconnected, or NULL + * @data: (closure): data to pass along with the handler + * @notify: (allow-none): function to call when the probe is disconnected, + * or NULL * * Adds a "data probe" to a pad. This function will be called whenever data * passes through a pad. In this case data means both events and buffers. The @@ -3244,7 +3265,7 @@ gst_pad_add_data_probe_full (GstPad * pad, GCallback handler, * gst_pad_add_event_probe: * @pad: pad to add the event probe handler to * @handler: function to call when events are passed over pad - * @data: data to pass along with the handler + * @data: (closure): data to pass along with the handler * * Adds a probe that will be called for all events passing through a pad. See * gst_pad_add_data_probe() for more information. @@ -3261,8 +3282,8 @@ gst_pad_add_event_probe (GstPad * pad, GCallback handler, gpointer data) * gst_pad_add_event_probe_full: * @pad: pad to add the event probe handler to * @handler: function to call when events are passed over pad - * @data: data to pass along with the handler, or NULL - * @notify: function to call when probe is disconnected, or NULL + * @data: (closure): data to pass along with the handler, or NULL + * @notify: (allow-none): function to call when probe is disconnected, or NULL * * Adds a probe that will be called for all events passing through a pad. See * gst_pad_add_data_probe() for more information. @@ -3302,7 +3323,7 @@ gst_pad_add_event_probe_full (GstPad * pad, GCallback handler, * gst_pad_add_buffer_probe: * @pad: pad to add the buffer probe handler to * @handler: function to call when buffers are passed over pad - * @data: data to pass along with the handler + * @data: (closure): data to pass along with the handler * * Adds a probe that will be called for all buffers passing through a pad. See * gst_pad_add_data_probe() for more information. @@ -3319,8 +3340,9 @@ gst_pad_add_buffer_probe (GstPad * pad, GCallback handler, gpointer data) * gst_pad_add_buffer_probe_full: * @pad: pad to add the buffer probe handler to * @handler: function to call when buffer are passed over pad - * @data: data to pass along with the handler - * @notify: function to call when the probe is disconnected, or NULL + * @data: (closure): data to pass along with the handler + * @notify: (allow-none): function to call when the probe is disconnected, + * or NULL * * Adds a probe that will be called for all buffers passing through a pad. See * gst_pad_add_data_probe() for more information. @@ -3428,8 +3450,8 @@ gst_pad_remove_buffer_probe (GstPad * pad, guint handler_id) /** * gst_element_found_tags_for_pad: * @element: element for which to post taglist to bus. - * @pad: pad on which to push tag-event. - * @list: the taglist to post on the bus and create event from. + * @pad: (transfer none): pad on which to push tag-event + * @list: (transfer full): 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 @list. @@ -3462,7 +3484,7 @@ push_and_ref (GstPad * pad, GstEvent * event) /** * gst_element_found_tags: * @element: element for which we found the tags. - * @list: list of tags. + * @list: (transfer full): 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 @list. @@ -3559,7 +3581,7 @@ element_find_unlinked_pad (GstElement * element, GstPadDirection direction) * owns a reference to it and should use gst_object_unref() on the * pad when it is not needed any longer. * - * Returns: unlinked pad of the given direction, or NULL. + * Returns: (transfer full): unlinked pad of the given direction, or NULL. * * Since: 0.10.20 */ @@ -3613,7 +3635,7 @@ gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction) * owns a reference to it and should use gst_object_unref() on the * pad when it is not needed any longer. * - * Returns: unlinked pad of the given direction, or NULL. + * Returns: (transfer full): unlinked pad of the given direction, or NULL. * * Since: 0.10.3 * @@ -3664,7 +3686,8 @@ gst_parse_bin_from_description (const gchar * bin_description, * @bin_description: command line describing the bin * @ghost_unlinked_pads: whether to automatically create ghost pads * for unlinked source or sink pads within the bin - * @context: a parse context allocated with gst_parse_context_new(), or %NULL + * @context: (transfer none) (allow-none): a parse context allocated with + * gst_parse_context_new(), or %NULL * @flags: parsing options, or #GST_PARSE_FLAG_NONE * @err: where to store the error message in case of an error, or NULL * @@ -3838,7 +3861,7 @@ gst_util_get_timestamp (void) * @search_func: function to compare two elements, @search_data will always be passed as second argument * @mode: search mode that should be used * @search_data: element that should be found - * @user_data: data to pass to @search_func + * @user_data: (closure): data to pass to @search_func * * Searches inside @array for @search_data by using the comparison function * @search_func. @array must be sorted ascending. @@ -3951,7 +3974,7 @@ gst_util_greatest_common_divisor (gint a, gint b) * gst_util_fraction_to_double: * @src_n: Fraction numerator as #gint * @src_d: Fraction denominator #gint - * @dest: pointer to a #gdouble for the result + * @dest: (out): pointer to a #gdouble for the result * * Transforms a #gdouble to a fraction and simplifies the result. * @@ -3978,8 +4001,8 @@ gst_util_fraction_to_double (gint src_n, gint src_d, gdouble * dest) /** * gst_util_double_to_fraction: * @src: #gdouble to transform - * @dest_n: pointer to a #gint to hold the result numerator - * @dest_d: pointer to a #gint to hold the result denominator + * @dest_n: (out): pointer to a #gint to hold the result numerator + * @dest_d: (out): pointer to a #gint to hold the result denominator * * Transforms a #gdouble to a fraction and simplifies * the result. @@ -4077,8 +4100,8 @@ gst_util_double_to_fraction (gdouble src, gint * dest_n, gint * dest_d) * @a_d: Denominator of first value * @b_n: Numerator of second value * @b_d: Denominator of second value - * @res_n: Pointer to #gint to hold the result numerator - * @res_d: Pointer to #gint to hold the result denominator + * @res_n: (out): Pointer to #gint to hold the result numerator + * @res_d: (out): Pointer to #gint to hold the result denominator * * Multiplies the fractions @a_n/@a_d and @b_n/@b_d and stores * the result in @res_n and @res_d. @@ -4136,8 +4159,8 @@ gst_util_fraction_multiply (gint a_n, gint a_d, gint b_n, gint b_d, * @a_d: Denominator of first value * @b_n: Numerator of second value * @b_d: Denominator of second value - * @res_n: Pointer to #gint to hold the result numerator - * @res_d: Pointer to #gint to hold the result denominator + * @res_n: (out): Pointer to #gint to hold the result numerator + * @res_d: (out): Pointer to #gint to hold the result denominator * * Adds the fractions @a_n/@a_d and @b_n/@b_d and stores * the result in @res_n and @res_d. diff --git a/gst/gstvalue.c b/gst/gstvalue.c index 30c03ecf23..f03ebf89d2 100644 --- a/gst/gstvalue.c +++ b/gst/gstvalue.c @@ -336,7 +336,7 @@ gst_value_list_prepend_value (GValue * value, const GValue * prepend_value) /** * gst_value_list_concat: - * @dest: an uninitialized #GValue to take the result + * @dest: (out caller-allocates): an uninitialized #GValue to take the result * @value1: a #GValue * @value2: a #GValue * @@ -408,7 +408,7 @@ gst_value_list_get_size (const GValue * value) * Gets the value that is a member of the list contained in @value and * has the index @index. * - * Returns: the value at the given index + * Returns: (transfer none): the value at the given index */ const GValue * gst_value_list_get_value (const GValue * value, guint index) @@ -482,7 +482,7 @@ gst_value_array_get_size (const GValue * value) * Gets the value that is a member of the array contained in @value and * has the index @index. * - * Returns: the value at the given index + * Returns: (transfer none): the value at the given index */ const GValue * gst_value_array_get_value (const GValue * value, guint index) @@ -1480,7 +1480,7 @@ gst_value_deserialize_fraction_range (GValue * dest, const gchar * s) /** * gst_value_set_caps: * @value: a GValue initialized to GST_TYPE_CAPS - * @caps: the caps to set the value to + * @caps: (transfer none): the caps to set the value to * * Sets the contents of @value to @caps. A reference to the * provided @caps will be taken by the @value. @@ -1503,7 +1503,7 @@ gst_value_set_caps (GValue * value, const GstCaps * caps) * #GstCaps will not be modified, therefore the caller must take one * before getting rid of the @value. * - * Returns: the contents of @value + * Returns: (transfer none): the contents of @value */ const GstCaps * gst_value_get_caps (const GValue * value) @@ -1565,7 +1565,7 @@ gst_value_set_structure (GValue * value, const GstStructure * structure) * * Gets the contents of @value. * - * Returns: the contents of @value + * Returns: (transfer none): the contents of @value * * Since: 0.10.15 */ @@ -3370,7 +3370,7 @@ gst_value_can_union (const GValue * value1, const GValue * value2) /** * gst_value_union: - * @dest: the destination value + * @dest: (out caller-allocates): the destination value * @value1: a value to union * @value2: another value to union * @@ -3489,7 +3489,7 @@ gst_value_can_intersect (const GValue * value1, const GValue * value2) /** * gst_value_intersect: - * @dest: a uninitialized #GValue that will hold the calculated + * @dest: (out caller-allocates): a uninitialized #GValue that will hold the calculated * intersection value * @value1: a value to intersect * @value2: another value to intersect @@ -3575,7 +3575,8 @@ gst_value_register_intersect_func (GType type1, GType type2, /** * gst_value_subtract: - * @dest: the destination value for the result if the subtraction is not empty + * @dest: (out caller-allocates): the destination value for the result if the + * subtraction is not empty * @minuend: the value to subtract from * @subtrahend: the value to subtract * @@ -3732,7 +3733,7 @@ gst_value_register (const GstValueTable * table) /** * gst_value_init_and_copy: - * @dest: the target value + * @dest: (out caller-allocates): the target value * @src: the source value * * Initialises the target value to be of the same type as source and then copies @@ -3755,7 +3756,9 @@ gst_value_init_and_copy (GValue * dest, const GValue * src) * tries to transform the given @value into a string representation that allows * getting back this string later on using gst_value_deserialize(). * - * Returns: the serialization for @value or NULL if none exists + * Free-function: g_free + * + * Returns: (transfer full): the serialization for @value or NULL if none exists */ gchar * gst_value_serialize (const GValue * value) @@ -3799,7 +3802,8 @@ gst_value_serialize (const GValue * value) /** * gst_value_deserialize: - * @dest: #GValue to fill with contents of deserialization + * @dest: (out caller-allocates): #GValue to fill with contents of + * deserialization * @src: string to deserialize * * Tries to deserialize a string into the type specified by the given GValue. @@ -4261,7 +4265,7 @@ gst_value_set_date (GValue * value, const GDate * date) * * Gets the contents of @value. * - * Returns: the contents of @value + * Returns: (transfer none): the contents of @value */ const GDate * gst_value_get_date (const GValue * value) diff --git a/gst/gstvalue.h b/gst/gstvalue.h index d3ccb4d4ca..9e921715e8 100644 --- a/gst/gstvalue.h +++ b/gst/gstvalue.h @@ -352,7 +352,9 @@ typedef gint (* GstValueCompareFunc) (const GValue *value1, * * Used by gst_value_serialize() to obtain a non-binary form of the #GValue. * - * Returns: the string representation of the value + * Free-function: g_free + * + * Returns: (transfer full): the string representation of the value */ typedef gchar * (* GstValueSerializeFunc) (const GValue *value1); @@ -385,7 +387,7 @@ typedef gboolean (* GstValueUnionFunc) (GValue *dest, /** * GstValueIntersectFunc: - * @dest: a #GValue for the result + * @dest: (out caller-allocates): a #GValue for the result * @value1: a #GValue operand * @value2: a #GValue operand * @@ -403,7 +405,7 @@ typedef gboolean (* GstValueIntersectFunc) (GValue *dest, /** * GstValueSubtractFunc: - * @dest: a #GValue for the result + * @dest: (out caller-allocates): a #GValue for the result * @minuend: a #GValue operand * @subtrahend: a #GValue operand * |