audio: Add/fix various annotations

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

subprojects/gst-plugins-base/gst-libs/gst/audio/audio-channel-mixer.c

@@ -817,8 +817,7 @@ DEFINE_FLOAT_MIX_FUNC (double, planar, planar);
  *
  * Create a new channel mixer object for the given parameters.
  *
- * Returns: a new #GstAudioChannelMixer object, or %NULL if @format isn't supported,
+ * Returns: a new #GstAudioChannelMixer object.
- *   @matrix is invalid, or @matrix is %NULL and @in_channels != @out_channels.
  *   Free with gst_audio_channel_mixer_free() after usage.
  *
  * Since: 1.14
@@ -980,7 +979,7 @@ gst_audio_channel_mixer_new_with_matrix (GstAudioChannelMixerFlags flags,
  *
  * Create a new channel mixer object for the given parameters.
  *
- * Returns: a new #GstAudioChannelMixer object, or %NULL if @format isn't supported.
+ * Returns: a new #GstAudioChannelMixer object.
  *   Free with gst_audio_channel_mixer_free() after usage.
  */
 GstAudioChannelMixer *

subprojects/gst-plugins-base/gst-libs/gst/audio/audio-converter.c

@@ -1320,7 +1320,7 @@ converter_resample (GstAudioConverter * convert,
  * @config contains extra configuration options, see `GST_AUDIO_CONVERTER_OPT_*`
  * parameters for details about the options and values.
  *
- * Returns: a #GstAudioConverter or %NULL if conversion is not possible.
+ * Returns: (nullable): a #GstAudioConverter or %NULL if conversion is not possible.
  */
 GstAudioConverter *
 gst_audio_converter_new (GstAudioConverterFlags flags, GstAudioInfo * in_info,

subprojects/gst-plugins-base/gst-libs/gst/audio/audio-info.c

@@ -326,7 +326,7 @@ invalid_channel_mask:
  *
  * Parse @caps to generate a #GstAudioInfo.
  *
- * Returns: A #GstAudioInfo, or %NULL if @caps couldn't be parsed
+ * Returns: (nullable): A #GstAudioInfo, or %NULL if @caps couldn't be parsed
  * Since: 1.20
  */
 GstAudioInfo *

subprojects/gst-plugins-base/gst-libs/gst/audio/audio-resampler.c

@@ -1342,8 +1342,7 @@ gst_audio_resampler_options_set_quality (GstAudioResamplerMethod method,
  *
  * Make a new resampler.
  *
- * Returns: (skip) (transfer full): The new #GstAudioResampler, or
+ * Returns: (skip) (transfer full): The new #GstAudioResampler.
- * %NULL on failure.
  */
 GstAudioResampler *
 gst_audio_resampler_new (GstAudioResamplerMethod method,

subprojects/gst-plugins-base/gst-libs/gst/audio/audio.c

@@ -69,7 +69,7 @@ ensure_debug_category (void)
  * After calling this function the caller does not own a reference to
  * @buffer anymore.
  *
- * Returns: (transfer full): %NULL if the buffer is completely outside the configured segment,
+ * Returns: (transfer full) (nullable): %NULL if the buffer is completely outside the configured segment,
  * otherwise the clipped buffer is returned.
  *
  * If the buffer has no timestamp, it is assumed to be inside the segment and
@@ -267,8 +267,7 @@ gst_audio_buffer_clip (GstBuffer * buffer, const GstSegment * segment,
  * After calling this function the caller does not own a reference to
  * @buffer anymore.
  *
- * Returns: (transfer full): the truncated buffer or %NULL if the arguments
+ * Returns: (transfer full): the truncated buffer
- *   were invalid
  *
  * Since: 1.16
  */

subprojects/gst-plugins-base/gst-libs/gst/audio/gstaudiobasesink.c

@@ -2256,7 +2256,7 @@ sync_latency_failed:
  * call the ::create_ringbuffer vmethod and will set @sink as the parent of
  * the returned buffer (see gst_object_set_parent()).
  *
- * Returns: (transfer none): The new ringbuffer of @sink.
+ * Returns: (transfer none) (nullable): The new ringbuffer of @sink.
  */
 GstAudioRingBuffer *
 gst_audio_base_sink_create_ringbuffer (GstAudioBaseSink * sink)

subprojects/gst-plugins-base/gst-libs/gst/audio/gstaudiobasesrc.c

@@ -1086,7 +1086,7 @@ got_error:
  * the ::create_ringbuffer vmethod and will set @src as the parent of the
  * returned buffer (see gst_object_set_parent()).
  *
- * Returns: (transfer none): The new ringbuffer of @src.
+ * Returns: (transfer none) (nullable): The new ringbuffer of @src.
  */
 GstAudioRingBuffer *
 gst_audio_base_src_create_ringbuffer (GstAudioBaseSrc * src)

subprojects/gst-plugins-base/gst-libs/gst/audio/gstaudiodecoder.c

@@ -1272,7 +1272,7 @@ foreach_metadata (GstBuffer * inbuf, GstMeta ** meta, gpointer user_data)
 /**
  * gst_audio_decoder_finish_subframe:
  * @dec: a #GstAudioDecoder
- * @buf: (transfer full) (allow-none): decoded data
+ * @buf: (transfer full) (nullable): decoded data
  *
  * Collects decoded data and pushes it downstream. This function may be called
  * multiple times for a given input frame.
@@ -1306,7 +1306,7 @@ gst_audio_decoder_finish_subframe (GstAudioDecoder * dec, GstBuffer * buf)
 /**
  * gst_audio_decoder_finish_frame:
  * @dec: a #GstAudioDecoder
- * @buf: (transfer full) (allow-none): decoded data
+ * @buf: (transfer full) (nullable): decoded data
  * @frames: number of decoded frames represented by decoded data
  *
  * Collects decoded data and pushes it downstream.
@@ -2762,8 +2762,8 @@ gst_audio_decoder_propose_allocation_default (GstAudioDecoder * dec,
 /**
  * gst_audio_decoder_proxy_getcaps:
  * @decoder: a #GstAudioDecoder
- * @caps: (allow-none): initial caps
+ * @caps: (nullable): initial caps
- * @filter: (allow-none): filter caps
+ * @filter: (nullable): filter caps
  *
  * Returns caps that express @caps (or sink template caps if @caps == NULL)
  * restricted to rate/channels/... combinations supported by downstream
@@ -3414,8 +3414,8 @@ gst_audio_decoder_set_latency (GstAudioDecoder * dec,
 /**
  * gst_audio_decoder_get_latency:
  * @dec: a #GstAudioDecoder
- * @min: (out) (allow-none): a pointer to storage to hold minimum latency
+ * @min: (out) (optional): a pointer to storage to hold minimum latency
- * @max: (out) (allow-none): a pointer to storage to hold maximum latency
+ * @max: (out) (optional): a pointer to storage to hold maximum latency
  *
  * Sets the variables pointed to by @min and @max to the currently configured
  * latency.
@@ -3457,7 +3457,7 @@ gst_audio_decoder_get_parse_state (GstAudioDecoder * dec,
 /**
  * gst_audio_decoder_set_allocation_caps:
  * @dec: a #GstAudioDecoder
- * @allocation_caps: (allow-none): a #GstCaps or %NULL
+ * @allocation_caps: (nullable): a #GstCaps or %NULL
  *
  * Sets a caps in allocation query which are different from the set
  * pad's caps. Use this function before calling
@@ -3706,7 +3706,7 @@ gst_audio_decoder_get_needs_format (GstAudioDecoder * dec)
 /**
  * gst_audio_decoder_merge_tags:
  * @dec: a #GstAudioDecoder
- * @tags: (allow-none): a #GstTagList to merge, or NULL
+ * @tags: (nullable): a #GstTagList to merge, or NULL
  * @mode: the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE
  *
  * Sets the audio decoder tags and how they should be merged with any
@@ -3796,9 +3796,9 @@ fallback:
 /**
  * gst_audio_decoder_get_allocator:
  * @dec: a #GstAudioDecoder
- * @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) (optional) (transfer full): the
  * #GstAllocationParams of @allocator
  *
  * Lets #GstAudioDecoder sub-classes to know the memory @allocator

subprojects/gst-plugins-base/gst-libs/gst/audio/gstaudioencoder.c

@@ -762,7 +762,7 @@ foreach_metadata (GstBuffer * inbuf, GstMeta ** meta, gpointer user_data)
 /**
  * gst_audio_encoder_finish_frame:
  * @enc: a #GstAudioEncoder
- * @buffer: (transfer full) (allow-none): encoded data
+ * @buffer: (transfer full) (nullable): encoded data
  * @samples: number of samples (per channel) represented by encoded data
  *
  * Collects encoded data and pushes encoded data downstream.
@@ -1531,8 +1531,8 @@ refuse_caps:
 /**
  * gst_audio_encoder_proxy_getcaps:
  * @enc: a #GstAudioEncoder
- * @caps: (allow-none): initial caps
+ * @caps: (nullable): initial caps
- * @filter: (allow-none): filter caps
+ * @filter: (nullable): filter caps
  *
  * Returns caps that express @caps (or sink template caps if @caps == NULL)
  * restricted to channel/rate combinations supported by downstream elements
@@ -2372,8 +2372,8 @@ gst_audio_encoder_set_latency (GstAudioEncoder * enc,
 /**
  * gst_audio_encoder_get_latency:
  * @enc: a #GstAudioEncoder
- * @min: (out) (allow-none): a pointer to storage to hold minimum latency
+ * @min: (out) (optional): a pointer to storage to hold minimum latency
- * @max: (out) (allow-none): a pointer to storage to hold maximum latency
+ * @max: (out) (optional): a pointer to storage to hold maximum latency
  *
  * Sets the variables pointed to by @min and @max to the currently configured
  * latency.
@@ -2416,7 +2416,7 @@ gst_audio_encoder_set_headers (GstAudioEncoder * enc, GList * headers)
 /**
  * gst_audio_encoder_set_allocation_caps:
  * @enc: a #GstAudioEncoder
- * @allocation_caps: (allow-none): a #GstCaps or %NULL
+ * @allocation_caps: (nullable): a #GstCaps or %NULL
  *
  * Sets a caps in allocation query which are different from the set
  * pad's caps. Use this function before calling
@@ -2711,7 +2711,7 @@ gst_audio_encoder_get_drainable (GstAudioEncoder * enc)
 /**
  * gst_audio_encoder_merge_tags:
  * @enc: a #GstAudioEncoder
- * @tags: (allow-none): a #GstTagList to merge, or NULL to unset
+ * @tags: (nullable): a #GstTagList to merge, or NULL to unset
  *     previously-set tags
  * @mode: the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE
  *
@@ -2990,9 +2990,9 @@ fallback:
 /**
  * gst_audio_encoder_get_allocator:
  * @enc: a #GstAudioEncoder
- * @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) (optional) (transfer full): the
  * #GstAllocationParams of @allocator
  *
  * Lets #GstAudioEncoder sub-classes to know the memory @allocator