introspection: add missing (nullable) annotations to return values

Support for (nullable) was added to G-I at the same time as nullable
return values.  Previous versions of G-I will not mark return values as
nullable, even when an (allow-none) annotation is present, so it is
not necessary to add (allow-none) annotations for compatibility with
older versions of G-I.

https://bugzilla.gnome.org/show_bug.cgi?id=730957

gst/gstallocator.c

@@ -221,8 +221,9 @@ gst_allocator_register (const gchar * name, GstAllocator * allocator)
  * Find a previously registered allocator with @name. When @name is %NULL, the
  * default allocator will be returned.
  *
- * Returns: (transfer full): a #GstAllocator or %NULL when the allocator with @name was not
+ * Returns: (transfer full) (nullable): a #GstAllocator or %NULL when
- * registered. Use gst_object_unref() to release the allocator after usage.
+ * the allocator with @name was not registered. Use gst_object_unref()
+ * to release the allocator after usage.
  */
 GstAllocator *
 gst_allocator_find (const gchar * name)

gst/gstatomicqueue.c

@@ -214,8 +214,8 @@ gst_atomic_queue_unref (GstAtomicQueue * queue)
  *
  * Peek the head element of the queue without removing it from the queue.
  *
- * Returns: (transfer none): the head element of @queue or %NULL when
+ * Returns: (transfer none) (nullable): the head element of @queue or
- * the queue is empty.
+ * %NULL when the queue is empty.
  */
 gpointer
 gst_atomic_queue_peek (GstAtomicQueue * queue)

gst/gstbin.c

@@ -1633,7 +1633,8 @@ no_function:
  *
  * MT safe.  Caller owns returned value.
  *
- * Returns: (transfer full): a #GstIterator of #GstElement, or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
+ * or %NULL
  */
 GstIterator *
 gst_bin_iterate_elements (GstBin * bin)
@@ -1673,7 +1674,8 @@ iterate_child_recurse (GstIterator * it, const GValue * item)
  *
  * MT safe.  Caller owns returned value.
  *
- * Returns: (transfer full): a #GstIterator of #GstElement, or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
+ * or %NULL
  */
 GstIterator *
 gst_bin_iterate_recurse (GstBin * bin)
@@ -1730,7 +1732,8 @@ sink_iterator_filter (const GValue * vchild, GValue * vbin)
  *
  * MT safe.  Caller owns returned value.
  *
- * Returns: (transfer full): a #GstIterator of #GstElement, or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
+ * or %NULL
  */
 GstIterator *
 gst_bin_iterate_sinks (GstBin * bin)
@@ -1790,7 +1793,8 @@ src_iterator_filter (const GValue * vchild, GValue * vbin)
  *
  * MT safe.  Caller owns returned value.
  *
- * Returns: (transfer full): a #GstIterator of #GstElement, or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
+ * or %NULL
  */
 GstIterator *
 gst_bin_iterate_sources (GstBin * bin)
@@ -2166,7 +2170,8 @@ gst_bin_sort_iterator_new (GstBin * bin)
  *
  * MT safe.  Caller owns returned value.
  *
- * Returns: (transfer full): a #GstIterator of #GstElement, or %NULL
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement,
+ * or %NULL
  */
 GstIterator *
 gst_bin_iterate_sorted (GstBin * bin)
@@ -4126,7 +4131,8 @@ compare_name (const GValue * velement, const gchar * name)
  *
  * MT safe.  Caller owns returned reference.
  *
- * Returns: (transfer full): the #GstElement with the given name, or %NULL
+ * Returns: (transfer full) (nullable): the #GstElement with the given
+ * name, or %NULL
  */
 GstElement *
 gst_bin_get_by_name (GstBin * bin, const gchar * name)
@@ -4169,7 +4175,8 @@ gst_bin_get_by_name (GstBin * bin, const gchar * name)
  *
  * MT safe.  Caller owns returned reference.
  *
- * Returns: (transfer full): the #GstElement with the given name, or %NULL
+ * Returns: (transfer full) (nullable): the #GstElement with the given
+ * name, or %NULL
  */
 GstElement *
 gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name)
@@ -4269,8 +4276,9 @@ gst_bin_get_by_interface (GstBin * bin, GType iface)
  *
  * MT safe.  Caller owns returned value.
  *
- * Returns: (transfer full): a #GstIterator of #GstElement for all elements
+ * Returns: (transfer full) (nullable): a #GstIterator of #GstElement
- *          in the bin implementing the given interface, or %NULL
+ *     for all elements in the bin implementing the given interface,
+ *     or %NULL
  */
 GstIterator *
 gst_bin_iterate_all_by_interface (GstBin * bin, GType iface)

gst/gstbuffer.c

@@ -650,8 +650,8 @@ gst_buffer_new (void)
  *
  * MT safe.
  *
