Add some missing nullable annotations

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/678>

gst/gstbufferpool.c

@@ -817,7 +817,7 @@ gst_buffer_pool_has_option (GstBufferPool * pool, const gchar * option)
 /**
  * gst_buffer_pool_config_set_params:
  * @config: a #GstBufferPool configuration
- * @caps: caps for the buffers
+ * @caps: (nullable): caps for the buffers
  * @size: the size of each buffer, not including prefix and padding
  * @min_buffers: the minimum amount of buffers to allocate.
  * @max_buffers: the maximum amount of buffers to allocate or 0 for unlimited.
@@ -842,8 +842,8 @@ gst_buffer_pool_config_set_params (GstStructure * config, GstCaps * caps,
 /**
  * gst_buffer_pool_config_set_allocator:
  * @config: a #GstBufferPool configuration
- * @allocator: (allow-none): a #GstAllocator
- * @params: (allow-none): #GstAllocationParams
+ * @allocator: (nullable): a #GstAllocator
+ * @params: (nullable): #GstAllocationParams
  *
  * Set the @allocator and @params on @config.
  *
@@ -942,7 +942,7 @@ gst_buffer_pool_config_n_options (GstStructure * config)
  * Parse an available @config and get the option at @index of the options API
  * array.
  *
- * Returns: a #gchar of the option at @index.
+ * Returns: (nullable): a #gchar of the option at @index.
  */
 const gchar *
 gst_buffer_pool_config_get_option (GstStructure * config, guint index)
@@ -996,10 +996,10 @@ gst_buffer_pool_config_has_option (GstStructure * config, const gchar * option)
 /**
  * gst_buffer_pool_config_get_params:
  * @config: (transfer none): a #GstBufferPool configuration
- * @caps: (out) (transfer none) (allow-none): the caps of buffers
- * @size: (out) (allow-none): the size of each buffer, not including prefix and padding
- * @min_buffers: (out) (allow-none): the minimum amount of buffers to allocate.
- * @max_buffers: (out) (allow-none): the maximum amount of buffers to allocate or 0 for unlimited.
+ * @caps: (out) (transfer none) (optional) (nullable): the caps of buffers
+ * @size: (out) (optional): the size of each buffer, not including prefix and padding
+ * @min_buffers: (out) (optional): the minimum amount of buffers to allocate.
+ * @max_buffers: (out) (optional): the maximum amount of buffers to allocate or 0 for unlimited.
  *
  * Get the configuration values from @config.
  *
@@ -1024,8 +1024,8 @@ gst_buffer_pool_config_get_params (GstStructure * config, GstCaps ** caps,
 /**
  * gst_buffer_pool_config_get_allocator:
  * @config: (transfer none): a #GstBufferPool configuration
- * @allocator: (out) (allow-none) (transfer none): a #GstAllocator, or %NULL
- * @params: (out) (allow-none): #GstAllocationParams, or %NULL
+ * @allocator: (out) (optional) (nullable) (transfer none): a #GstAllocator, or %NULL
+ * @params: (out caller-allocates) (optional): #GstAllocationParams, or %NULL
  *
  * Get the @allocator and @params from @config.
  *
@@ -1057,7 +1057,7 @@ gst_buffer_pool_config_get_allocator (GstStructure * config,
 /**
  * gst_buffer_pool_config_validate_params:
  * @config: (transfer none): a #GstBufferPool configuration
- * @caps: (transfer none): the excepted caps of buffers
+ * @caps: (nullable) (transfer none): the excepted caps of buffers
  * @size: the expected size of each buffer, not including prefix and padding
  * @min_buffers: the expected minimum amount of buffers to allocate.
  * @max_buffers: the expect maximum amount of buffers to allocate or 0 for unlimited.

gst/gstdatetime.c

@@ -351,7 +351,7 @@ gst_date_time_get_time_zone_offset (const GstDateTime * datetime)
  *
  * 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_y (gint year)
@@ -374,7 +374,7 @@ gst_date_time_new_y (gint year)
  *
  * 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_ym (gint year, gint month)
@@ -401,7 +401,7 @@ gst_date_time_new_ym (gint year, gint month)
  *
  * 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_ymd (gint year, gint month, gint day)
@@ -418,7 +418,7 @@ gst_date_time_new_ymd (gint year, gint month, gint day)
  *
  * 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_from_unix_epoch_local_time (gint64 secs)
@@ -438,7 +438,7 @@ gst_date_time_new_from_unix_epoch_local_time (gint64 secs)
  *
  * 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_from_unix_epoch_utc (gint64 secs)
@@ -456,7 +456,7 @@ gst_date_time_new_from_unix_epoch_utc (gint64 secs)
  * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
  * @usecs. The #GstDateTime is in the local timezone.
  *
- * Returns: (transfer full): a newly created #GstDateTime
+ * Returns: (transfer full) (nullable): a newly created #GstDateTime
  *
  * Since: 1.18
  */
