From 4617b63b5f4b3e8927ab8417aaa342c172643ea7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Mon, 17 Oct 2022 14:51:03 +0300 Subject: [PATCH] tag: Add/fix various annotations Part-of: --- .../gst-plugins-base/gst-libs/gst/tag/gstid3tag.c | 10 +++++----- .../gst-plugins-base/gst-libs/gst/tag/gstvorbistag.c | 10 +++++----- .../gst-plugins-base/gst-libs/gst/tag/gstxmptag.c | 8 ++++---- .../gst-plugins-base/gst-libs/gst/tag/id3v2.c | 2 +- subprojects/gst-plugins-base/gst-libs/gst/tag/lang.c | 10 +++++----- .../gst-plugins-base/gst-libs/gst/tag/licenses.c | 12 ++++++------ subprojects/gst-plugins-base/gst-libs/gst/tag/tags.c | 4 ++-- 7 files changed, 28 insertions(+), 28 deletions(-) diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/gstid3tag.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/gstid3tag.c index 1bb0e8c2e4..d845114d5b 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/gstid3tag.c +++ b/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) diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/gstvorbistag.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/gstvorbistag.c index 756c9d247e..69c8bbbe66 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/gstvorbistag.c +++ b/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 * diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/gstxmptag.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/gstxmptag.c index 95031f4b02..20cd5b8ff2 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/gstxmptag.c +++ b/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, diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/id3v2.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/id3v2.c index 3f351c9007..c295ac89ef 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/id3v2.c +++ b/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 * diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/lang.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/lang.c index ae6dd5417c..50ed53faba 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/lang.c +++ b/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. */ diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/licenses.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/licenses.c index ecb39eaeae..d0eea1e859 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/licenses.c +++ b/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 * diff --git a/subprojects/gst-plugins-base/gst-libs/gst/tag/tags.c b/subprojects/gst-plugins-base/gst-libs/gst/tag/tags.c index f9dce252ff..73e6bb4a36 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/tag/tags.c +++ b/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,