tag: Add/fix various annotations

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

subprojects/gst-plugins-base/gst-libs/gst/tag/gstid3tag.c

@@ -122,7 +122,7 @@ static const GstTagEntryMatch tag_matches[] = {
  *
  * Looks up the GStreamer tag for a ID3v2 tag.
  *
- * Returns: The corresponding GStreamer tag or NULL if none exists.
+ * Returns: (nullable): The corresponding GStreamer tag or NULL if none exists.
  */
 const gchar *
 gst_tag_from_id3_tag (const gchar * id3_tag)
@@ -190,7 +190,7 @@ static const GstTagEntryMatch user_tag_matches[] = {
  * Looks up the GStreamer tag for an ID3v2 user tag (e.g. description in
  * TXXX frame or owner in UFID frame).
  *
- * Returns: The corresponding GStreamer tag or NULL if none exists.
+ * Returns: (nullable): The corresponding GStreamer tag or NULL if none exists.
  */
 const gchar *
 gst_tag_from_id3_user_tag (const gchar * type, const gchar * id3_user_tag)
@@ -222,7 +222,7 @@ gst_tag_from_id3_user_tag (const gchar * type, const gchar * id3_user_tag)
  *
  * Looks up the ID3v2 tag for a GStreamer tag.
  *
- * Returns: The corresponding ID3v2 tag or NULL if none exists.
+ * Returns: (nullable): The corresponding ID3v2 tag or NULL if none exists.
  */
 const gchar *
 gst_tag_to_id3_tag (const gchar * gst_tag)
@@ -265,7 +265,7 @@ gst_tag_extract_id3v1_string (GstTagList * list, const gchar * tag,
  * Parses the data containing an ID3v1 tag and returns a #GstTagList from the
  * parsed data.
  *
- * Returns: A new tag list or NULL if the data was not an ID3v1 tag.
+ * Returns: (transfer full) (nullable): A new tag list or NULL if the data was not an ID3v1 tag.
  */
 GstTagList *
 gst_tag_list_new_from_id3v1 (const guint8 * data)
@@ -328,7 +328,7 @@ gst_tag_id3_genre_count (void)
  *
  * Gets the ID3v1 genre name for a given ID.
  *
- * Returns: the genre or NULL if no genre is associated with that ID.
+ * Returns: (nullable): the genre or NULL if no genre is associated with that ID.
  */
 const gchar *
 gst_tag_id3_genre_get (const guint id)

subprojects/gst-plugins-base/gst-libs/gst/tag/gstvorbistag.c

@@ -117,7 +117,7 @@ static const GstTagEntryMatch tag_matches[] = {
  *
  * Looks up the GStreamer tag for a vorbiscomment tag.
  *
- * Returns: The corresponding GStreamer tag or NULL if none exists.
+ * Returns: (nullable): The corresponding GStreamer tag or NULL if none exists.
  */
 const gchar *
 gst_tag_from_vorbis_tag (const gchar * vorbis_tag)
@@ -146,7 +146,7 @@ gst_tag_from_vorbis_tag (const gchar * vorbis_tag)
  *
  * Looks up the vorbiscomment tag for a GStreamer tag.
  *
- * Returns: The corresponding vorbiscomment tag or NULL if none exists.
+ * Returns: (nullable): The corresponding vorbiscomment tag or NULL if none exists.
  */
 const gchar *
 gst_tag_to_vorbis_tag (const gchar * gst_tag)
@@ -417,7 +417,7 @@ decode_failed:
  * Creates a new tag list that contains the information parsed out of a
  * vorbiscomment packet.
  *
- * Returns: A new #GstTagList with all tags that could be extracted from the
+ * Returns: (transfer full) (nullable): A new #GstTagList with all tags that could be extracted from the
  *          given vorbiscomment buffer or NULL on error.
  */
 GstTagList *
@@ -513,7 +513,7 @@ error:
  * Creates a new tag list that contains the information parsed out of a
  * vorbiscomment packet.
  *
- * Returns: A new #GstTagList with all tags that could be extracted from the
+ * Returns: (transfer full) (nullable): A new #GstTagList with all tags that could be extracted from the
  *          given vorbiscomment buffer or NULL on error.
  */
 GstTagList *
@@ -787,7 +787,7 @@ write_one_tag (const GstTagList * list, const gchar * tag, gpointer user_data)
  *
  * Creates a new vorbiscomment buffer from a tag list.
  *
- * Returns: A new #GstBuffer containing a vorbiscomment buffer with all tags
+ * Returns: (transfer full): A new #GstBuffer containing a vorbiscomment buffer with all tags
  *          that could be converted from the given tag list.
  */
 GstBuffer *

subprojects/gst-plugins-base/gst-libs/gst/tag/gstxmptag.c

@@ -79,7 +79,7 @@ static const gchar *schema_list[] = {
  *
  * Gets the list of supported schemas in the xmp lib
  *
- * Returns: (transfer none): a %NULL terminated array of strings with the
+ * Returns: (transfer none) (array zero-terminated=1): a %NULL terminated array of strings with the
  *     schema names
  */
 const gchar **
@@ -1175,7 +1175,7 @@ read_one_tag (GstTagList * list, XmpTag * xmptag,
  *
  * Parse a xmp packet into a taglist.
  *
- * Returns: new taglist or %NULL, free the list when done
+ * Returns: (transfer full) (nullable): new taglist or %NULL, free the list when done
  */
 GstTagList *
 gst_tag_list_from_xmp_buffer (GstBuffer * buffer)
@@ -1700,14 +1700,14 @@ write_one_tag (const GstTagList * list, XmpTag * xmp_tag, gpointer user_data)
  * gst_tag_list_to_xmp_buffer:
  * @list: tags
  * @read_only: does the container forbid inplace editing
- * @schemas: (array zero-terminated):
+ * @schemas: (array zero-terminated=1):
  *     %NULL terminated array of schemas to be used on serialization
  *
  * Formats a taglist as a xmp packet using only the selected
  * schemas. An empty list (%NULL) means that all schemas should
  * be used
  *
- * Returns: new buffer or %NULL, unref the buffer when done
+ * Returns: (transfer full) (nullable): new buffer or %NULL, unref the buffer when done
  */
 GstBuffer *
 gst_tag_list_to_xmp_buffer (const GstTagList * list, gboolean read_only,

subprojects/gst-plugins-base/gst-libs/gst/tag/id3v2.c

@@ -183,7 +183,7 @@ id3v2_ununsync_data (const guint8 * unsync_data, guint32 * size)
  * Creates a new tag list that contains the information parsed out of a
  * ID3 tag.
  *
- * Returns: A new #GstTagList with all tags that could be extracted from the
+ * Returns: (transfer full) (nullable): A new #GstTagList with all tags that could be extracted from the
  *          given vorbiscomment buffer or NULL on error.
  */
 GstTagList *

subprojects/gst-plugins-base/gst-libs/gst/tag/lang.c

@@ -264,7 +264,7 @@ qsort_strcmp_func (const void *p1, const void *p2)
  * tagging purposes (e.g. to tag an audio track appropriately in a video or
  * audio editor).
  *
- * Returns: (transfer full): NULL-terminated string array with two-letter
+ * Returns: (transfer full) (array zero-terminated=1): NULL-terminated string array with two-letter
  *     language codes. Free with g_strfreev() when no longer needed.
  */
 gchar **
@@ -312,7 +312,7 @@ gst_tag_get_language_codes (void)
  *
  * Language codes are case-sensitive and expected to be lower case.
  *
- * Returns: language name in UTF-8 format, or NULL if @language_code could
+ * Returns: (nullable): language name in UTF-8 format, or NULL if @language_code could
  *     not be mapped to a language name. The returned string must not be
  *     modified and does not need to freed; it will stay valid until the
  *     application is terminated.
@@ -345,7 +345,7 @@ gst_tag_get_language_name (const gchar * language_code)
  *
  * Language codes are case-sensitive and expected to be lower case.
  *
- * Returns: two-letter ISO-639-1 language code string that maps to @lang_code,
+ * Returns: (nullable): two-letter ISO-639-1 language code string that maps to @lang_code,
  *     or NULL if no mapping is known. The returned string must not be
  *     modified or freed.
  */
@@ -429,7 +429,7 @@ gst_tag_get_language_code_iso_639_2X (const gchar * lang_code, guint8 flags)
  *
  * Language codes are case-sensitive and expected to be lower case.
  *
- * Returns: three-letter ISO-639-2 language code string that maps to @lang_code,
+ * Returns: (nullable): three-letter ISO-639-2 language code string that maps to @lang_code,
  *     or NULL if no mapping is known. The returned string must not be
  *     modified or freed.
  */
@@ -463,7 +463,7 @@ gst_tag_get_language_code_iso_639_2T (const gchar * lang_code)
  *
  * Language codes are case-sensitive and expected to be lower case.
  *
- * Returns: three-letter ISO-639-2 language code string that maps to @lang_code,
+ * Returns: (nullable): three-letter ISO-639-2 language code string that maps to @lang_code,
  *     or NULL if no mapping is known. The returned string must not be
  *     modified or freed.
  */

subprojects/gst-plugins-base/gst-libs/gst/tag/licenses.c

@@ -202,7 +202,7 @@ static const gchar jurisdictions[] =
  * (e.g. to tag an audio track appropriately in a video or audio editor, or
  * an image in a camera application).
  *
- * Returns: (transfer full): NULL-terminated array of license strings. Free
+ * Returns: (transfer full) (array zero-terminated=1): NULL-terminated array of license strings. Free
  *     with g_strfreev() when no longer needed.
  */
 gchar **
@@ -346,7 +346,7 @@ gst_tag_get_license_flags (const gchar * license_ref)
  * Get the nick name of a license, which is a short (untranslated) string
  * such as e.g. "CC BY-NC-ND 2.0 UK".
  *
- * Returns: the nick name of the license, or NULL if the license is unknown
+ * Returns: (nullable): the nick name of the license, or NULL if the license is unknown
  */
 const gchar *
 gst_tag_get_license_nick (const gchar * license_ref)
@@ -391,7 +391,7 @@ gst_tag_get_license_nick (const gchar * license_ref)
  * Get the title of a license, which is a short translated description
  * of the license's features (generally not very pretty though).
  *
- * Returns: the title of the license, or NULL if the license is unknown or
+ * Returns: (nullable): the title of the license, or NULL if the license is unknown or
  *    no title is available.
  */
 const gchar *
@@ -417,7 +417,7 @@ gst_tag_get_license_title (const gchar * license_ref)
  * Get the description of a license, which is a translated description
  * of the license's main features.
  *
- * Returns: the description of the license, or NULL if the license is unknown
+ * Returns: (nullable): the description of the license, or NULL if the license is unknown
  *    or a description is not available.
  */
 const gchar *
@@ -448,7 +448,7 @@ gst_tag_get_license_description (const gchar * license_ref)
  * dk, es, fi, fr, hr, hu, il, in, it, jp, kr, mk, mt, mx, my, nl, pe, pl,
  * pt, scotland, se, si, tw, uk, us, za.
  *
- * Returns: the jurisdiction code of the license, or NULL if the license is
+ * Returns: (nullable): the jurisdiction code of the license, or NULL if the license is
  *    unknown or is not specific to a particular jurisdiction.
  */
 const gchar *
@@ -470,7 +470,7 @@ gst_tag_get_license_jurisdiction (const gchar * license_ref)
  *
  * Get the version of a license.
  *
- * Returns: the version of the license, or NULL if the license is not known or
+ * Returns: (nullable): the version of the license, or NULL if the license is not known or
  *    has no version
  */
 const gchar *

subprojects/gst-plugins-base/gst-libs/gst/tag/tags.c

@@ -330,7 +330,7 @@ gst_tag_parse_extended_comment (const gchar * ext_comment, gchar ** key,
  * are specified, the current locale will be tried. If that also doesn't work,
  * WINDOWS-1252/ISO-8859-1 is assumed (which will almost always succeed).
  *
- * Returns: a newly-allocated string in UTF-8 encoding, or NULL
+ * Returns: (nullable): a newly-allocated string in UTF-8 encoding, or NULL
  */
 gchar *
 gst_tag_freeform_string_to_utf8 (const gchar * data, gint size,
@@ -516,7 +516,7 @@ beach:
  * This function will do various checks and typefind the encoded image
  * data (we can't trust the declared mime type).
  *
- * Returns: a newly-allocated image sample for use in tag lists, or NULL
+ * Returns: (transfer full) (nullable): a newly-allocated image sample for use in tag lists, or NULL
  */
 GstSample *
 gst_tag_image_data_to_image_sample (const guint8 * image_data,