@@ -480,7 +480,7 @@ gst_date_time_new_from_unix_epoch_local_time_usecs (gint64 usecs)
  * Creates a new #GstDateTime using the time since Jan 1, 1970 specified by
  * @usecs. The #GstDateTime is in UTC.
  *
- * Returns: (transfer full): a newly created #GstDateTime
+ * Returns: (transfer full) (nullable): a newly created #GstDateTime
  *
  * Since: 1.18
  */
@@ -546,7 +546,7 @@ gst_date_time_check_fields (gint * year, gint * month, gint * day,
  *
  * 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,
@@ -658,7 +658,7 @@ __gst_date_time_compare (const GstDateTime * dt1, const GstDateTime * dt2)
  *
  * 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,

gst/gstdeviceprovider.c

@@ -554,7 +554,7 @@ gst_device_provider_stop (GstDeviceProvider * provider)
  *
  * Retrieves the factory that was used to create this device provider.
  *
- * Returns: (transfer none): the #GstDeviceProviderFactory used for
+ * Returns: (transfer none) (nullable): the #GstDeviceProviderFactory used for
  *     creating this device provider. no refcounting is needed.
  *
  * Since: 1.4

gst/gstelement.c

@@ -3631,7 +3631,7 @@ gst_element_get_context_unlocked (GstElement * element,
  *
  * MT safe.
  *
- * Returns: (transfer full): A #GstContext or NULL
+ * Returns: (transfer full) (nullable): A #GstContext or NULL
  *
  * Since: 1.8
  */

gst/gstparse.c

@@ -218,7 +218,7 @@ _gst_parse_escape (const gchar * str)
  * @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) (nullable): a new element on success and %NULL
+ * Returns: (transfer floating): a new element on success and %NULL
  * on failure.
  */
 GstElement *
@@ -239,7 +239,7 @@ gst_parse_launchv (const gchar ** argv, GError ** error)
  * @error will contain an error message if an erroneous pipeline is specified.
  * An error does not mean that the pipeline could not be constructed.
  *
- * Returns: (transfer floating) (nullable): a new element on success; on
+ * 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
@@ -296,7 +296,7 @@ gst_parse_launchv_full (const gchar ** argv, GstParseContext * context,
  * To create a sub-pipeline (bin) for embedding into an existing pipeline
  * use gst_parse_bin_from_description().
  *
- * Returns: (transfer floating) (nullable): a new element on success, %NULL on
+ * 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.
@@ -324,7 +324,7 @@ gst_parse_launch (const gchar * pipeline_description, GError ** error)
  * To create a sub-pipeline (bin) for embedding into an existing pipeline
  * use gst_parse_bin_from_description_full().
  *
- * Returns: (transfer floating) (nullable): a new element on success, %NULL on
+ * 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

gst/gstplugin.c

@@ -985,7 +985,7 @@ gst_plugin_get_description (GstPlugin * plugin)
  *
  * get the filename of the plugin
  *
- * Returns: (type filename): the filename of the plugin
+ * Returns: (type filename) (nullable): the filename of the plugin
  */
 const gchar *
 gst_plugin_get_filename (GstPlugin * plugin)

gst/gstregistry.c

@@ -1018,7 +1018,7 @@ gst_registry_lookup_feature_locked (GstRegistry * registry, const char *name)
  *
  * Find a #GstPluginFeature with @name in @registry.
  *
- * Returns: (transfer full): a #GstPluginFeature with its refcount incremented,
+ * Returns: (transfer full) (nullable): a #GstPluginFeature with its refcount incremented,
  *     use gst_object_unref() after usage.
  *
  * MT safe.

gst/gststreamcollection.c

@@ -204,7 +204,7 @@ gst_stream_collection_set_upstream_id (GstStreamCollection * collection,
  *
  * Returns the upstream id of the @collection.
  *
- * Returns: (transfer none): The upstream id
+ * Returns: (transfer none) (nullable): The upstream id
  *
  * Since: 1.10
  */

gst/gsttypefind.c

@@ -41,13 +41,13 @@ G_DEFINE_POINTER_TYPE (GstTypeFind, gst_type_find);
 
 /**
  * gst_type_find_register:
- * @plugin: (allow-none): A #GstPlugin, or %NULL for a static typefind function
+ * @plugin: (nullable): A #GstPlugin, or %NULL for a static typefind function
  * @name: The name for registering
  * @rank: The rank (or importance) of this typefind function
  * @func: The #GstTypeFindFunction to use
- * @extensions: (allow-none): Optional comma-separated list of extensions
+ * @extensions: (nullable): Optional comma-separated list of extensions
  *     that could belong to this type
- * @possible_caps: Optionally the caps that could be returned when typefinding
+ * @possible_caps: (nullable): Optionally the caps that could be returned when typefinding
  *                 succeeds
  * @data: Optional user data. This user data must be available until the plugin
  *        is unloaded.

gst/gsttypefindfactory.c

@@ -159,7 +159,7 @@ gst_type_find_factory_get_list (void)
  *
  * Gets the #GstCaps associated with a typefind factory.
  *
- * Returns: (transfer none): the #GstCaps associated with this factory
+ * Returns: (transfer none) (nullable): the #GstCaps associated with this factory
  */
 GstCaps *
 gst_type_find_factory_get_caps (GstTypeFindFactory * factory)

gst/gsturi.c

@@ -618,7 +618,7 @@ gst_uri_protocol_is_supported (const GstURIType type, const gchar * protocol)
  *
  * Creates an element for handling the given URI.
  *
- * Returns: (transfer floating) (nullable): a new element or %NULL if none
+ * Returns: (transfer floating): a new element or %NULL if none
  * could be created
  */
 GstElement *

gst/gstutils.c

@@ -3407,7 +3407,7 @@ gst_bin_sync_children_states (GstBin * bin)
  * and want them all ghosted, you will have to create the ghost pads
  * yourself).
  *
- * Returns: (transfer floating) (type Gst.Bin) (nullable): a
+ * Returns: (transfer floating) (type Gst.Bin): a
  *   newly-created bin, or %NULL if an error occurred.
  */
 GstElement *
@@ -3438,7 +3438,7 @@ gst_parse_bin_from_description (const gchar * bin_description,
  * and want them all ghosted, you will have to create the ghost pads
  * yourself).
  *
- * Returns: (transfer floating) (type Gst.Element) (nullable): a newly-created
+ * Returns: (transfer floating) (type Gst.Element): a newly-created
  *   element, which is guaranteed to be a bin unless
  *   #GST_PARSE_FLAG_NO_SINGLE_ELEMENT_BINS was passed, or %NULL if an error
  *   occurred.

libs/gst/base/gstaggregator.c

@@ -324,7 +324,7 @@ gst_aggregator_pad_flush (GstAggregatorPad * aggpad, GstAggregator * agg)
  * a #GstAggregator::samples-selected handler, and can be used to precisely
  * control aggregating parameters for a given set of input samples.
  *
- * Returns: The sample that is about to be aggregated. It may hold a #GstBuffer
+ * Returns: (nullable) (transfer full): The sample that is about to be aggregated. It may hold a #GstBuffer
  *   or a #GstBufferList. The contents of its info structure is subclass-dependent,
  *   and documented on a subclass basis. The buffers held by the sample are
  *   not writable.
@@ -3364,7 +3364,7 @@ gst_aggregator_pad_clip_buffer_unlocked (GstAggregatorPad * pad)
  *
  * Steal the ref to the buffer currently queued in @pad.
  *
- * Returns: (transfer full): The buffer in @pad or NULL if no buffer was
+ * Returns: (nullable) (transfer full): The buffer in @pad or NULL if no buffer was
  *   queued. You should unref the buffer after usage.
  */
 GstBuffer *
@@ -3442,7 +3442,7 @@ gst_aggregator_pad_drop_buffer (GstAggregatorPad * pad)
  * gst_aggregator_pad_peek_buffer:
  * @pad: the pad to get buffer from
  *
- * Returns: (transfer full): A reference to the buffer in @pad or
+ * Returns: (nullable) (transfer full): A reference to the buffer in @pad or
  * NULL if no buffer was queued. You should unref the buffer after
  * usage.
  */
@@ -3606,7 +3606,7 @@ gst_aggregator_set_latency (GstAggregator * self,
  * gst_aggregator_get_buffer_pool:
  * @self: a #GstAggregator
  *
- * Returns: (transfer full): the instance of the #GstBufferPool used
+ * Returns: (transfer full) (nullable): the instance of the #GstBufferPool used
  * by @trans; free it after use it
  */
 GstBufferPool *
@@ -3628,9 +3628,9 @@ gst_aggregator_get_buffer_pool (GstAggregator * self)
 /**
  * gst_aggregator_get_allocator:
  * @self: a #GstAggregator
- * @allocator: (out) (allow-none) (transfer full): the #GstAllocator
+ * @allocator: (out) (optional) (nullable) (transfer full): the #GstAllocator
  * used
- * @params: (out) (allow-none) (transfer full): the
+ * @params: (out caller-allocates) (optional): the
  * #GstAllocationParams of @allocator
  *
  * Lets #GstAggregator sub-classes get the memory @allocator

libs/gst/base/gstbasesrc.c

@@ -4054,7 +4054,7 @@ failure:
  * gst_base_src_get_buffer_pool:
  * @src: a #GstBaseSrc
  *
- * Returns: (transfer full): the instance of the #GstBufferPool used
+ * Returns: (nullable) (transfer full): the instance of the #GstBufferPool used
  * by the src; unref it after usage.
  */
 GstBufferPool *
@@ -4075,10 +4075,9 @@ gst_base_src_get_buffer_pool (GstBaseSrc * src)
 /**
  * gst_base_src_get_allocator:
  * @src: a #GstBaseSrc
- * @allocator: (out) (allow-none) (transfer full): the #GstAllocator
+ * @allocator: (out) (optional) (nullable) (transfer full): the #GstAllocator
  * used
- * @params: (out) (allow-none) (transfer full): the
- * #GstAllocationParams of @allocator
+ * @params: (out caller-allocates) (optional): the #GstAllocationParams of @allocator
  *
  * Lets #GstBaseSrc sub-classes to know the memory @allocator
  * used by the base class and its @params.

libs/gst/base/gstbasetransform.c

@@ -2847,7 +2847,7 @@ gst_base_transform_reconfigure_src (GstBaseTransform * trans)
  * gst_base_transform_get_buffer_pool:
  * @trans: a #GstBaseTransform
  *
- * Returns: (transfer full): the instance of the #GstBufferPool used
+ * Returns: (nullable) (transfer full): the instance of the #GstBufferPool used
  * by @trans; free it after use
  */
 GstBufferPool *
@@ -2864,10 +2864,9 @@ gst_base_transform_get_buffer_pool (GstBaseTransform * trans)
 /**
  * gst_base_transform_get_allocator:
  * @trans: a #GstBaseTransform
- * @allocator: (out) (allow-none) (transfer full): the #GstAllocator
+ * @allocator: (out) (optional) (nullable) (transfer full): the #GstAllocator
  * used
- * @params: (out) (allow-none) (transfer full): the
- * #GstAllocationParams of @allocator
+ * @params: (out caller-allocates) (optional): the #GstAllocationParams of @allocator
  *
  * Lets #GstBaseTransform sub-classes know the memory @allocator
  * used by the base class and its @params.