- * Returns: (transfer full): a new #GstBuffer, or %NULL if the memory couldn't
+ * Returns: (transfer full) (nullable): a new #GstBuffer, or %NULL if
- *     be allocated.
+ *     the memory couldn't be allocated.
  */
 GstBuffer *
 gst_buffer_new_allocate (GstAllocator * allocator, gsize size,
@@ -1934,7 +1934,8 @@ gst_buffer_append_region (GstBuffer * buf1, GstBuffer * buf2, gssize offset,
  * Get the metadata for @api on buffer. When there is no such
  * metadata, %NULL is returned.
  *
- * Returns: (transfer none): the metadata for @api on @buffer.
+ * Returns: (transfer none) (nullable): the metadata for @api on
+ * @buffer.
  */
 GstMeta *
 gst_buffer_get_meta (GstBuffer * buffer, GType api)
@@ -2063,8 +2064,8 @@ gst_buffer_remove_meta (GstBuffer * buffer, GstMeta * meta)
  *
  * @state will be updated with an opaque state pointer
  *
- * Returns: (transfer none): The next #GstMeta or %NULL when there are
+ * Returns: (transfer none) (nullable): The next #GstMeta or %NULL
- * no more items.
+ * when there are no more items.
  */
 GstMeta *
 gst_buffer_iterate_meta (GstBuffer * buffer, gpointer * state)

gst/gstbufferlist.c

@@ -227,8 +227,9 @@ gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
  *
  * Get the buffer at @idx.
  *
- * Returns: (transfer none): the buffer at @idx in @group or %NULL when there
+ * Returns: (transfer none) (nullable): the buffer at @idx in @group
- *     is no buffer. The buffer remains valid as long as @list is valid.
+ *     or %NULL when there is no buffer. The buffer remains valid as
+ *     long as @list is valid.
  */
 GstBuffer *
 gst_buffer_list_get (GstBufferList * list, guint idx)

gst/gstbus.c

@@ -467,10 +467,11 @@ 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: (transfer full): a #GstMessage matching the filter in @types,
+ * Returns: (transfer full) (nullable): a #GstMessage matching the
- *     or %NULL if no matching message was found on the bus until the timeout
+ *     filter in @types, or %NULL if no matching message was found on
- *     expired. The message is taken from the bus and needs to be unreffed
+ *     the bus until the timeout expired. The message is taken from
- *     with gst_message_unref() after usage.
+ *     the bus and needs to be unreffed with gst_message_unref() after
+ *     usage.
  *
  * MT safe.
  */
@@ -568,10 +569,10 @@ beach:
  * #GST_CLOCK_TIME_NONE, this function will block forever until a message was
  * posted on the bus.
  *
- * Returns: (transfer full): the #GstMessage that is on the bus after the
+ * Returns: (transfer full) (nullable): the #GstMessage that is on the
- *     specified timeout or %NULL if the bus is empty after the timeout expired.
+ *     bus after the specified timeout or %NULL if the bus is empty
- * The message is taken from the bus and needs to be unreffed with
+ *     after the timeout expired.  The message is taken from the bus
- * gst_message_unref() after usage.
+ *     and needs to be unreffed with gst_message_unref() after usage.
  *
  * MT safe.
  */
@@ -594,10 +595,10 @@ gst_bus_timed_pop (GstBus * bus, GstClockTime timeout)
  * the bus, all messages will be discarded. It is not possible to use message
  * enums beyond #GST_MESSAGE_EXTENDED in the @events mask.
  *
- * Returns: (transfer full): the next #GstMessage matching @type that is on
+ * Returns: (transfer full) (nullable): the next #GstMessage matching
- *     the bus, or %NULL if the bus is empty or there is no message matching
+ *     @type that is on the bus, or %NULL if the bus is empty or there
- *     @type. The message is taken from the bus and needs to be unreffed with
+ *     is no message matching @type. The message is taken from the bus
- *     gst_message_unref() after usage.
+ *     and needs to be unreffed with gst_message_unref() after usage.
  *
  * MT safe.
  */
@@ -616,9 +617,10 @@ gst_bus_pop_filtered (GstBus * bus, GstMessageType types)
  *
  * Get a message from the bus.
  *
- * Returns: (transfer full): the #GstMessage that is on the bus, or %NULL if the
+ * Returns: (transfer full) (nullable): the #GstMessage that is on the
- *     bus is empty. The message is taken from the bus and needs to be unreffed
+ *     bus, or %NULL if the bus is empty. The message is taken from
- *     with gst_message_unref() after usage.
+ *     the bus and needs to be unreffed with gst_message_unref() after
+ *     usage.
  *
  * MT safe.
  */
@@ -638,8 +640,8 @@ gst_bus_pop (GstBus * bus)
  * on the bus' message queue. A reference is returned, and needs to be unreffed
  * by the caller.
  *
- * Returns: (transfer full): the #GstMessage that is on the bus, or %NULL if the
+ * Returns: (transfer full) (nullable): the #GstMessage that is on the
- *     bus is empty.
+ *     bus, or %NULL if the bus is empty.
  *
  * MT safe.
  */
@@ -1054,9 +1056,10 @@ poll_destroy_timeout (GstBusPollData * poll_data)
  * better handled by setting up an asynchronous bus watch and doing things
  * from there.
  *
- * Returns: (transfer full): the message that was received, or %NULL if the
+ * Returns: (transfer full) (nullable): the message that was received,
- *     poll timed out. The message is taken from the bus and needs to be
+ *     or %NULL if the poll timed out. The message is taken from the
- *     unreffed with gst_message_unref() after usage.
+ *     bus and needs to be unreffed with gst_message_unref() after
+ *     usage.
  */
 GstMessage *
 gst_bus_poll (GstBus * bus, GstMessageType events, GstClockTime timeout)

gst/gstcapsfeatures.c

@@ -471,8 +471,9 @@ priv_gst_caps_features_append_to_gstring (const GstCapsFeatures * features,
  *
  * Free-function: gst_caps_features_free
  *
- * Returns: (transfer full): a new #GstCapsFeatures or %NULL when the string could
+ * Returns: (transfer full) (nullable): a new #GstCapsFeatures or
- *     not be parsed. Free with gst_caps_features_free() after use.
+ *     %NULL when the string could not be parsed. Free with
+ *     gst_caps_features_free() after use.
  *
  * Since: 1.2
  */

gst/gstchildproxy.c

@@ -108,8 +108,8 @@ gst_child_proxy_default_get_child_by_name (GstChildProxy * parent,
  * together with gst_object_get_name(). If the interface is to be used with
  * #GObjects, this methods needs to be overridden.
  *
- * Returns: (transfer full): the child object or %NULL if not found. Unref
+ * Returns: (transfer full) (nullable): the child object or %NULL if
- *     after usage.
+ *     not found. Unref after usage.
  *
  * MT safe.
  */
@@ -129,8 +129,8 @@ gst_child_proxy_get_child_by_name (GstChildProxy * parent, const gchar * name)
  *
  * Fetches a child by its number.
  *
- * Returns: (transfer full): the child object or %NULL if not found (index
+ * Returns: (transfer full) (nullable): the child object or %NULL if
- *     too high). Unref after usage.
+ *     not found (index too high). Unref after usage.
  *
  * MT safe.
  */

gst/gstclock.c

@@ -1204,8 +1204,9 @@ not_supported:
  * Get the master clock that @clock is slaved to or %NULL when the clock is
  * not slaved to any master clock.
  *
- * Returns: (transfer full): a master #GstClock or %NULL when this clock is
+ * Returns: (transfer full) (nullable): a master #GstClock or %NULL
- *     not slaved to a master clock. Unref after usage.
+ *     when this clock is not slaved to a master clock. Unref after
+ *     usage.
  *
  * MT safe.
  */

gst/gstcontrolbinding.c

@@ -259,8 +259,8 @@ gst_control_binding_sync_values (GstControlBinding * binding,
  *
  * Gets the value for the given controlled property at the requested time.
  *
- * Returns: the GValue of the property at the given time, or %NULL if the
+ * Returns: (nullable): the GValue of the property at the given time,
- * property isn't controlled.
+ * or %NULL if the property isn't controlled.
  */
 GValue *
 gst_control_binding_get_value (GstControlBinding * binding,

gst/gstdatetime.c

@@ -76,7 +76,8 @@ static void gst_date_time_free (GstDateTime * datetime);
  *
  * Free-function: gst_date_time_unref
  *
- * Returns: (transfer full): a newly created #GstDateTime, or %NULL on error
+ * Returns: (transfer full) (nullable): a newly created #GstDateTime,
+ * or %NULL on error
  */
 GstDateTime *
 gst_date_time_new_from_g_date_time (GDateTime * dt)
@@ -104,7 +105,8 @@ gst_date_time_new_from_g_date_time (GDateTime * dt)
  *
  * Free-function: g_date_time_unref
  *
- * Returns: (transfer full): a newly created #GDateTime, or %NULL on error
+ * Returns: (transfer full) (nullable): a newly created #GDateTime, or
+ * %NULL on error
  */
 GDateTime *
 gst_date_time_to_g_date_time (GstDateTime * datetime)
@@ -725,9 +727,10 @@ done:
  * are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z,
  * 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100
  *
- * Returns: a newly allocated string formatted according to ISO 8601 and
+ * Returns: (nullable): a newly allocated string formatted according
- *     only including the datetime fields that are valid, or %NULL in case
+ *     to ISO 8601 and only including the datetime fields that are
- *     there was an error. The string should be freed with g_free().
+ *     valid, or %NULL in case there was an error. The string should
+ *     be freed with g_free().
  */
 gchar *
 gst_date_time_to_iso8601_string (GstDateTime * datetime)
@@ -749,7 +752,8 @@ gst_date_time_to_iso8601_string (GstDateTime * datetime)
  *
  * Free-function: gst_date_time_unref
  *
- * Returns: (transfer full): a newly created #GstDateTime, or %NULL on error
+ * Returns: (transfer full) (nullable): a newly created #GstDateTime,
+ * or %NULL on error
  */
 GstDateTime *
 gst_date_time_new_from_iso8601_string (const gchar * string)

gst/gstdevicemonitorfactory.c

@@ -105,7 +105,8 @@ gst_device_monitor_factory_finalize (GObject * object)
  * Search for an device monitor factory of the given name. Refs the returned
  * device monitor factory; caller is responsible for unreffing.
  *
- * Returns: (transfer full): #GstDeviceMonitorFactory if found, %NULL otherwise
+ * Returns: (transfer full) (nullable): #GstDeviceMonitorFactory if
+ * found, %NULL otherwise
  *
  * Since: 1.4
  */
@@ -244,8 +245,8 @@ detailserror:
  * Returns the device monitor of the type defined by the given device
  * monitorfactory.
  *
- * Returns: (transfer full): the #GstDeviceMonitor or %NULL if the
+ * Returns: (transfer full) (nullable): the #GstDeviceMonitor or %NULL
- *     device monitor couldn't be created
+ * if the device monitor couldn't be created
  *
  * Since: 1.4
  */
@@ -336,8 +337,8 @@ no_device_monitor:
  * Returns the device monitor of the type defined by the given device
  * monitor factory.
  *
- * Returns: (transfer full): a #GstDeviceMonitor or %NULL if unable to
+ * Returns: (transfer full) (nullable): a #GstDeviceMonitor or %NULL
- * create device monitor
+ * if unable to create device monitor
  *
  * Since: 1.4
  */
@@ -407,8 +408,8 @@ gst_device_monitor_factory_get_device_monitor_type (GstDeviceMonitorFactory *
  *
  * Get the metadata on @factory with @key.
  *
- * Returns: the metadata with @key on @factory or %NULL when there was no
+ * Returns: (nullable): the metadata with @key on @factory or %NULL
- * metadata with the given @key.
+ * when there was no metadata with the given @key.
  *
  * Since: 1.4
  */
@@ -425,7 +426,7 @@ gst_device_monitor_factory_get_metadata (GstDeviceMonitorFactory * factory,
  *
  * Get the available keys for the metadata on @factory.
  *
- * Returns: (transfer full) (element-type utf8) (array zero-terminated=1):
+ * Returns: (transfer full) (element-type utf8) (array zero-terminated=1) (nullable):
  * a %NULL-terminated array of key strings, or %NULL when there is no
  * metadata. Free with g_strfreev() when no longer needed.
  *

gst/gstelement.c

@@ -342,8 +342,8 @@ gst_element_release_request_pad (GstElement * element, GstPad * pad)
  * <note>An element is only required to provide a clock in the PAUSED
  * state. Some elements can provide a clock in other states.</note>
  *
- * Returns: (transfer full): the GstClock provided by the element or %NULL
+ * Returns: (transfer full) (nullable): the GstClock provided by the
- * if no clock could be provided.  Unref after usage.
+ * element or %NULL if no clock could be provided.  Unref after usage.
  *
  * MT safe.
  */
@@ -583,8 +583,8 @@ gst_element_set_index (GstElement * element, GstIndex * index)
  *
  * Gets the index from the element.
  *
- * Returns: (transfer full): a #GstIndex or %NULL when no index was set on the
+ * Returns: (transfer full) (nullable): a #GstIndex or %NULL when no
- * element. unref after usage.
+ * index was set on the element. unref after usage.
  *
  * MT safe.
  */
@@ -865,8 +865,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: (transfer full): the requested #GstPad if found, otherwise %NULL.
+ * Returns: (transfer full) (nullable): the requested #GstPad if
- *     unref after usage.
+ *     found, otherwise %NULL.  unref after usage.
  *
  * MT safe.
  */
@@ -978,8 +978,8 @@ _gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
  * This method is slow and will be deprecated in the future. New code should
  * use gst_element_request_pad() with the requested template.
  *
- * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
+ * Returns: (transfer full) (nullable): requested #GstPad if found,
- *     Release after usage.
+ *     otherwise %NULL.  Release after usage.
  */
 GstPad *
 gst_element_get_request_pad (GstElement * element, const gchar * name)
@@ -1083,8 +1083,8 @@ gst_element_get_request_pad (GstElement * element, const gchar * name)
  *
  * The pad should be released with gst_element_release_request_pad().
  *
- * Returns: (transfer full): requested #GstPad if found, otherwise %NULL.
+ * Returns: (transfer full) (nullable): requested #GstPad if found,
- *     Release after usage.
+ *     otherwise %NULL.  Release after usage.
  */
 GstPad *
 gst_element_request_pad (GstElement * element,
@@ -1396,8 +1396,9 @@ 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: (transfer none): the #GstPadTemplate with the given name, or %NULL
+ * Returns: (transfer none) (nullable): the #GstPadTemplate with the
- *     if none was found. No unreferencing is necessary.
+ *     given name, or %NULL if none was found. No unreferencing is
+ *     necessary.
  */
 GstPadTemplate *
 gst_element_class_get_pad_template (GstElementClass *
@@ -1734,8 +1735,8 @@ gst_element_post_message (GstElement * element, GstMessage * message)
  *
  * This function is only used internally by the gst_element_error() macro.
  *
- * Returns: (transfer full): a newly allocated string, or %NULL if the format
+ * Returns: (transfer full) (nullable): a newly allocated string, or
- *     was %NULL or ""
+ *     %NULL if the format was %NULL or ""
  *
  * MT safe.
  */

gst/gstelement.h

@@ -694,7 +694,8 @@ GType                   gst_element_get_type            (void);
  * For a nameless element, this returns %NULL, which you can safely g_free()
  * as well.
  *
- * Returns: (transfer full): the name of @elem. g_free() after usage. MT safe.
+ * Returns: (transfer full) (nullable): the name of @elem. g_free()
+ * after usage. MT safe.
  *
  */
 #define                 gst_element_get_name(elem)      gst_object_get_name(GST_OBJECT_CAST(elem))

gst/gstelementfactory.c

@@ -123,7 +123,8 @@ 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: (transfer full): #GstElementFactory if found, %NULL otherwise
+ * Returns: (transfer full) (nullable): #GstElementFactory if found,
+ * %NULL otherwise
  */
 GstElementFactory *
 gst_element_factory_find (const gchar * name)
@@ -335,8 +336,8 @@ detailserror:
  * It will be given the name supplied, since all elements require a name as
  * their first argument.
  *
- * Returns: (transfer floating): new #GstElement or %NULL if the element couldn't
+ * Returns: (transfer floating) (nullable): new #GstElement or %NULL
- *     be created
+ *     if the element couldn't be created
  */
 GstElement *
 gst_element_factory_create (GstElementFactory * factory, const gchar * name)
@@ -422,7 +423,8 @@ no_element:
  * consisting of the element factory name and a number.
  * If name is given, it will be given the name supplied.
  *
- * Returns: (transfer floating): new #GstElement or %NULL if unable to create element
+ * Returns: (transfer floating) (nullable): new #GstElement or %NULL
+ * if unable to create element
  */
 GstElement *
 gst_element_factory_make (const gchar * factoryname, const gchar * name)
@@ -500,8 +502,8 @@ gst_element_factory_get_element_type (GstElementFactory * factory)
  *
  * Get the metadata on @factory with @key.
  *
- * Returns: the metadata with @key on @factory or %NULL when there was no
+ * Returns: (nullable): the metadata with @key on @factory or %NULL
- * metadata with the given @key.
+ * when there was no metadata with the given @key.
  */
 const gchar *
 gst_element_factory_get_metadata (GstElementFactory * factory,
@@ -516,7 +518,7 @@ gst_element_factory_get_metadata (GstElementFactory * factory,
  *
  * Get the available keys for the metadata on @factory.
  *
- * Returns: (transfer full) (element-type utf8) (array zero-terminated=1):
+ * Returns: (transfer full) (element-type utf8) (array zero-terminated=1) (nullable):
  * a %NULL-terminated array of key strings, or %NULL when there is no
  * metadata. Free with g_strfreev() when no longer needed.
  */

gst/gstformat.c

@@ -85,8 +85,8 @@ _priv_gst_format_initialize (void)
  *
  * Get a printable name for the given format. Do not modify or free.
  *
- * Returns: a reference to the static name of the format or %NULL if
+ * Returns: (nullable): a reference to the static name of the format
- * the format is unknown.
+ * or %NULL if the format is unknown.
  */
 const gchar *
 gst_format_get_name (GstFormat format)
@@ -225,7 +225,8 @@ gst_formats_contains (const GstFormat * formats, GstFormat format)
  *
  * Get details about the given format.
  *
- * Returns: The #GstFormatDefinition for @format or %NULL on failure.
+ * Returns: (nullable): The #GstFormatDefinition for @format or %NULL
+ * on failure.
  *
  * MT safe.
  */

gst/gstghostpad.c

@@ -79,8 +79,8 @@ static GstPad *gst_proxy_pad_get_target (GstPad * pad);
  *
  * Invoke the default iterate internal links function of the proxy pad.
  *
- * Returns: a #GstIterator of #GstPad, or %NULL if @pad has no parent. Unref each
+ * Returns: (nullable): a #GstIterator of #GstPad, or %NULL if @pad
- * returned pad with gst_object_unref().
+ * has no parent. Unref each returned pad with gst_object_unref().
  */
 GstIterator *
 gst_proxy_pad_iterate_internal_links_default (GstPad * pad, GstObject * parent)
@@ -208,8 +208,8 @@ gst_proxy_pad_get_target (GstPad * pad)
  * The internal pad of a #GstGhostPad is the internally used
  * pad of opposite direction, which is used to link to the target.
  *
- * Returns: (transfer full): the target #GstProxyPad, can be %NULL.
+ * Returns: (transfer full) (nullable): the target #GstProxyPad, can
- * Unref target pad after usage.
+ * be %NULL.  Unref target pad after usage.
  */
 GstProxyPad *
 gst_proxy_pad_get_internal (GstProxyPad * pad)
@@ -653,7 +653,8 @@ construct_failed:
  *
  * The created ghostpad will not have a padtemplate.
  *
- * Returns: (transfer full): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  */
 GstPad *
 gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir)
@@ -679,7 +680,8 @@ gst_ghost_pad_new_no_target (const gchar * name, GstPadDirection dir)
  *
  * Will ref the target.
  *
- * Returns: (transfer floating): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  */
 GstPad *
 gst_ghost_pad_new (const gchar * name, GstPad * target)
@@ -719,7 +721,8 @@ set_target_failed:
  *
  * Will ref the target.
  *
- * Returns: (transfer full): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  */
 
 GstPad *
@@ -761,7 +764,8 @@ set_target_failed:
  * Create a new ghostpad based on @templ, without setting a target. The
  * direction will be taken from the @templ.
  *
- * Returns: (transfer full): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  */
 GstPad *
 gst_ghost_pad_new_no_target_from_template (const gchar * name,
@@ -783,8 +787,9 @@ gst_ghost_pad_new_no_target_from_template (const gchar * name,
  *
  * Get the target pad of @gpad. Unref target pad after usage.
  *
- * Returns: (transfer full): the target #GstPad, can be %NULL if the ghostpad
+ * Returns: (transfer full) (nullable): the target #GstPad, can be
- * has no target set. Unref target pad after usage.
+ * %NULL if the ghostpad has no target set. Unref target pad after
+ * usage.
  */
 GstPad *
 gst_ghost_pad_get_target (GstGhostPad * gpad)

gst/gstmemory.c

@@ -225,8 +225,8 @@ gst_memory_resize (GstMemory * mem, gssize offset, gsize size)
  * This function takes ownership of old @mem and returns a reference to a new
  * #GstMemory.
  *
- * Returns: (transfer full): a #GstMemory object mapped with @flags or %NULL when
+ * Returns: (transfer full) (nullable): a #GstMemory object mapped
- * a mapping is not possible.
+ * with @flags or %NULL when a mapping is not possible.
  */
 GstMemory *
 gst_memory_make_mapped (GstMemory * mem, GstMapInfo * info, GstMapFlags flags)

gst/gstmeta.c

@@ -205,8 +205,8 @@ gst_meta_register (GType api, const gchar * impl, gsize size,
  * Lookup a previously registered meta info structure by its implementation name
  * @impl.
  *
- * Returns: (transfer none): a #GstMetaInfo with @impl, or %NULL when no such
+ * Returns: (transfer none) (nullable): a #GstMetaInfo with @impl, or
- * metainfo exists.
+ * %NULL when no such metainfo exists.
  */
 const GstMetaInfo *
 gst_meta_get_info (const gchar * impl)

gst/gstminiobject.c

@@ -691,7 +691,8 @@ gst_mini_object_set_qdata (GstMiniObject * object, GQuark quark,
  * This function gets back user data pointers stored via
  * gst_mini_object_set_qdata().
  *
- * Returns: (transfer none): The user data pointer set, or %NULL
+ * Returns: (transfer none) (nullable): The user data pointer set, or
+ * %NULL
  */
 gpointer
 gst_mini_object_get_qdata (GstMiniObject * object, GQuark quark)
@@ -721,7 +722,8 @@ gst_mini_object_get_qdata (GstMiniObject * object, GQuark quark)
  * and removes the data from @object without invoking its destroy() function (if
  * any was set).
  *
- * Returns: (transfer full): The user data pointer set, or %NULL
+ * Returns: (transfer full) (nullable): The user data pointer set, or
+ * %NULL
  */
 gpointer
 gst_mini_object_steal_qdata (GstMiniObject * object, GQuark quark)

gst/gstobject.c

@@ -649,7 +649,8 @@ had_parent:
  *
  * Free-function: g_free
  *
- * Returns: (transfer full): the name of @object. g_free() after usage.
+ * Returns: (transfer full) (nullable): the name of @object. g_free()
+ * after usage.
  *
  * MT safe. This function grabs and releases @object's LOCK.
  */
@@ -724,8 +725,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: (transfer full): parent of @object, this can be %NULL if @object
+ * Returns: (transfer full) (nullable): parent of @object, this can be
- *   has no parent. unref after usage.
+ *   %NULL if @object has no parent. unref after usage.
  *
  * MT safe. Grabs and releases @object's LOCK.
  */
@@ -992,8 +993,8 @@ gst_object_get_path_string (GstObject * object)
  *
  * Searches the list of properties under control.
  *
- * Returns: a #GstControlBinding or %NULL if the property is not being
+ * Returns: (nullable): a #GstControlBinding or %NULL if the property
- * controlled.
+ * is not being controlled.
  */
 static GstControlBinding *
 gst_object_find_control_binding (GstObject * self, const gchar * name)
@@ -1210,8 +1211,8 @@ gst_object_add_control_binding (GstObject * object, GstControlBinding * binding)
  * Gets the corresponding #GstControlBinding for the property. This should be
  * unreferenced again after use.
  *
- * Returns: (transfer full): the #GstControlBinding for @property_name or %NULL if
+ * Returns: (transfer full) (nullable): the #GstControlBinding for
- * the property is not controlled.
+ * @property_name or %NULL if the property is not controlled.
  */
 GstControlBinding *
 gst_object_get_control_binding (GstObject * object, const gchar * property_name)
@@ -1271,8 +1272,8 @@ gst_object_remove_control_binding (GstObject * object,
  *
  * Gets the value for the given controlled property at the requested time.
  *
- * Returns: the GValue of the property at the given time, or %NULL if the
+ * Returns: (nullable): the GValue of the property at the given time,
- * property isn't controlled.
+ * or %NULL if the property isn't controlled.
  */
 GValue *
 gst_object_get_value (GstObject * object, const gchar * property_name,

gst/gstpad.c

@@ -774,7 +774,8 @@ 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: (transfer floating): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  *
  * MT safe.
  */
@@ -795,7 +796,8 @@ 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: (transfer floating): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  */
 GstPad *
 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
@@ -816,7 +818,8 @@ 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: (transfer floating): a new #GstPad, or %NULL in case of an error.
+ * Returns: (transfer floating) (nullable): a new #GstPad, or %NULL in
+ * case of an error.
  */
 GstPad *
 gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
@@ -2458,9 +2461,9 @@ gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
  *
  * Gets the template for @pad.
  *
- * Returns: (transfer full): the #GstPadTemplate from which this pad was
+ * Returns: (transfer full) (nullable): the #GstPadTemplate from which
- *     instantiated, or %NULL if this pad has no template. Unref after
+ *     this pad was instantiated, or %NULL if this pad has no
- *     usage.
+ *     template. Unref after usage.
  */
 GstPadTemplate *
 gst_pad_get_pad_template (GstPad * pad)
@@ -2584,9 +2587,9 @@ gst_pad_get_peer (GstPad * pad)
  * calling gst_pad_query_caps() on @pad and its peer. The caller owns a reference
  * on the resulting caps.
  *
- * Returns: (transfer full): the allowed #GstCaps of the pad link. Unref the
+ * Returns: (transfer full) (nullable): the allowed #GstCaps of the
- *     caps when you no longer need it. This function returns %NULL when @pad
+ *     pad link. Unref the caps when you no longer need it. This
- *     has no peer.
+ *     function returns %NULL when @pad has no peer.
  *
  * MT safe.
  */
@@ -2641,8 +2644,8 @@ no_peer:
  *
  * The caller must free this iterator after use with gst_iterator_free().
  *
- * Returns: a #GstIterator of #GstPad, or %NULL if @pad has no parent. Unref each
+ * Returns: (nullable): a #GstIterator of #GstPad, or %NULL if @pad
- * returned pad with gst_object_unref().
+ * has no parent. Unref each returned pad with gst_object_unref().
  */
 GstIterator *
 gst_pad_iterate_internal_links_default (GstPad * pad, GstObject * parent)
@@ -2707,9 +2710,9 @@ no_parent:
  *
  * Free-function: gst_iterator_free
  *
- * Returns: (transfer full): a new #GstIterator of #GstPad or %NULL when the
+ * Returns: (transfer full) (nullable): a new #GstIterator of #GstPad
- *     pad does not have an iterator function configured. Use
+ *     or %NULL when the pad does not have an iterator function
- *     gst_iterator_free() after usage.
+ *     configured. Use gst_iterator_free() after usage.
  */
 GstIterator *
 gst_pad_iterate_internal_links (GstPad * pad)
@@ -5348,8 +5351,9 @@ gst_pad_get_element_private (GstPad * pad)
  * Returns a new reference of the sticky event of type @event_type
  * from the event.
  *
- * Returns: (transfer full): a #GstEvent of type @event_type or %NULL when no
+ * Returns: (transfer full) (nullable): a #GstEvent of type
- * event of @event_type was on @pad. Unref after usage.
+ * @event_type or %NULL when no event of @event_type was on
+ * @pad. Unref after usage.
  */
 GstEvent *
 gst_pad_get_sticky_event (GstPad * pad, GstEventType event_type, guint idx)

gst/gstpad.h

@@ -1186,6 +1186,8 @@ GstPad*			gst_pad_new_from_static_template	(GstStaticPadTemplate *templ, const g
  * Can return %NULL if the pad did not have a parent.
  *
  * MT safe.
+ *
+ * Returns: (nullable): the parent
  */
 #define gst_pad_get_parent(pad) gst_object_get_parent (GST_OBJECT_CAST (pad))
 

gst/gstplugin.c

@@ -1006,7 +1006,8 @@ gst_plugin_get_origin (GstPlugin * plugin)
  *
  * There may be plugins that do not have a valid release date set on them.
  *
- * Returns: the date string of the plugin, or %NULL if not available.
+ * Returns: (nullable): the date string of the plugin, or %NULL if not
+ * available.
  */
 const gchar *
 gst_plugin_get_release_date_string (GstPlugin * plugin)
@@ -1039,7 +1040,8 @@ 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: (transfer none): The cached data as a #GstStructure or %NULL.
+ * Returns: (transfer none) (nullable): The cached data as a
+ * #GstStructure or %NULL.
  */
 const GstStructure *
 gst_plugin_get_cache_data (GstPlugin * plugin)

gst/gstpluginfeature.c

@@ -90,7 +90,8 @@ gst_plugin_feature_finalize (GObject * object)
  * feature = loaded_feature;
  * ]|
  *
- * Returns: (transfer full): a reference to the loaded feature, or %NULL on error
+ * Returns: (transfer full) (nullable): a reference to the loaded
+ * feature, or %NULL on error
  */
 GstPluginFeature *
 gst_plugin_feature_load (GstPluginFeature * feature)
@@ -185,8 +186,9 @@ gst_plugin_feature_get_rank (GstPluginFeature * feature)
  *
  * Get the plugin that provides this feature.
  *
- * Returns: (transfer full): the plugin that provides this feature, or %NULL.
+ * Returns: (transfer full) (nullable): the plugin that provides this
- *     Unref with gst_object_unref() when no longer needed.
+ *     feature, or %NULL.  Unref with gst_object_unref() when no
+ *     longer needed.
  */
 GstPlugin *
 gst_plugin_feature_get_plugin (GstPluginFeature * feature)
@@ -205,8 +207,9 @@ gst_plugin_feature_get_plugin (GstPluginFeature * feature)
  *
  * Get the name of the plugin that provides this feature.
  *
- * Returns: the name of the plugin that provides this feature, or %NULL if
+ * Returns: (nullable): the name of the plugin that provides this
- *     the feature is not associated with a plugin.
+ *     feature, or %NULL if the feature is not associated with a
+ *     plugin.
  *
  * Since: 1.2
  */

gst/gstpluginfeature.h

@@ -75,7 +75,7 @@ typedef enum {
  * Returns the name of @feature.
  * For a nameless plugin feature, this returns %NULL.
  *
- * Returns: (transfer none): the name of @feature. MT safe.
+ * Returns: (transfer none) (nullable): the name of @feature. MT safe.
  *
  */
 #define                 gst_plugin_feature_get_name(feature)      GST_OBJECT_NAME(feature)

gst/gstpoll.c

@@ -545,8 +545,8 @@ gst_poll_collect_winsock_events (GstPoll * set)
  *
  * Free-function: gst_poll_free
  *
- * Returns: (transfer full): a new #GstPoll, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): a new #GstPoll, or %NULL in
- *     Free with gst_poll_free().
+ *     case of an error.  Free with gst_poll_free().
  */
 GstPoll *
 gst_poll_new (gboolean controllable)
@@ -617,8 +617,8 @@ no_socket_pair:
  *
  * Free-function: gst_poll_free
  *
- * Returns: (transfer full): a new #GstPoll, or %NULL in case of an error.
+ * Returns: (transfer full) (nullable): a new #GstPoll, or %NULL in
- *     Free with gst_poll_free().
+ *     case of an error.  Free with gst_poll_free().
  */
 GstPoll *
 gst_poll_new_timer (void)

gst/gstpreset.c

@@ -1141,7 +1141,8 @@ gst_preset_set_app_dir (const gchar * app_dir)
  * Gets the directory for application specific presets if set by the
  * application.
  *
- * Returns: the directory or %NULL, don't free or modify the string
+ * Returns: (nullable): the directory or %NULL, don't free or modify
+ * the string
  */
 const gchar *
 gst_preset_get_app_dir (void)

gst/gstregistry.c

@@ -868,8 +868,9 @@ gst_registry_plugin_name_filter (GstPlugin * plugin, const gchar * name)
  * Find the plugin with the given name in the registry.
  * The plugin will be reffed; caller is responsible for unreffing.
  *
- * Returns: (transfer full): the plugin with the given name or %NULL if the
+ * Returns: (transfer full) (nullable): the plugin with the given name
- *     plugin was not found. gst_object_unref() after usage.
+ *     or %NULL if the plugin was not found. gst_object_unref() after
+ *     usage.
  *
  * MT safe.
  */
@@ -902,8 +903,9 @@ gst_registry_find_plugin (GstRegistry * registry, const gchar * name)
  *
  * Find the pluginfeature with the given name and type in the registry.
  *
- * Returns: (transfer full): the pluginfeature with the given name and type
+ * Returns: (transfer full) (nullable): the pluginfeature with the
- *     or %NULL if the plugin was not found. gst_object_unref() after usage.
+ *     given name and type or %NULL if the plugin was not
+ *     found. gst_object_unref() after usage.
  *
  * MT safe.
  */
@@ -1055,8 +1057,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: (transfer full): the #GstPlugin if found, or %NULL if not.
+ * Returns: (transfer full) (nullable): the #GstPlugin if found, or
- *     gst_object_unref() after usage.
+ *     %NULL if not.  gst_object_unref() after usage.
  */
 GstPlugin *
 gst_registry_lookup (GstRegistry * registry, const char *filename)

gst/gstsample.c

@@ -143,10 +143,10 @@ had_parent:
  *
  * Get the buffer associated with @sample
  *
- * Returns: (transfer none): the buffer of @sample or %NULL when there
+ * Returns: (transfer none) (nullable): the buffer of @sample or %NULL
- *  is no buffer. The buffer remains valid as long as @sample is valid.
+ *  when there is no buffer. The buffer remains valid as long as
- *  If you need to hold on to it for longer than that, take a ref to
+ *  @sample is valid.  If you need to hold on to it for longer than
- *  the buffer with gst_buffer_ref().
+ *  that, take a ref to the buffer with gst_buffer_ref().
  */
 GstBuffer *
 gst_sample_get_buffer (GstSample * sample)
@@ -162,10 +162,10 @@ gst_sample_get_buffer (GstSample * sample)
  *
  * Get the caps associated with @sample
  *
- * Returns: (transfer none): the caps of @sample or %NULL when there
+ * Returns: (transfer none) (nullable): the caps of @sample or %NULL
- *  is no caps. The caps remain valid as long as @sample is valid.
+ *  when there is no caps. The caps remain valid as long as @sample is
- *  If you need to hold on to the caps for longer than that, take a ref to
+ *  valid.  If you need to hold on to the caps for longer than that,
- *  the caps with gst_caps_ref().
+ *  take a ref to the caps with gst_caps_ref().
  */
 GstCaps *
 gst_sample_get_caps (GstSample * sample)

gst/gststructure.c

@@ -1585,8 +1585,8 @@ gst_structure_get_double (const GstStructure * structure,
  * The string should not be modified, and remains valid until the next
  * call to a gst_structure_*() function with the given structure.
  *
- * Returns: a pointer to the string or %NULL when the field did not exist
+ * Returns: (nullable): a pointer to the string or %NULL when the
- * or did not contain a string.
+ * field did not exist or did not contain a string.
  */
 const gchar *
 gst_structure_get_string (const GstStructure * structure,
@@ -2374,8 +2374,9 @@ priv_gst_structure_parse_fields (gchar * str, gchar ** end,
  *
  * Free-function: gst_structure_free
  *
- * Returns: (transfer full): a new #GstStructure or %NULL when the string could
+ * Returns: (transfer full) (nullable): a new #GstStructure or %NULL
- *     not be parsed. Free with gst_structure_free() after use.
+ *     when the string could not be parsed. Free with
+ *     gst_structure_free() after use.
  *
  * Since: 1.2
  */
@@ -2396,8 +2397,9 @@ gst_structure_new_from_string (const gchar * string)
  *
  * Free-function: gst_structure_free
  *
- * Returns: (transfer full): a new #GstStructure or %NULL when the string could
+ * Returns: (transfer full) (nullable): a new #GstStructure or %NULL
- *     not be parsed. Free with gst_structure_free() after use.
+ *     when the string could not be parsed. Free with
+ *     gst_structure_free() after use.
  */
 GstStructure *
 gst_structure_from_string (const gchar * string, gchar ** end)

gst/gsttaglist.c

@@ -844,8 +844,9 @@ gst_tag_list_get_scope (const GstTagList * list)
  *
  * Serializes a tag list to a string.
  *
- * Returns: a newly-allocated string, or %NULL in case of an error. The
+ * Returns: (nullable): a newly-allocated string, or %NULL in case of
- *    string must be freed with g_free() when no longer needed.
+ *     an error. The string must be freed with g_free() when no longer
+ *     needed.
  */
 gchar *
 gst_tag_list_to_string (const GstTagList * list)
@@ -861,7 +862,8 @@ gst_tag_list_to_string (const GstTagList * list)
  *
  * Deserializes a tag list.
  *
- * Returns: a new #GstTagList, or %NULL in case of an error.
+ * Returns: (nullable): a new #GstTagList, or %NULL in case of an
+ * error.
  */
 GstTagList *
 gst_tag_list_new_from_string (const gchar * str)
@@ -1140,7 +1142,7 @@ gst_tag_list_insert (GstTagList * into, const GstTagList * from,
  *
  * Free-function: gst_tag_list_unref
  *
- * Returns: (transfer full): the new list
+ * Returns: (transfer full) (nullable): the new list
  */
 GstTagList *
 gst_tag_list_merge (const GstTagList * list1, const GstTagList * list2,
@@ -1424,8 +1426,9 @@ 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: (transfer none): The GValue for the specified entry or %NULL if the
+ * Returns: (transfer none) (nullable): The GValue for the specified
- *          tag wasn't available or the tag doesn't have as many entries
+ *          entry or %NULL if the tag wasn't available or the tag
+ *          doesn't have as many entries
  */
 const GValue *
 gst_tag_list_get_value_index (const GstTagList * list, const gchar * tag,

gst/gsttagsetter.c

@@ -340,8 +340,8 @@ gst_tag_setter_add_tag_value (GstTagSetter * setter,
  *
  * This function is not thread-safe.
  *
- * Returns: (transfer none): a current snapshot of the taglist used in the
+ * Returns: (transfer none) (nullable): a current snapshot of the
- *          setter or %NULL if none is used.
+ *          taglist used in the setter or %NULL if none is used.
  */
 const GstTagList *
 gst_tag_setter_get_tag_list (GstTagSetter * setter)

gst/gsttaskpool.c

@@ -223,9 +223,9 @@ gst_task_pool_cleanup (GstTaskPool * pool)
  *
  * Start the execution of a new thread from @pool.
  *
- * Returns: (transfer none): a pointer that should be used for the
+ * Returns: (transfer none) (nullable): a pointer that should be used
- * gst_task_pool_join function. This pointer can be %NULL, you must
+ * for the gst_task_pool_join function. This pointer can be %NULL, you
- * check @error to detect errors.
+ * must check @error to detect errors.
  */
 gpointer
 gst_task_pool_push (GstTaskPool * pool, GstTaskPoolFunction func,

gst/gsttoc.c

@@ -360,7 +360,8 @@ gst_toc_entry_find_sub_entry (const GstTocEntry * entry, const gchar * uid)
  *
  * Find #GstTocEntry with given @uid in the @toc.
  *
- * Returns: (transfer none): #GstTocEntry with specified @uid from the @toc, or %NULL if not found.
+ * Returns: (transfer none) (nullable): #GstTocEntry with specified
+ * @uid from the @toc, or %NULL if not found.
  */
 GstTocEntry *
 gst_toc_find_entry (const GstToc * toc, const gchar * uid)
@@ -393,8 +394,9 @@ gst_toc_find_entry (const GstToc * toc, const gchar * uid)
  *
  * Copy #GstTocEntry with all subentries (deep copy).
  *
- * Returns: newly allocated #GstTocEntry in case of success, %NULL otherwise;
+ * Returns: (nullable): newly allocated #GstTocEntry in case of
- * free it when done with gst_toc_entry_unref().
+ * success, %NULL otherwise; free it when done with
+ * gst_toc_entry_unref().
  */
 static GstTocEntry *
 gst_toc_entry_copy (const GstTocEntry * entry)
@@ -437,8 +439,8 @@ gst_toc_entry_copy (const GstTocEntry * entry)
  *
  * Copy #GstToc with all subentries (deep copy).
  *
- * Returns: newly allocated #GstToc in case of success, %NULL otherwise;
+ * Returns: (nullable): newly allocated #GstToc in case of success,
- * free it when done with gst_toc_unref().
+ * %NULL otherwise; free it when done with gst_toc_unref().
  */
 static GstToc *
 gst_toc_copy (const GstToc * toc)

gst/gsttocsetter.c

@@ -128,8 +128,8 @@ gst_toc_setter_reset (GstTocSetter * setter)
  * modified without making it writable first.
  *
  *
- * Returns: (transfer full): TOC set, or %NULL. Unref with gst_toc_unref()
+ * Returns: (transfer full) (nullable): TOC set, or %NULL. Unref with
- *     when no longer needed
+ *     gst_toc_unref() when no longer needed
  */
 GstToc *
 gst_toc_setter_get_toc (GstTocSetter * setter)

gst/gsttypefind.c

@@ -119,8 +119,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: (transfer none) (array length=size): the requested data, or %NULL
+ * Returns: (transfer none) (array length=size) (nullable): the
- *     if that data is not available.
+ *     requested data, or %NULL if that data is not available.
  */
 const guint8 *
 gst_type_find_peek (GstTypeFind * find, gint64 offset, guint size)

gst/gsttypefindfactory.c

@@ -177,8 +177,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: (transfer none) (array zero-terminated=1) (element-type utf8): a
+ * Returns: (transfer none) (array zero-terminated=1) (element-type utf8) (nullable):
- *     %NULL-terminated array of extensions associated with this factory
+ *     a %NULL-terminated array of extensions associated with this factory
  */
 const gchar *const *
 gst_type_find_factory_get_extensions (GstTypeFindFactory * factory)

gst/gsturi.c

@@ -233,9 +233,9 @@ unescape_character (const char *scanner)
  * Characters are encoded in PERCENTxy form, where xy is the ASCII hex code
  * for character 16x+y.
  *
- * Return value: a newly allocated string with the unescaped equivalents,
+ * Return value: (nullable): a newly allocated string with the
- * or %NULL if @escaped_string contained one of the characters
+ * unescaped equivalents, or %NULL if @escaped_string contained one of
- * in @illegal_characters.
+ * the characters in @illegal_characters.
  **/
 static char *
 unescape_string (const gchar * escaped_string, const gchar * illegal_characters)
@@ -664,9 +664,10 @@ gst_uri_handler_get_uri_type (GstURIHandler * handler)
  * Gets the list of protocols supported by @handler. This list may not be
  * modified.
  *
- * Returns: (transfer none) (element-type utf8): the supported protocols.
+ * Returns: (transfer none) (element-type utf8) (nullable): the
- *     Returns %NULL if the @handler isn't implemented properly, or the @handler
+ *     supported protocols.  Returns %NULL if the @handler isn't
- *     doesn't support any protocols.
+ *     implemented properly, or the @handler doesn't support any
+ *     protocols.
  */
 const gchar *const *
 gst_uri_handler_get_protocols (GstURIHandler * handler)
@@ -692,9 +693,10 @@ gst_uri_handler_get_protocols (GstURIHandler * handler)
  *
  * Gets the currently handled URI.
  *
- * Returns: (transfer full): the URI currently handled by the @handler.
+ * Returns: (transfer full) (nullable): the URI currently handled by
- *   Returns %NULL if there are no URI currently handled. The
+ *   the @handler.  Returns %NULL if there are no URI currently
- *   returned string must be freed with g_free() when no longer needed.
+ *   handled. The returned string must be freed with g_free() when no
+ *   longer needed.
  */
 gchar *
 gst_uri_handler_get_uri (GstURIHandler * handler)

gst/gstutils.c

@@ -773,8 +773,8 @@ gst_element_create_all_pads (GstElement * element)
  * Retrieves a pad template from @element that is compatible with @compattempl.
  * Pads from compatible templates can be linked together.
  *
- * Returns: (transfer none): a compatible #GstPadTemplate, or %NULL if none
+ * Returns: (transfer none) (nullable): a compatible #GstPadTemplate,
- *     was found. No unreferencing is necessary.
+ *   or %NULL if none was found. No unreferencing is necessary.
  */
 GstPadTemplate *
 gst_element_get_compatible_pad_template (GstElement * element,
@@ -850,8 +850,8 @@ gst_element_get_compatible_pad_template (GstElement * element,
  * #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES
  * templates.
  *
- * Returns: (transfer full): the #GstPad, or NULL if one could not be found
+ * Returns: (transfer full) (nullable): the #GstPad, or %NULL if one
- *     or created.
+ *   could not be found or created.
  */
 static GstPad *
 gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ)
@@ -891,7 +891,8 @@ gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ)
  * Requests a pad from @element. The returned pad should be unlinked and
  * compatible with @templ. Might return an existing pad, or request a new one.
  *
- * Returns: a #GstPad, or %NULL if one could not be found or created.
+ * Returns: (nullable): a #GstPad, or %NULL if one could not be found
+ *   or created.
  */
 static GstPad *
 gst_element_request_compatible_pad (GstElement * element,
@@ -984,8 +985,9 @@ 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: (transfer full): the #GstPad to which a link can be made, or %NULL
+ * Returns: (transfer full) (nullable): the #GstPad to which a link
- *     if one cannot be found. gst_object_unref() after usage.
+ *   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,
@@ -2311,8 +2313,9 @@ gst_pad_use_fixed_caps (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: (transfer full): the parent of the pad. The caller has a
+ * Returns: (transfer full) (nullable): the parent of the pad. The
- * reference on the parent, so unref when you're finished with it.
+ * caller has a reference on the parent, so unref when you're finished
+ * with it.
  *
  * MT safe.
  */
@@ -2957,7 +2960,8 @@ 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: (transfer full): unlinked pad of the given direction, %NULL.
+ * Returns: (transfer full) (nullable): unlinked pad of the given
+ * direction, %NULL.
  */
 GstPad *
 gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction)
@@ -3017,8 +3021,8 @@ gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction)
  * and want them all ghosted, you will have to create the ghost pads
  * yourself).
  *
- * Returns: (transfer floating) (type Gst.Bin): a newly-created bin,
+ * Returns: (transfer floating) (type Gst.Bin) (nullable): a
- *   or %NULL if an error occurred.
+ *   newly-created bin, or %NULL if an error occurred.
  */
 GstElement *
 gst_parse_bin_from_description (const gchar * bin_description,
@@ -3159,7 +3163,8 @@ gst_util_get_timestamp (void)
  *
  * The complexity of this search function is O(log (num_elements)).
  *
- * Returns: (transfer none): The address of the found element or %NULL if nothing was found
+ * Returns: (transfer none) (nullable): The address of the found
+ * element or %NULL if nothing was found
  */
 gpointer
 gst_util_array_binary_search (gpointer array, guint num_elements,
@@ -3778,8 +3783,9 @@ gst_pad_create_stream_id (GstPad * pad, GstElement * parent,
  * The returned stream-id string should be treated as an opaque string, its
  * contents should not be interpreted.
  *
- * Returns: a newly-allocated copy of the stream-id for @pad, or %NULL.
+ * Returns: (nullable): a newly-allocated copy of the stream-id for
- *     g_free() the returned string when no longer needed.
+ *     @pad, or %NULL.  g_free() the returned string when no longer
+ *     needed.
  *
  * Since: 1.2
  */

gst/gstvalue.c

@@ -5059,7 +5059,8 @@ gst_value_move (GValue * dest, GValue * src)
  *
  * Free-function: g_free
  *
- * Returns: (transfer full): the serialization for @value or %NULL if none exists
+ * Returns: (transfer full) (nullable): the serialization for @value
+ * or %NULL if none exists
  */
 gchar *
 gst_value_serialize (const GValue * value)