gst: Fix up a bunch of GIR annotations
This is mostly on nullable return values, and some other minor ones that
I ran across.
https://bugzilla.gnome.org/show_bug.cgi?id=789319
diff --git a/gst/gst.c b/gst/gst.c
index b383f41..42adb9d 100644
--- a/gst/gst.c
+++ b/gst/gst.c
@@ -237,7 +237,7 @@
* threading system as one of the very first things in your program
* (see the example at the beginning of this section).
*
- * Returns: (transfer full): a pointer to GStreamer's option group.
+ * Returns: (transfer full) (nullable): a pointer to GStreamer's option group.
*/
GOptionGroup *
@@ -375,7 +375,7 @@
* external process, the returned path will be the same as from the
* parent process.
*
- * Returns: (transfer none): The path of the executable that
+ * Returns: (transfer none) (nullable): The path of the executable that
* initialized GStreamer, or %NULL if it could not be determined.
*
* Since: 1.14
diff --git a/gst/gstallocator.c b/gst/gstallocator.c
index 38a7d4f..4b78a33 100644
--- a/gst/gstallocator.c
+++ b/gst/gstallocator.c
@@ -159,13 +159,13 @@
/**
* gst_allocation_params_copy:
- * @params: (transfer none): a #GstAllocationParams
+ * @params: (transfer none) (nullable): a #GstAllocationParams
*
* Create a copy of @params.
*
* Free-function: gst_allocation_params_free
*
- * Returns: (transfer full): a new ##GstAllocationParams, free with
+ * Returns: (transfer full) (nullable): a new ##GstAllocationParams, free with
* gst_allocation_params_free().
*/
GstAllocationParams *
@@ -290,7 +290,7 @@
* the amount of bytes to align to. For example, to align to 8 bytes,
* use an alignment of 7.
*
- * Returns: (transfer full): a new #GstMemory.
+ * Returns: (transfer full) (nullable): a new #GstMemory.
*/
GstMemory *
gst_allocator_alloc (GstAllocator * allocator, gsize size,
@@ -631,7 +631,7 @@
* The prefix/padding must be filled with 0 if @flags contains
* #GST_MEMORY_FLAG_ZERO_PREFIXED and #GST_MEMORY_FLAG_ZERO_PADDED respectively.
*
- * Returns: (transfer full): a new #GstMemory.
+ * Returns: (transfer full) (nullable): a new #GstMemory.
*/
GstMemory *
gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data,
diff --git a/gst/gstbin.c b/gst/gstbin.c
index d6ec582..3719c40 100644
--- a/gst/gstbin.c
+++ b/gst/gstbin.c
@@ -4549,7 +4549,8 @@
*
* MT safe. Caller owns returned reference.
*
- * Returns: (transfer full): A #GstElement inside the bin implementing the interface
+ * Returns: (transfer full) (nullable): A #GstElement inside the bin
+ * implementing the interface
*/
GstElement *
gst_bin_get_by_interface (GstBin * bin, GType iface)
diff --git a/gst/gstbuffer.c b/gst/gstbuffer.c
index 27cc0d8..73c5182 100644
--- a/gst/gstbuffer.c
+++ b/gst/gstbuffer.c
@@ -1080,7 +1080,7 @@
* the memory block in @buffer is removed, replaced or merged, typically with
* any call that modifies the memory in @buffer.
*
- * Returns: (transfer none): the #GstMemory at @idx.
+ * Returns: (transfer none) (nullable): the #GstMemory at @idx.
*/
GstMemory *
gst_buffer_peek_memory (GstBuffer * buffer, guint idx)
@@ -1101,7 +1101,7 @@
*
* Get the memory block at index @idx in @buffer.
*
- * Returns: (transfer full): a #GstMemory that contains the data of the
+ * Returns: (transfer full) (nullable): a #GstMemory that contains the data of the
* memory block at @idx. Use gst_memory_unref () after usage.
*/
GstMemory *
@@ -1117,7 +1117,7 @@
* Get all the memory block in @buffer. The memory blocks will be merged
* into one large #GstMemory.
*
- * Returns: (transfer full): a #GstMemory that contains the merged memory.
+ * Returns: (transfer full) (nullable): a #GstMemory that contains the merged memory.
* Use gst_memory_unref () after usage.
*/
GstMemory *
@@ -1137,7 +1137,7 @@
*
* If @length is -1, all memory starting from @idx is merged.
*
- * Returns: (transfer full): a #GstMemory that contains the merged data of @length
+ * Returns: (transfer full) (nullable): a #GstMemory that contains the merged data of @length
* blocks starting at @idx. Use gst_memory_unref () after usage.
*/
GstMemory *
@@ -2147,7 +2147,7 @@
*
* Add metadata for @info to @buffer using the parameters in @params.
*
- * Returns: (transfer none): the metadata for the api in @info on @buffer.
+ * Returns: (transfer none) (nullable): the metadata for the api in @info on @buffer.
*/
GstMeta *
gst_buffer_add_meta (GstBuffer * buffer, const GstMetaInfo * info,
@@ -2430,7 +2430,7 @@
* Add a #GstParentBufferMeta to @buffer that holds a reference on
* @ref until the buffer is freed.
*
- * Returns: (transfer none): The #GstParentBufferMeta that was added to the buffer
+ * Returns: (transfer none) (nullable): The #GstParentBufferMeta that was added to the buffer
*
* Since: 1.6
*/
@@ -2561,7 +2561,7 @@
* optionally @duration based on a specific timestamp @reference. See the
* documentation of #GstReferenceTimestampMeta for details.
*
- * Returns: (transfer none): The #GstReferenceTimestampMeta that was added to the buffer
+ * Returns: (transfer none) (nullable): The #GstReferenceTimestampMeta that was added to the buffer
*
* Since: 1.14
*/
@@ -2599,7 +2599,7 @@
*
* Buffers can contain multiple #GstReferenceTimestampMeta metadata items.
*
- * Returns: (transfer none): the #GstReferenceTimestampMeta or %NULL when there
+ * Returns: (transfer none) (nullable): the #GstReferenceTimestampMeta or %NULL when there
* is no such metadata on @buffer.
*
* Since: 1.14
diff --git a/gst/gstbus.c b/gst/gstbus.c
index 55a65cc..81f2fb9 100644
--- a/gst/gstbus.c
+++ b/gst/gstbus.c
@@ -888,7 +888,7 @@
* a message is on the bus. After the GSource is dispatched, the
* message is popped off the bus and unreffed.
*
- * Returns: (transfer full): a #GSource that can be added to a mainloop.
+ * Returns: (transfer full) (nullable): a #GSource that can be added to a mainloop.
*/
GSource *
gst_bus_create_watch (GstBus * bus)
diff --git a/gst/gstcaps.c b/gst/gstcaps.c
index a637311..d660e52 100644
--- a/gst/gstcaps.c
+++ b/gst/gstcaps.c
@@ -395,9 +395,10 @@
*
* Converts a #GstStaticCaps to a #GstCaps.
*
- * 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.
+ * Returns: (transfer full) (nullable): 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)
@@ -513,8 +514,8 @@
* Retrieves the structure with the given index from the list of structures
* contained in @caps. The caller becomes the owner of the returned structure.
*
- * Returns: (transfer full): a pointer to the #GstStructure corresponding
- * to @index.
+ * Returns: (transfer full) (nullable): a pointer to the #GstStructure
+ * corresponding to @index.
*/
GstStructure *
gst_caps_steal_structure (GstCaps * caps, guint index)
@@ -856,8 +857,8 @@
* You do not need to free or unref the structure returned, it
* belongs to the #GstCaps.
*
- * Returns: (transfer none): a pointer to the #GstCapsFeatures corresponding
- * to @index
+ * Returns: (transfer none) (nullable): a pointer to the #GstCapsFeatures
+ * corresponding to @index
*
* Since: 1.2
*/
@@ -2361,7 +2362,7 @@
* The current implementation of serialization will lead to unexpected results
* when there are nested #GstCaps / #GstStructure deeper than one level.
*
- * Returns: (transfer full): a newly allocated #GstCaps
+ * Returns: (transfer full) (nullable): a newly allocated #GstCaps
*/
GstCaps *
gst_caps_from_string (const gchar * string)
diff --git a/gst/gstcapsfeatures.c b/gst/gstcapsfeatures.c
index e501b93..9215de8 100644
--- a/gst/gstcapsfeatures.c
+++ b/gst/gstcapsfeatures.c
@@ -593,7 +593,7 @@
*
* Returns the @i-th feature of @features.
*
- * Returns: The @i-th feature of @features.
+ * Returns: (nullable): The @i-th feature of @features.
*
* Since: 1.2
*/
diff --git a/gst/gstdatetime.c b/gst/gstdatetime.c
index 67cdd6c..93205f1 100644
--- a/gst/gstdatetime.c
+++ b/gst/gstdatetime.c
@@ -498,7 +498,7 @@
*
* Free-function: gst_date_time_unref
*
- * Return value: (transfer full): the newly created #GstDateTime
+ * Return value: (transfer full) (nullable): the newly created #GstDateTime
*/
GstDateTime *
gst_date_time_new_local_time (gint year, gint month, gint day, gint hour,
@@ -607,7 +607,7 @@
*
* Free-function: gst_date_time_unref
*
- * Return value: (transfer full): the newly created #GstDateTime
+ * Return value: (transfer full) (nullable): the newly created #GstDateTime
*/
GstDateTime *
gst_date_time_new (gfloat tzoffset, gint year, gint month, gint day, gint hour,
diff --git a/gst/gstdevice.c b/gst/gstdevice.c
index c30d021..8a46752 100644
--- a/gst/gstdevice.c
+++ b/gst/gstdevice.c
@@ -199,7 +199,8 @@
* Creates the element with all of the required parameters set to use
* this device.
*
- * Returns: (transfer full): a new #GstElement configured to use this device
+ * Returns: (transfer full) (nullable): a new #GstElement configured to use
+ * this device
*
* Since: 1.4
*/
@@ -222,7 +223,7 @@
*
* Getter for the #GstCaps that this device supports.
*
- * Returns: The #GstCaps supported by this device. Unref with
+ * Returns: (nullable): The #GstCaps supported by this device. Unref with
* gst_caps_unref() when done.
*
* Since: 1.4
@@ -286,7 +287,7 @@
*
* Gets the extra properties of a device.
*
- * Returns: The extra properties or %NULL when there are none.
+ * Returns: (nullable): The extra properties or %NULL when there are none.
* Free with gst_structure_free() after use.
*
* Since: 1.6
diff --git a/gst/gstdevicemonitor.c b/gst/gstdevicemonitor.c
index 03b4621..e0b59ec 100644
--- a/gst/gstdevicemonitor.c
+++ b/gst/gstdevicemonitor.c
@@ -342,7 +342,7 @@
* Gets a list of devices from all of the relevant monitors. This may actually
* probe the hardware if the monitor is not currently started.
*
- * Returns: (transfer full) (element-type GstDevice): a #GList of
+ * Returns: (transfer full) (element-type GstDevice) (nullable): a #GList of
* #GstDevice
*
* Since: 1.4
diff --git a/gst/gstdeviceprovider.c b/gst/gstdeviceprovider.c
index 8fb0abb..83bb54b 100644
--- a/gst/gstdeviceprovider.c
+++ b/gst/gstdeviceprovider.c
@@ -337,7 +337,7 @@
*
* Get metadata with @key in @klass.
*
- * Returns: the metadata for @key.
+ * Returns: (nullable): the metadata for @key.
*
* Since: 1.4
*/
diff --git a/gst/gstelement.c b/gst/gstelement.c
index a18363f..8a908a1 100644
--- a/gst/gstelement.c
+++ b/gst/gstelement.c
@@ -444,7 +444,7 @@
* Elements in a pipeline will only have their clock set when the
* pipeline is in the PLAYING state.
*
- * Returns: (transfer full): the #GstClock of the element. unref after usage.
+ * Returns: (transfer full) (nullable): the #GstClock of the element. unref after usage.
*
* MT safe.
*/
@@ -3381,7 +3381,8 @@
* Returns the bus of the element. Note that only a #GstPipeline will provide a
* bus for the application.
*
- * Returns: (transfer full): the element's #GstBus. unref after usage.
+ * Returns: (transfer full) (nullable): the element's #GstBus. unref after
+ * usage.
*
* MT safe.
*/
@@ -3505,7 +3506,7 @@
*
* Gets the context with @context_type set on the element or NULL.
*
- * Returns: (transfer full): A #GstContext or NULL
+ * Returns: (transfer full) (nullable): A #GstContext or NULL
*
* Since: 1.8
*/
diff --git a/gst/gstevent.c b/gst/gstevent.c
index 41e5b0b..c41a73b 100644
--- a/gst/gstevent.c
+++ b/gst/gstevent.c
@@ -293,7 +293,7 @@
* New custom events can also be created by subclassing the event type if
* needed.
*
- * Returns: (transfer full): the new custom event.
+ * Returns: (transfer full) (nullable): the new custom event.
*/
GstEvent *
gst_event_new_custom (GstEventType type, GstStructure * structure)
@@ -801,7 +801,7 @@
* synchronized with the buffer flow and contains the format of the buffers
* that will follow after the event.
*
- * Returns: (transfer full): the new CAPS event.
+ * Returns: (transfer full) (nullable): the new CAPS event.
*/
GstEvent *
gst_event_new_caps (GstCaps * caps)
@@ -879,7 +879,7 @@
*
* time + (TIMESTAMP(buf) - start) * ABS (rate * applied_rate)
*
- * Returns: (transfer full): the new SEGMENT event.
+ * Returns: (transfer full) (nullable): the new SEGMENT event.
*/
GstEvent *
gst_event_new_segment (const GstSegment * segment)
@@ -1128,7 +1128,7 @@
* The application can use general event probes to intercept the QoS
* event and implement custom application specific QoS handling.
*
- * Returns: (transfer full): a new QOS event.
+ * Returns: (transfer full) (nullable): a new QOS event.
*/
GstEvent *
gst_event_new_qos (GstQOSType type, gdouble proportion,
@@ -1254,7 +1254,7 @@
* #GST_QUERY_POSITION and update the playback segment current position with a
* #GST_SEEK_TYPE_SET to the desired position.
*
- * Returns: (transfer full): a new seek event.
+ * Returns: (transfer full) (nullable): a new seek event.
*/
GstEvent *
gst_event_new_seek (gdouble rate, GstFormat format, GstSeekFlags flags,
@@ -1435,7 +1435,7 @@
* The @intermediate flag instructs the pipeline that this step operation is
* part of a larger step operation.
*
- * Returns: (transfer full): a new #GstEvent
+ * Returns: (transfer full) (nullable): a new #GstEvent
*/
GstEvent *
gst_event_new_step (GstFormat format, guint64 amount, gdouble rate,
diff --git a/gst/gstinfo.c b/gst/gstinfo.c
index 0f8cb8a..8bb1a2a 100644
--- a/gst/gstinfo.c
+++ b/gst/gstinfo.c
@@ -574,7 +574,7 @@
* Gets the string representation of a #GstDebugMessage. This function is used
* in debug handlers to extract the message.
*
- * Returns: the string representation of a #GstDebugMessage.
+ * Returns: (nullable): the string representation of a #GstDebugMessage.
*/
const gchar *
gst_debug_message_get (GstDebugMessage * message)
@@ -2439,7 +2439,7 @@
*
* Free with g_free().
*
- * Returns: a newly allocated null terminated string or %NULL on any error
+ * Returns: (nullable): a newly allocated null terminated string or %NULL on any error
*
* Since: 1.8
*/
@@ -2466,7 +2466,7 @@
*
* Free with g_free().
*
- * Returns: a newly allocated null terminated string or %NULL on any error
+ * Returns: (nullable): a newly allocated null terminated string or %NULL on any error
*
* Since: 1.8
*/
@@ -2771,8 +2771,8 @@
* @flags: A set of #GstStackTraceFlags to determine how the stack
* trace should look like. Pass 0 to retrieve a minimal backtrace.
*
- * If libunwind or glibc backtrace are present, a stack trace
- * is returned.
+ * Returns: (nullable): a stack trace, if libunwind or glibc backtrace are
+ * present, else %NULL.
*
* Since: 1.12
*/
diff --git a/gst/gstmessage.c b/gst/gstmessage.c
index a5765da..e02a0c1 100644
--- a/gst/gstmessage.c
+++ b/gst/gstmessage.c
@@ -284,7 +284,7 @@
* handled by other message-specific functions to pass a message to the
* app. The structure field can be %NULL.
*
- * Returns: (transfer full): The new message.
+ * Returns: (transfer full) (nullable): The new message.
*
* MT safe.
*/
@@ -405,7 +405,7 @@
* occurred. The pipeline will probably (partially) stop. The application
* receiving this message should stop the pipeline.
*
- * Returns: (transfer full): the new error message.
+ * Returns: (transfer full) (nullable): the new error message.
*
* Since: 1.10
*/
@@ -497,7 +497,7 @@
* Create a new warning message. The message will make copies of @error and
* @debug.
*
- * Returns: (transfer full): the new warning message.
+ * Returns: (transfer full) (nullable): the new warning message.
*
* Since: 1.10
*/
@@ -587,7 +587,7 @@
* Create a new info message. The message will make copies of @error and
* @debug.
*
- * Returns: (transfer full): the new warning message.
+ * Returns: (transfer full) (nullable): the new warning message.
*
* Since: 1.10
*/
@@ -714,7 +714,7 @@
*
* MT safe.
*
- * Returns: (transfer full): The new buffering message.
+ * Returns: (transfer full) (nullable): The new buffering message.
*/
GstMessage *
gst_message_new_buffering (GstObject * src, gint percent)
@@ -984,7 +984,7 @@
* Create a new application-typed message. GStreamer will never create these
* messages; they are a gift from us to you. Enjoy.
*
- * Returns: (transfer full): The new application message.
+ * Returns: (transfer full) (nullable): The new application message.
*
* MT safe.
*/
@@ -1007,7 +1007,7 @@
* "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: (transfer full): The new element message.
+ * Returns: (transfer full) (nullable): The new element message.
*
* MT safe.
*/
@@ -1815,9 +1815,10 @@
*
* Extracts the object managing the streaming thread from @message.
*
- * Returns: a GValue containing the object that manages the streaming thread.
- * This object is usually of type GstTask but other types can be added in the
- * future. The object remains valid as long as @message is valid.
+ * Returns: (nullable): a GValue containing the object that manages the
+ * streaming thread. This object is usually of type GstTask but other types can
+ * be added in the future. The object remains valid as long as @message is
+ * valid.
*/
const GValue *
gst_message_get_stream_status_object (GstMessage * message)
@@ -2226,7 +2227,7 @@
* @code contains a well defined string describing the action.
* @text should contain a user visible string detailing the current action.
*
- * Returns: (transfer full): The new qos message.
+ * Returns: (transfer full) (nullable): The new qos message.
*/
GstMessage *
gst_message_new_progress (GstObject * src, GstProgressType type,
@@ -2911,7 +2912,7 @@
*
* Retrieves the #GstStream with index @index from the @message.
*
- * Returns: (transfer full): A #GstStream
+ * Returns: (transfer full) (nullable): A #GstStream
*
* Since: 1.10
*/
diff --git a/gst/gstmeta.c b/gst/gstmeta.c
index e177e58..84d9838 100644
--- a/gst/gstmeta.c
+++ b/gst/gstmeta.c
@@ -158,7 +158,8 @@
* The same @info can be retrieved later with gst_meta_get_info() by using
* @impl as the key.
*
- * Returns: (transfer none): a #GstMetaInfo that can be used to access metadata.
+ * Returns: (transfer none) (nullable): a #GstMetaInfo that can be used to
+ * access metadata.
*/
const GstMetaInfo *
diff --git a/gst/gstminiobject.c b/gst/gstminiobject.c
index fcba49d..b047f98 100644
--- a/gst/gstminiobject.c
+++ b/gst/gstminiobject.c
@@ -132,7 +132,8 @@
*
* MT safe
*
- * Returns: (transfer full): the new mini-object.
+ * Returns: (transfer full) (nullable): the new mini-object if copying is
+ * possible, %NULL otherwise.
*/
GstMiniObject *
gst_mini_object_copy (const GstMiniObject * mini_object)
@@ -521,7 +522,7 @@
* Replace the current #GstMiniObject pointer to by @olddata with %NULL and
* return the old value.
*
- * Returns: the #GstMiniObject at @oldata
+ * Returns: (nullable): the #GstMiniObject at @oldata
*/
GstMiniObject *
gst_mini_object_steal (GstMiniObject ** olddata)
diff --git a/gst/gstpad.c b/gst/gstpad.c
index 99f445e..ffecee9 100644
--- a/gst/gstpad.c
+++ b/gst/gstpad.c
@@ -2759,7 +2759,7 @@
* Gets the peer of @pad. This function refs the peer pad so
* you need to unref it after use.
*
- * Returns: (transfer full): the peer #GstPad. Unref after usage.
+ * Returns: (transfer full) (nullable): the peer #GstPad. Unref after usage.
*
* MT safe.
*/
@@ -5905,7 +5905,7 @@
* Gets the private data of a pad.
* No locking is performed in this function.
*
- * Returns: (transfer none): a #gpointer to the private data.
+ * Returns: (transfer none) (nullable): a #gpointer to the private data.
*/
gpointer
gst_pad_get_element_private (GstPad * pad)
@@ -6271,7 +6271,7 @@
* gst_pad_probe_info_get_event:
* @info: a #GstPadProbeInfo
*
- * Returns: (transfer none): The #GstEvent from the probe
+ * Returns: (transfer none) (nullable): The #GstEvent from the probe
*/
GstEvent *
@@ -6288,7 +6288,7 @@
* gst_pad_probe_info_get_query:
* @info: a #GstPadProbeInfo
*
- * Returns: (transfer none): The #GstQuery from the probe
+ * Returns: (transfer none) (nullable): The #GstQuery from the probe
*/
GstQuery *
@@ -6304,7 +6304,7 @@
* gst_pad_probe_info_get_buffer:
* @info: a #GstPadProbeInfo
*
- * Returns: (transfer none): The #GstBuffer from the probe
+ * Returns: (transfer none) (nullable): The #GstBuffer from the probe
*/
GstBuffer *
@@ -6319,7 +6319,7 @@
* gst_pad_probe_info_get_buffer_list:
* @info: a #GstPadProbeInfo
*
- * Returns: (transfer none): The #GstBufferList from the probe
+ * Returns: (transfer none) (nullable): The #GstBufferList from the probe
*/
GstBufferList *
diff --git a/gst/gstpadtemplate.c b/gst/gstpadtemplate.c
index 2827902..1df8e07 100644
--- a/gst/gstpadtemplate.c
+++ b/gst/gstpadtemplate.c
@@ -299,7 +299,7 @@
*
* Converts a #GstStaticPadTemplate into a #GstPadTemplate.
*
- * Returns: (transfer floating): a new #GstPadTemplate.
+ * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
*/
/* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
GstPadTemplate *
@@ -369,7 +369,7 @@
* Creates a new pad template with a name according to the given template
* and with the given arguments.
*
- * Returns: (transfer floating): a new #GstPadTemplate.
+ * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
*/
GstPadTemplate *
gst_pad_template_new (const gchar * name_template,
diff --git a/gst/gstparamspecs.c b/gst/gstparamspecs.c
index a41cc8e..7de51d7 100644
--- a/gst/gstparamspecs.c
+++ b/gst/gstparamspecs.c
@@ -164,7 +164,7 @@
* used in connection with g_object_class_install_property() in a GObjects's
* instance_init function.
*
- * Returns: (transfer full): a newly created parameter specification
+ * Returns: (transfer full) (nullable): a newly created parameter specification
*/
GParamSpec *
gst_param_spec_fraction (const gchar * name, const gchar * nick,
diff --git a/gst/gstparse.c b/gst/gstparse.c
index f1f0c22..e50d7e7 100644
--- a/gst/gstparse.c
+++ b/gst/gstparse.c
@@ -75,8 +75,8 @@
*
* Free-function: gst_parse_context_free
*
- * Returns: (transfer full): a newly-allocated parse context. Free with
- * gst_parse_context_free() when no longer needed.
+ * Returns: (transfer full) (nullable): a newly-allocated parse context. Free
+ * with gst_parse_context_free() when no longer needed.
*/
GstParseContext *
gst_parse_context_new (void)
@@ -99,7 +99,7 @@
*
* Copies the @context.
*
- * Returns: (transfer full): A copied #GstParseContext
+ * Returns: (transfer full) (nullable): A copied #GstParseContext
*/
GstParseContext *
gst_parse_context_copy (const GstParseContext * context)
@@ -147,7 +147,7 @@
* or gst_parse_launchv_full(). Will only return results if an error code
* of %GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned.
*
- * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*): a
+ * Returns: (transfer full) (array zero-terminated=1) (element-type gchar*) (nullable): a
* %NULL-terminated array of element factory name strings of missing
* elements. Free with g_strfreev() when no longer needed.
*/
@@ -216,7 +216,8 @@
* @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: (transfer floating): a new element on success and %NULL on failure.
+ * Returns: (transfer floating) (nullable): a new element on success and %NULL
+ * on failure.
*/
GstElement *
gst_parse_launchv (const gchar ** argv, GError ** error)
@@ -236,10 +237,11 @@
* @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: (transfer floating): 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 floating) (nullable): 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)
*/
GstElement *
gst_parse_launchv_full (const gchar ** argv, GstParseContext * context,
@@ -289,9 +291,10 @@
* the @error is set. In this case there was a recoverable parsing error and you
* can try to play the pipeline.
*
- * Returns: (transfer floating): 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 floating) (nullable): 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)
@@ -313,11 +316,11 @@
* the @error is set. In this case there was a recoverable parsing error and you
* can try to play the pipeline.
*
- * Returns: (transfer floating): 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 (unless
- * the GST_PARSE_FLAG_PLACE_IN_BIN flag is set, in which case they are put
- * in a #GstBin instead).
+ * Returns: (transfer floating) (nullable): 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 (unless the GST_PARSE_FLAG_PLACE_IN_BIN flag is set, in
+ * which case they are put in a #GstBin instead).
*/
GstElement *
gst_parse_launch_full (const gchar * pipeline_description,
diff --git a/gst/gstplugin.c b/gst/gstplugin.c
index 86d8abc..6838afd 100644
--- a/gst/gstplugin.c
+++ b/gst/gstplugin.c
@@ -1309,7 +1309,8 @@
*
* Load the named plugin. Refs the plugin.
*
- * Returns: (transfer full): a reference to a loaded plugin, or %NULL on error.
+ * Returns: (transfer full) (nullable): a reference to a loaded plugin, or
+ * %NULL on error.
*/
GstPlugin *
gst_plugin_load_by_name (const gchar * name)
@@ -1352,7 +1353,8 @@
* plugin = loaded_plugin;
* ]|
*
- * Returns: (transfer full): a reference to a loaded plugin, or %NULL on error.
+ * Returns: (transfer full) (nullable): a reference to a loaded plugin, or
+ * %NULL on error.
*/
GstPlugin *
gst_plugin_load (GstPlugin * plugin)
diff --git a/gst/gstprotection.c b/gst/gstprotection.c
index 436cce7..e6aed07 100644
--- a/gst/gstprotection.c
+++ b/gst/gstprotection.c
@@ -166,9 +166,10 @@
* an element that supports one of the supplied UUIDs. If more than one
* element matches, the system ID of the highest ranked element is selected.
*
- * Returns: (transfer none): One of the strings from @system_identifiers that
- * indicates the highest ranked element that implements the protection system
- * indicated by that system ID, or %NULL if no element has been found.
+ * Returns: (transfer none) (nullable): One of the strings from
+ * @system_identifiers that indicates the highest ranked element that
+ * implements the protection system indicated by that system ID, or %NULL if no
+ * element has been found.
*
* Since: 1.6
*/
@@ -202,9 +203,9 @@
* Iterates the supplied list of UUIDs and checks the GstRegistry for
* all the decryptors supporting one of the supplied UUIDs.
*
- * Returns: (transfer full): A null terminated array containing all the
- * @system_identifiers supported by the set of available decryptors, or %NULL
- * if no matches were found.
+ * Returns: (transfer full) (nullable): A null terminated array containing all
+ * the @system_identifiers supported by the set of available decryptors, or
+ * %NULL if no matches were found.
*
* Since: 1.14
*/
diff --git a/gst/gstquery.c b/gst/gstquery.c
index 30180cf..87e565b 100644
--- a/gst/gstquery.c
+++ b/gst/gstquery.c
@@ -663,7 +663,7 @@
*
* Free-function: gst_query_unref()
*
- * Returns: (transfer full): a new #GstQuery
+ * Returns: (transfer full) (nullable): a new #GstQuery
*/
GstQuery *
gst_query_new_custom (GstQueryType type, GstStructure * structure)
diff --git a/gst/gstsample.c b/gst/gstsample.c
index 219db6b..6479048 100644
--- a/gst/gstsample.c
+++ b/gst/gstsample.c
@@ -207,7 +207,7 @@
*
* Get extra information associated with @sample.
*
- * Returns: (transfer none): the extra info of @sample.
+ * Returns: (transfer none) (nullable): the extra info of @sample.
* The info remains valid as long as @sample is valid.
*/
const GstStructure *
diff --git a/gst/gststreamcollection.c b/gst/gststreamcollection.c
index ef134b9..f1fa1a4 100644
--- a/gst/gststreamcollection.c
+++ b/gst/gststreamcollection.c
@@ -342,7 +342,7 @@
*
* The caller should not modify the returned #GstStream
*
- * Returns: (transfer none): A #GstStream
+ * Returns: (transfer none) (nullable): A #GstStream
*
* Since: 1.10
*/
diff --git a/gst/gststreams.c b/gst/gststreams.c
index f90d771..9c3272d 100644
--- a/gst/gststreams.c
+++ b/gst/gststreams.c
@@ -525,7 +525,7 @@
*
* Get a descriptive string for a given #GstStreamType
*
- * Returns: A string describing the stream type
+ * Returns: (nullable): A string describing the stream type
*
* Since: 1.10
*/
diff --git a/gst/gststructure.c b/gst/gststructure.c
index 068b4fa..3b4d5b8 100644
--- a/gst/gststructure.c
+++ b/gst/gststructure.c
@@ -879,7 +879,8 @@
*
* Get the value of the field with name @fieldname.
*
- * Returns: the #GValue corresponding to the field with the given name.
+ * Returns: (nullable): the #GValue corresponding to the field with the given
+ * name.
*/
const GValue *
gst_structure_get_value (const GstStructure * structure,
@@ -904,8 +905,8 @@
*
* Get the value of the field with GQuark @field.
*
- * Returns: the #GValue corresponding to the field with the given name
- * identifier.
+ * Returns: (nullable): the #GValue corresponding to the field with the given
+ * name identifier.
*/
const GValue *
gst_structure_id_get_value (const GstStructure * structure, GQuark field)
@@ -2848,7 +2849,7 @@
*
* Intersects @struct1 and @struct2 and returns the intersection.
*
- * Returns: Intersection of @struct1 and @struct2
+ * Returns: (nullable): Intersection of @struct1 and @struct2
*/
GstStructure *
gst_structure_intersect (const GstStructure * struct1,
diff --git a/gst/gsttaglist.c b/gst/gsttaglist.c
index f1940d9..3713b2c 100644
--- a/gst/gsttaglist.c
+++ b/gst/gsttaglist.c
@@ -604,7 +604,7 @@
* Returns the human-readable name of this tag, You must not change or free
* this string.
*
- * Returns: the human-readable name of this tag
+ * Returns: (nullable): the human-readable name of this tag
*/
const gchar *
gst_tag_get_nick (const gchar * tag)
@@ -629,7 +629,7 @@
* Returns the human-readable description of this tag, You must not change or
* free this string.
*
- * Returns: the human-readable description of this tag
+ * Returns: (nullable): the human-readable description of this tag
*/
const gchar *
gst_tag_get_description (const gchar * tag)
diff --git a/gst/gsttoc.c b/gst/gsttoc.c
index f501348..7e62d5f 100644
--- a/gst/gsttoc.c
+++ b/gst/gsttoc.c
@@ -777,7 +777,7 @@
*
* Gets the parent #GstTocEntry of @entry.
*
- * Returns: (transfer none): The parent #GstTocEntry of @entry
+ * Returns: (transfer none) (nullable): The parent #GstTocEntry of @entry
*/
GstTocEntry *
gst_toc_entry_get_parent (GstTocEntry * entry)
diff --git a/gst/gsturi.c b/gst/gsturi.c
index 52aa678..35fa503 100644
--- a/gst/gsturi.c
+++ b/gst/gsturi.c
@@ -397,7 +397,7 @@
* Extracts the protocol out of a given valid URI. The returned string must be
* freed using g_free().
*
- * Returns: The protocol for this URI.
+ * Returns: (nullable): The protocol for this URI.
*/
gchar *
gst_uri_get_protocol (const gchar * uri)
@@ -449,9 +449,9 @@
*
* Free-function: g_free
*
- * Returns: (transfer full): 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.
+ * Returns: (transfer full) (nullable): 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)
@@ -616,7 +616,8 @@
*
* Creates an element for handling the given URI.
*
- * Returns: (transfer floating): a new element or %NULL if none could be created
+ * Returns: (transfer floating) (nullable): a new element or %NULL if none
+ * could be created
*/
GstElement *
gst_element_make_from_uri (const GstURIType type, const gchar * uri,
@@ -1497,7 +1498,7 @@
* Parses a URI string into a new #GstUri object. Will return NULL if the URI
* cannot be parsed.
*
- * Returns: (transfer full)(nullable): A new #GstUri object, or NULL.
+ * Returns: (transfer full) (nullable): A new #GstUri object, or NULL.
*
* Since: 1.6
*/
@@ -1759,16 +1760,16 @@
/**
* gst_uri_join:
- * @base_uri: (transfer none)(nullable): The base URI to join another to.
- * @ref_uri: (transfer none)(nullable): The reference URI to join onto the
- * base URI.
+ * @base_uri: (transfer none) (nullable): The base URI to join another to.
+ * @ref_uri: (transfer none) (nullable): The reference URI to join onto the
+ * base URI.
*
* Join a reference URI onto a base URI using the method from RFC 3986.
* If either URI is %NULL then the other URI will be returned with the ref count
* increased.
*
- * Returns: (transfer full): A #GstUri which represents the base with the
- * reference URI joined on.
+ * Returns: (transfer full) (nullable): A #GstUri which represents the base
+ * with the reference URI joined on.
*
* Since: 1.6
*/
@@ -2076,7 +2077,7 @@
* Get the scheme name from the URI or %NULL if it doesn't exist.
* If @uri is %NULL then returns %NULL.
*
- * Returns: The scheme from the #GstUri object or %NULL.
+ * Returns: (nullable): The scheme from the #GstUri object or %NULL.
*/
const gchar *
gst_uri_get_scheme (const GstUri * uri)
@@ -2116,7 +2117,7 @@
* Get the userinfo (usually in the form "username:password") from the URI
* or %NULL if it doesn't exist. If @uri is %NULL then returns %NULL.
*
- * Returns: The userinfo from the #GstUri object or %NULL.
+ * Returns: (nullable): The userinfo from the #GstUri object or %NULL.
*
* Since: 1.6
*/
@@ -2158,7 +2159,7 @@
* Get the host name from the URI or %NULL if it doesn't exist.
* If @uri is %NULL then returns %NULL.
*
- * Returns: The host name from the #GstUri object or %NULL.
+ * Returns: (nullable): The host name from the #GstUri object or %NULL.
*
* Since: 1.6
*/
@@ -2240,8 +2241,8 @@
*
* Extract the path string from the URI object.
*
- * Returns: (transfer full): The path from the URI. Once finished with the
- * string should be g_free()'d.
+ * Returns: (transfer full): (nullable): The path from the URI. Once finished
+ * with the string should be g_free()'d.
*
* Since: 1.6
*/
@@ -2274,7 +2275,7 @@
/**
* gst_uri_set_path:
- * @uri: (transfer none)(nullable): The #GstUri to modify.
+ * @uri: (transfer none) (nullable): The #GstUri to modify.
* @path: The new path to set with path segments separated by '/', or use %NULL
* to unset the path.
*
@@ -2303,8 +2304,8 @@
*
* Extract the path string from the URI object as a percent encoded URI path.
*
- * Returns: (transfer full): The path from the URI. Once finished with the
- * string should be g_free()'d.
+ * Returns: (transfer full) (nullable): The path from the URI. Once finished
+ * with the string should be g_free()'d.
*
* Since: 1.6
*/
@@ -2368,7 +2369,7 @@
*
* Get a list of path segments from the URI.
*
- * Returns: (transfer full)(element-type gchar*): A #GList of path segment
+ * Returns: (transfer full) (element-type gchar*): A #GList of path segment
* strings or %NULL if no path segments are available. Free the list
* when no longer needed with g_list_free_full(list, g_free).
*
@@ -2490,8 +2491,8 @@
*
* Get a percent encoded URI query string from the @uri.
*
- * Returns: (transfer full): A percent encoded query string. Use g_free() when
- * no longer needed.
+ * Returns: (transfer full) (nullable): A percent encoded query string. Use
+ * g_free() when no longer needed.
*
* Since: 1.6
*/
@@ -2566,8 +2567,8 @@
* no longer required. Modifying this hash table will modify the query in the
* URI.
*
- * Returns: (transfer full)(element-type gchar* gchar*): The query hash table
- * from the URI.
+ * Returns: (transfer full) (element-type gchar* gchar*) (nullable): The query
+ * hash table from the URI.
*
* Since: 1.6
*/
@@ -2714,7 +2715,7 @@
* use gst_uri_query_has_key() to determine if a key is present in the URI
* query.
*
- * Returns: The value for the given key, or %NULL if not found.
+ * Returns: (nullable): The value for the given key, or %NULL if not found.
*
* Since: 1.6
*/
@@ -2736,7 +2737,7 @@
*
* Get a list of the query keys from the URI.
*
- * Returns: (transfer container)(element-type gchar*): A list of keys from
+ * Returns: (transfer container) (element-type gchar*): A list of keys from
* the URI query. Free the list with g_list_free().
*
* Since: 1.6
@@ -2760,7 +2761,7 @@
* Get the fragment name from the URI or %NULL if it doesn't exist.
* If @uri is %NULL then returns %NULL.
*
- * Returns: The host name from the #GstUri object or %NULL.
+ * Returns: (nullable): The host name from the #GstUri object or %NULL.
*
* Since: 1.6
*/
@@ -2811,8 +2812,8 @@
*
* See more about Media Fragments URI 1.0 (W3C) at https://www.w3.org/TR/media-frags/
*
- * Returns: (transfer full)(element-type gchar* gchar*): The fragment hash table
- * from the URI.
+ * Returns: (transfer full) (element-type gchar* gchar*) (nullable): The
+ * fragment hash table from the URI.
*
* Since: 1.12
*/
diff --git a/gst/gstutils.c b/gst/gstutils.c
index 7c1618a..e8749cb 100644
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -3375,7 +3375,7 @@
* and want them all ghosted, you will have to create the ghost pads
* yourself).
*
- * Returns: (transfer floating) (type Gst.Element): a newly-created
+ * Returns: (transfer floating) (type Gst.Element) (nullable): a newly-created
* element, which is guaranteed to be a bin unless
* GST_FLAG_NO_SINGLE_ELEMENT_BINS was passed, or %NULL if an error
* occurred.
diff --git a/gst/gstvalue.c b/gst/gstvalue.c
index 51e5c13..2f16ebc 100644
--- a/gst/gstvalue.c
+++ b/gst/gstvalue.c
@@ -1939,7 +1939,7 @@
*
* Gets the minimum of the range specified by @value.
*
- * Returns: the minimum of the range
+ * Returns: (nullable): the minimum of the range
*/
const GValue *
gst_value_get_fraction_range_min (const GValue * value)
@@ -1962,7 +1962,7 @@
*
* Gets the maximum of the range specified by @value.
*
- * Returns: the maximum of the range
+ * Returns: (nullable): the maximum of the range
*/
const GValue *
gst_value_get_fraction_range_max (const GValue * value)
