From 2b22befc4f665a4557b02704eff930f7d686d028 Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:17:18 +0000 Subject: [PATCH 01/10] gprintf: Add missing (out) annotation to g_vasprintf() --- glib/gprintf.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/glib/gprintf.c b/glib/gprintf.c index 7cf30d2cf..34ba8e92f 100644 --- a/glib/gprintf.c +++ b/glib/gprintf.c @@ -297,7 +297,7 @@ g_vsnprintf (gchar *string, /** * g_vasprintf: - * @string: (not optional) (nullable): the return location for the newly-allocated string, + * @string: (out) (not optional) (nullable): the return location for the newly-allocated string, * which will be %NULL if (and only if) this function fails * @format: (not nullable): a standard printf() format string, but notice * [string precision pitfalls](string-utils.html#string-precision-pitfalls) From 8d2d12bd522f2853582154ee5d82b6717df1cfe2 Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Sat, 6 Jan 2024 16:50:42 +0100 Subject: [PATCH 02/10] gprintf: Port doc comments to gi-docgen Fixes broken links, and removes `%` and `#` notation in favor of inline code, and limits indentation to two to prevent accidental formatting. Fixes some style issues too, mainly removing periods at the end of parameter and return descriptions. Also removes trailing whitespace from the doc comments. Helps: #3037 --- glib/gprintf.c | 151 +++++++++++++++++++++++++------------------------ 1 file changed, 76 insertions(+), 75 deletions(-) diff --git a/glib/gprintf.c b/glib/gprintf.c index 34ba8e92f..c9a99142a 100644 --- a/glib/gprintf.c +++ b/glib/gprintf.c @@ -30,20 +30,20 @@ /** * g_printf: - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @...: the arguments to insert in the output. + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @...: the arguments to insert in the output * - * An implementation of the standard printf() function which supports + * An implementation of the standard `printf()` function which supports * positional parameters, as specified in the Single Unix Specification. * - * As with the standard printf(), this does not automatically append a trailing + * As with the standard `printf()`, this does not automatically append a trailing * new-line character to the message, so typically @format should end with its * own new-line character. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * Returns: the number of bytes printed. + * Returns: the number of bytes printed * * Since: 2.2 **/ @@ -63,17 +63,17 @@ g_printf (gchar const *format, /** * g_fprintf: - * @file: (not nullable): the stream to write to. - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @...: the arguments to insert in the output. + * @file: (not nullable): the stream to write to + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @...: the arguments to insert in the output * - * An implementation of the standard fprintf() function which supports + * An implementation of the standard `fprintf()` function which supports * positional parameters, as specified in the Single Unix Specification. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * Returns: the number of bytes printed. + * Returns: the number of bytes printed * * Since: 2.2 **/ @@ -95,23 +95,23 @@ g_fprintf (FILE *file, /** * g_sprintf: * @string: A pointer to a memory buffer to contain the resulting string. It - * is up to the caller to ensure that the allocated buffer is large - * enough to hold the formatted result - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @...: the arguments to insert in the output. + * is up to the caller to ensure that the allocated buffer is large + * enough to hold the formatted result. + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @...: the arguments to insert in the output * - * An implementation of the standard sprintf() function which supports + * An implementation of the standard `sprintf()` function which supports * positional parameters, as specified in the Single Unix Specification. * - * Note that it is usually better to use g_snprintf(), to avoid the + * Note that it is usually better to use [func@GLib.snprintf], to avoid the * risk of buffer overflow. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * See also g_strdup_printf(). + * See also [func@GLib.strdup_printf]. * - * Returns: the number of bytes printed. + * Returns: the number of bytes printed * * Since: 2.2 **/ @@ -132,18 +132,18 @@ g_sprintf (gchar *string, /** * g_snprintf: - * @string: the buffer to hold the output. + * @string: the buffer to hold the output * @n: the maximum number of bytes to produce (including the - * terminating nul character). - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @...: the arguments to insert in the output. + * terminating nul character) + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @...: the arguments to insert in the output * * A safer form of the standard sprintf() function. The output is guaranteed * to not exceed @n characters (including the terminating nul character), so * it is easy to ensure that a buffer overflow cannot occur. * - * See also g_strdup_printf(). + * See also [func@GLib.strdup_printf]. * * In versions of GLib prior to 1.2.3, this function may return -1 if the * output was truncated, and the truncated string may not be nul-terminated. @@ -152,13 +152,13 @@ g_sprintf (gchar *string, * * The return value of g_snprintf() conforms to the snprintf() * function as standardized in ISO C99. Note that this is different from - * traditional snprintf(), which returns the length of the output string. + * traditional `snprintf()`, which returns the length of the output string. * * The format string may contain positional parameters, as specified in * the Single Unix Specification. * - * Returns: the number of bytes which would be produced if the buffer - * was large enough. + * Returns: the number of bytes which would be produced if the buffer + * was large enough **/ gint g_snprintf (gchar *string, @@ -178,16 +178,16 @@ g_snprintf (gchar *string, /** * g_vprintf: - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @args: the list of arguments to insert in the output. + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @args: the list of arguments to insert in the output * - * An implementation of the standard vprintf() function which supports + * An implementation of the standard `vprintf()` function which supports * positional parameters, as specified in the Single Unix Specification. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * Returns: the number of bytes printed. + * Returns: the number of bytes printed * * Since: 2.2 **/ @@ -202,17 +202,17 @@ g_vprintf (gchar const *format, /** * g_vfprintf: - * @file: (not nullable): the stream to write to. - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @args: the list of arguments to insert in the output. + * @file: (not nullable): the stream to write to + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @args: the list of arguments to insert in the output * - * An implementation of the standard fprintf() function which supports + * An implementation of the standard `fprintf()` function which supports * positional parameters, as specified in the Single Unix Specification. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * Returns: the number of bytes printed. + * Returns: the number of bytes printed * * Since: 2.2 **/ @@ -228,17 +228,17 @@ g_vfprintf (FILE *file, /** * g_vsprintf: - * @string: the buffer to hold the output. - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @args: the list of arguments to insert in the output. + * @string: the buffer to hold the output + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @args: the list of arguments to insert in the output * - * An implementation of the standard vsprintf() function which supports + * An implementation of the standard `vsprintf()` function which supports * positional parameters, as specified in the Single Unix Specification. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * Returns: the number of bytes printed. + * Returns: the number of bytes printed * * Since: 2.2 **/ @@ -253,35 +253,35 @@ g_vsprintf (gchar *string, return _g_vsprintf (string, format, args); } -/** +/** * g_vsnprintf: - * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the - * terminating nul character). - * @format: a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @args: the list of arguments to insert in the output. + * @string: the buffer to hold the output + * @n: the maximum number of bytes to produce (including the + * terminating nul character) + * @format: a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @args: the list of arguments to insert in the output * - * A safer form of the standard vsprintf() function. The output is guaranteed - * to not exceed @n characters (including the terminating nul character), so + * A safer form of the standard `vsprintf()` function. The output is guaranteed + * to not exceed @n characters (including the terminating nul character), so * it is easy to ensure that a buffer overflow cannot occur. * - * See also g_strdup_vprintf(). + * See also [func@GLib.strdup_vprintf]. * - * In versions of GLib prior to 1.2.3, this function may return -1 if the + * In versions of GLib prior to 1.2.3, this function may return -1 if the * output was truncated, and the truncated string may not be nul-terminated. - * In versions prior to 1.3.12, this function returns the length of the output + * In versions prior to 1.3.12, this function returns the length of the output * string. * - * The return value of g_vsnprintf() conforms to the vsnprintf() function - * as standardized in ISO C99. Note that this is different from traditional - * vsnprintf(), which returns the length of the output string. + * The return value of `g_vsnprintf()` conforms to the `vsnprintf()` function + * as standardized in ISO C99. Note that this is different from traditional + * `vsnprintf()`, which returns the length of the output string. * - * The format string may contain positional parameters, as specified in + * The format string may contain positional parameters, as specified in * the Single Unix Specification. * - * Returns: the number of bytes which would be produced if the buffer - * was large enough. + * Returns: the number of bytes which would be produced if the buffer + * was large enough */ gint g_vsnprintf (gchar *string, @@ -297,25 +297,26 @@ g_vsnprintf (gchar *string, /** * g_vasprintf: - * @string: (out) (not optional) (nullable): the return location for the newly-allocated string, - * which will be %NULL if (and only if) this function fails - * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) - * @args: the list of arguments to insert in the output. + * @string: (out) (not optional) (nullable): the return location for the + * newly-allocated string, which will be `NULL` if (and only if) + * this function fails + * @format: (not nullable): a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @args: the list of arguments to insert in the output * - * An implementation of the GNU vasprintf() function which supports + * An implementation of the GNU `vasprintf()` function which supports * positional parameters, as specified in the Single Unix Specification. - * This function is similar to g_vsprintf(), except that it allocates a - * string to hold the output, instead of putting the output in a buffer + * This function is similar to [func@GLib.vsprintf], except that it allocates a + * string to hold the output, instead of putting the output in a buffer * you allocate in advance. * - * The returned value in @string is guaranteed to be non-NULL, unless + * The returned value in @string is guaranteed to be non-`NULL`, unless * @format contains `%lc` or `%ls` conversions, which can fail if no * multibyte representation is available for the given character. * * `glib/gprintf.h` must be explicitly included in order to use this function. * - * Returns: the number of bytes printed, or `-1` on failure + * Returns: the number of bytes printed, or -1 on failure * * Since: 2.4 **/ From 16ea531ecb25ed6069453a679849f8ed8eeb8f06 Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:20:00 +0000 Subject: [PATCH 03/10] gstrfuncs: Add missing (array) annotation to g_strfreev() --- glib/gstrfuncs.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 8dd722afd..500836cf7 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -2533,7 +2533,7 @@ g_strsplit_set (const gchar *string, /** * g_strfreev: - * @str_array: (nullable) (transfer full): a %NULL-terminated array of strings to free + * @str_array: (array zero-terminated=1) (nullable) (transfer full): a %NULL-terminated array of strings to free * * Frees a %NULL-terminated array of strings, as well as each * string it contains. From 2d5f608454317676ec3e04bbbb14b0b0b2bea442 Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:22:54 +0000 Subject: [PATCH 04/10] gstrfuncs: Add missing (transfer) and (nullable) annotations to g_memdup() --- glib/gstrfuncs.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 500836cf7..2b31a4e38 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -338,7 +338,7 @@ gchar* * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it * from @mem. If @mem is %NULL it returns %NULL. * - * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem + * Returns: (transfer full) (nullable): a pointer to the newly-allocated copy of the memory, or %NULL if @mem * is %NULL. * Deprecated: 2.68: Use g_memdup2() instead, as it accepts a #gsize argument * for @byte_size, avoiding the possibility of overflow in a #gsize → #guint @@ -372,7 +372,7 @@ g_memdup (gconstpointer mem, * This replaces g_memdup(), which was prone to integer overflows when * converting the argument from a #gsize to a #guint. * - * Returns: (nullable): a pointer to the newly-allocated copy of the memory, + * Returns: (transfer full) (nullable): a pointer to the newly-allocated copy of the memory, * or %NULL if @mem is %NULL. * Since: 2.68 */ From 8689a1f8b78c3bbd32b361ec8394b8622e1cb5ab Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:25:09 +0000 Subject: [PATCH 05/10] gstrfuncs: Add missing (nullable) annotations to g_strndup() --- glib/gstrfuncs.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 2b31a4e38..c57610856 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -395,7 +395,7 @@ g_memdup2 (gconstpointer mem, /** * g_strndup: - * @str: the string to duplicate + * @str: (nullable): the string to duplicate * @n: the maximum number of bytes to copy from @str * * Duplicates the first @n bytes of a string, returning a newly-allocated @@ -407,7 +407,7 @@ g_memdup2 (gconstpointer mem, * To copy a number of characters from a UTF-8 encoded string, * use g_utf8_strncpy() instead. * - * Returns: a newly-allocated buffer containing the first @n bytes + * Returns: (nullable): a newly-allocated buffer containing the first @n bytes * of @str, nul-terminated */ gchar* From b869908f16bd50151c1f260fd540076b99e04b7f Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:29:52 +0000 Subject: [PATCH 06/10] gstrfuncs: Add missing (array) annotations to g_strdupv() and g_strjoinv() --- glib/gstrfuncs.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index c57610856..1108ee732 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -2556,14 +2556,14 @@ g_strfreev (gchar **str_array) /** * g_strdupv: - * @str_array: (nullable): a %NULL-terminated array of strings + * @str_array: (array zero-terminated=1) (nullable): a %NULL-terminated array of strings * * Copies %NULL-terminated array of strings. The copy is a deep copy; * the new array should be freed by first freeing each string, then * the array itself. g_strfreev() does this for you. If called * on a %NULL value, g_strdupv() simply returns %NULL. * - * Returns: (nullable) (transfer full): a new %NULL-terminated array of strings. + * Returns: (array zero-terminated=1) (nullable) (transfer full): a new %NULL-terminated array of strings. */ gchar** g_strdupv (gchar **str_array) @@ -2597,7 +2597,7 @@ g_strdupv (gchar **str_array) * g_strjoinv: * @separator: (nullable): a string to insert between each of the * strings, or %NULL - * @str_array: a %NULL-terminated array of strings to join + * @str_array: (array zero-terminated=1): a %NULL-terminated array of strings to join * * Joins a number of strings together to form one long string, with the * optional @separator inserted between each of them. The returned string From 2d5955c4f38b441fb1ea15dc852331ea4762031d Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:32:56 +0000 Subject: [PATCH 07/10] gstrfuncs: Add missing (array) annotation to g_strv_length() --- glib/gstrfuncs.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 1108ee732..1ee237c02 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -2932,7 +2932,7 @@ gboolean (g_str_has_prefix) (const gchar *str, /** * g_strv_length: - * @str_array: a %NULL-terminated array of strings + * @str_array: (array zero-terminated=1): a %NULL-terminated array of strings * * Returns the length of the given %NULL-terminated * string array @str_array. @str_array must not be %NULL. From dc7331f4fbf5b206e8022461419f9628a1abc148 Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:33:09 +0000 Subject: [PATCH 08/10] gstrfuncs: Add missing (optional) annotation to g_str_tokenize_and_fold() --- glib/gstrfuncs.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 1ee237c02..91fe07a3d 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -3044,7 +3044,7 @@ split_words (const gchar *value) * @string: a string * @translit_locale: (nullable): the language code (like 'de' or * 'en_GB') from which @string originates - * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a + * @ascii_alternates: (out) (optional) (transfer full) (array zero-terminated=1): a * return location for ASCII alternates * * Tokenises @string and performs folding on each token. From a834b8b03844b477530f2673181dff2080008d0b Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Thu, 25 Jan 2024 11:35:12 +0000 Subject: [PATCH 09/10] gstrfuncs: Add missing (array) annotations to GStrv comparison functions --- glib/gstrfuncs.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 91fe07a3d..4f9178148 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -3204,7 +3204,7 @@ one_matched: /** * g_strv_contains: - * @strv: a %NULL-terminated array of strings + * @strv: (array zero-terminated=1): a %NULL-terminated array of strings * @str: a string * * Checks if @strv contains @str. @strv must not be %NULL. @@ -3231,8 +3231,8 @@ g_strv_contains (const gchar * const *strv, /** * g_strv_equal: - * @strv1: a %NULL-terminated array of strings - * @strv2: another %NULL-terminated array of strings + * @strv1: (array zero-terminated=1): a %NULL-terminated array of strings + * @strv2: (array zero-terminated=1): another %NULL-terminated array of strings * * Checks if @strv1 and @strv2 contain exactly the same elements in exactly the * same order. Elements are compared using g_str_equal(). To match independently From 66cd3311728c64f456eddadc5796030fbc870f9b Mon Sep 17 00:00:00 2001 From: velsinki <112010-velsinki@users.noreply.gitlab.gnome.org> Date: Sun, 7 Jan 2024 01:17:26 +0100 Subject: [PATCH 10/10] gstrfuncs: Improve and port doc comments to gi-docgen This fixes many things from the port to gi-docgen, but also improves documentation more generally. Main improvements/fixes: - Fix links to functions, constants, etc. - Rewrite code syntax to work with Markdown - Reduce indentation (do not indent by 4 to prevent code blocks) - Remove redundant text such as "can be NULL" or "should be freed" - Move text from large return info texts to main function text - Remove periods at the end of parameter and return descriptions - Do not capitalize the first word of a parameter or return description - Try to improve consistency between docs for similar functions - Convert %TRUE and %FALSE into true and false - Convert other uses of `%` and `#` into inline code Helps: #3037 --- glib/gstrfuncs.c | 851 ++++++++++++++++++++++++----------------------- glib/gstrfuncs.h | 4 +- 2 files changed, 429 insertions(+), 426 deletions(-) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 4f9178148..6c2e942d8 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -63,14 +63,14 @@ * * Determines whether a character is alphanumeric. * - * Unlike the standard C library isalnum() function, this only + * Unlike the standard C library `isalnum()` function, this only * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to cast to `guchar` before * passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII alphanumeric character + * Returns: true if @c is an ASCII alphanumeric character */ /** @@ -79,14 +79,14 @@ * * Determines whether a character is alphabetic (i.e. a letter). * - * Unlike the standard C library isalpha() function, this only + * Unlike the standard C library `isalpha()` function, this only * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to cast to `guchar` before * passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII alphabetic character + * Returns: true if @c is an ASCII alphabetic character */ /** @@ -95,14 +95,14 @@ * * Determines whether a character is a control character. * - * Unlike the standard C library iscntrl() function, this only + * Unlike the standard C library `iscntrl()` function, this only * recognizes standard ASCII control characters and ignores the - * locale, returning %FALSE for all non-ASCII characters. Also, - * unlike the standard library function, this takes a char, not - * an int, so don't call it on %EOF, but no need to cast to #guchar + * locale, returning false for all non-ASCII characters. Also, + * unlike the standard library function, this takes a `char`, not + * an `int`, so don't call it on `EOF`, but no need to cast to `guchar` * before passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII control character. + * Returns: true if @c is an ASCII control character */ /** @@ -111,11 +111,11 @@ * * Determines whether a character is digit (0-9). * - * Unlike the standard C library isdigit() function, this takes - * a char, not an int, so don't call it on %EOF, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * Unlike the standard C library `isdigit()` function, this takes + * a `char`, not an `int`, so don't call it on `EOF`, but no need to + * cast to `guchar` before passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII digit. + * Returns: true if @c is an ASCII digit */ /** @@ -124,14 +124,14 @@ * * Determines whether a character is a printing character and not a space. * - * Unlike the standard C library isgraph() function, this only + * Unlike the standard C library `isgraph()` function, this only * recognizes standard ASCII characters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to cast to `guchar` before * passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII printing character other than space. + * Returns: true if @c is an ASCII printing character other than space */ /** @@ -140,14 +140,14 @@ * * Determines whether a character is an ASCII lower case letter. * - * Unlike the standard C library islower() function, this only + * Unlike the standard C library `islower()` function, this only * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to worry about casting - * to #guchar before passing a possibly non-ASCII character in. + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to worry about casting + * to `guchar` before passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII lower case letter + * Returns: true if @c is an ASCII lower case letter */ /** @@ -156,14 +156,14 @@ * * Determines whether a character is a printing character. * - * Unlike the standard C library isprint() function, this only + * Unlike the standard C library `isprint()` function, this only * recognizes standard ASCII characters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to cast to `guchar` before * passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII printing character. + * Returns: true if @c is an ASCII printing character */ /** @@ -172,14 +172,14 @@ * * Determines whether a character is a punctuation character. * - * Unlike the standard C library ispunct() function, this only + * Unlike the standard C library `ispunct()` function, this only * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to cast to `guchar` before * passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII punctuation character. + * Returns: true if @c is an ASCII punctuation character */ /** @@ -188,14 +188,14 @@ * * Determines whether a character is a white-space character. * - * Unlike the standard C library isspace() function, this only + * Unlike the standard C library `isspace()` function, this only * recognizes standard ASCII white-space and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to cast to `guchar` before * passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII white-space character + * Returns: true if @c is an ASCII white-space character */ /** @@ -204,14 +204,14 @@ * * Determines whether a character is an ASCII upper case letter. * - * Unlike the standard C library isupper() function, this only + * Unlike the standard C library `isupper()` function, this only * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to worry about casting - * to #guchar before passing a possibly non-ASCII character in. + * returning false for all non-ASCII characters. Also, unlike + * the standard library function, this takes a `char`, not an `int`, + * so don't call it on `EOF`, but no need to worry about casting + * to `guchar` before passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII upper case letter + * Returns: true if @c is an ASCII upper case letter */ /** @@ -220,26 +220,26 @@ * * Determines whether a character is a hexadecimal-digit character. * - * Unlike the standard C library isxdigit() function, this takes - * a char, not an int, so don't call it on %EOF, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. + * Unlike the standard C library `isxdigit()` function, this takes + * a `char`, not an `int`, so don't call it on `EOF`, but no need to + * cast to `guchar` before passing a possibly non-ASCII character in. * - * Returns: %TRUE if @c is an ASCII hexadecimal-digit character. + * Returns: true if @c is an ASCII hexadecimal-digit character */ /** * G_ASCII_DTOSTR_BUF_SIZE: * - * A good size for a buffer to be passed into g_ascii_dtostr(). + * A good size for a buffer to be passed into [func@GLib.ascii_dtostr]. * It is guaranteed to be enough for all output of that function * on systems with 64bit IEEE-compatible doubles. * * The typical usage would be something like: - * |[ - * char buf[G_ASCII_DTOSTR_BUF_SIZE]; + * ```C + * char buf[G_ASCII_DTOSTR_BUF_SIZE]; * - * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); - * ]| + * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); + * ``` */ /** @@ -247,7 +247,8 @@ * @string: a string to remove the leading and trailing whitespace from * * Removes leading and trailing whitespace from a string. - * See g_strchomp() and g_strchug(). + * + * See [func@GLib.strchomp] and [func@GLib.strchug]. * * Returns: @string */ @@ -255,7 +256,7 @@ /** * G_STR_DELIMITERS: * - * The standard delimiters, used in g_strdelimit(). + * The standard delimiters, used in [func@GLib.strdelimit]. */ static const guint16 ascii_table_data[256] = { @@ -306,9 +307,7 @@ get_C_locale (void) * g_strdup: * @str: (nullable): the string to duplicate * - * Duplicates a string. If @str is %NULL it returns %NULL. - * The returned string should be freed with g_free() - * when no longer needed. + * Duplicates a string. If @str is `NULL` it returns `NULL`. * * Returns: a newly-allocated copy of @str */ @@ -332,17 +331,17 @@ gchar* /** * g_memdup: - * @mem: the memory to copy. - * @byte_size: the number of bytes to copy. + * @mem: the memory to copy + * @byte_size: the number of bytes to copy * * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it - * from @mem. If @mem is %NULL it returns %NULL. + * from @mem. If @mem is `NULL` it returns `NULL`. * - * Returns: (transfer full) (nullable): a pointer to the newly-allocated copy of the memory, or %NULL if @mem - * is %NULL. - * Deprecated: 2.68: Use g_memdup2() instead, as it accepts a #gsize argument - * for @byte_size, avoiding the possibility of overflow in a #gsize → #guint - * conversion + * Returns: (transfer full) (nullable): a pointer to the newly-allocated copy of the memory + * + * Deprecated: 2.68: Use [func@GLib.memdup2] instead, as it accepts a gsize argument + * for @byte_size, avoiding the possibility of overflow in a `gsize` → `guint` + * conversion */ gpointer g_memdup (gconstpointer mem, @@ -363,17 +362,17 @@ g_memdup (gconstpointer mem, /** * g_memdup2: - * @mem: (nullable): the memory to copy. - * @byte_size: the number of bytes to copy. + * @mem: (nullable): the memory to copy + * @byte_size: the number of bytes to copy * * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it - * from @mem. If @mem is %NULL it returns %NULL. + * from @mem. If @mem is `NULL` it returns `NULL`. * - * This replaces g_memdup(), which was prone to integer overflows when - * converting the argument from a #gsize to a #guint. + * This replaces [func@GLib.memdup], which was prone to integer overflows when + * converting the argument from a `gsize` to a `guint`. + * + * Returns: (transfer full) (nullable): a pointer to the newly-allocated copy of the memory * - * Returns: (transfer full) (nullable): a pointer to the newly-allocated copy of the memory, - * or %NULL if @mem is %NULL. * Since: 2.68 */ gpointer @@ -401,14 +400,13 @@ g_memdup2 (gconstpointer mem, * Duplicates the first @n bytes of a string, returning a newly-allocated * buffer @n + 1 bytes long which will always be nul-terminated. If @str * is less than @n bytes long the buffer is padded with nuls. If @str is - * %NULL it returns %NULL. The returned value should be freed when no longer - * needed. + * `NULL` it returns `NULL`. * * To copy a number of characters from a UTF-8 encoded string, - * use g_utf8_strncpy() instead. + * use [func@GLib.utf8_strncpy] instead. * - * Returns: (nullable): a newly-allocated buffer containing the first @n bytes - * of @str, nul-terminated + * Returns: (nullable): a newly-allocated buffer containing the first + * @n bytes of @str */ gchar* g_strndup (const gchar *str, @@ -434,9 +432,8 @@ g_strndup (const gchar *str, * @fill_char: the byte to fill the string with * * Creates a new string @length bytes long filled with @fill_char. - * The returned string should be freed when no longer needed. * - * Returns: a newly-allocated string filled the @fill_char + * Returns: a newly-allocated string filled with @fill_char */ gchar* g_strnfill (gsize length, @@ -453,15 +450,15 @@ g_strnfill (gsize length, /** * g_stpcpy: - * @dest: destination buffer. - * @src: source string. + * @dest: destination buffer + * @src: source string * * Copies a nul-terminated string into the destination buffer, including * the trailing nul byte, and returns a pointer to the trailing nul byte * in `dest`. The return value is useful for concatenating multiple * strings without having to repeatedly scan for the end. * - * Returns: a pointer to the trailing nul byte in `dest`. + * Returns: a pointer to the trailing nul byte in `dest` **/ gchar * g_stpcpy (gchar *dest, @@ -487,23 +484,23 @@ g_stpcpy (gchar *dest, /** * g_strdup_vprintf: - * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @format: (not nullable): a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @args: the list of parameters to insert into the format string * - * Similar to the standard C vsprintf() function but safer, since it + * Similar to the standard C `vsprintf()` function but safer, since it * calculates the maximum space required and allocates memory to hold - * the result. The returned string should be freed with g_free() when - * no longer needed. + * the result. * * The returned string is guaranteed to be non-NULL, unless @format * contains `%lc` or `%ls` conversions, which can fail if no multibyte * representation is available for the given character. * - * See also g_vasprintf(), which offers the same functionality, but + * See also [func@GLib.vasprintf], which offers the same functionality, but * additionally returns the length of the allocated string. * - * Returns: (nullable) (transfer full): a newly-allocated string holding the result + * Returns: (nullable) (transfer full): a newly-allocated string holding the + * result */ gchar* g_strdup_vprintf (const gchar *format, @@ -518,20 +515,20 @@ g_strdup_vprintf (const gchar *format, /** * g_strdup_printf: - * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls](string-utils.html#string-precision-pitfalls) + * @format: (not nullable): a standard `printf()` format string, but notice + * [string precision pitfalls](string-utils.html#string-precision-pitfalls) * @...: the parameters to insert into the format string * - * Similar to the standard C sprintf() function but safer, since it + * Similar to the standard C `sprintf()` function but safer, since it * calculates the maximum space required and allocates memory to hold - * the result. The returned string should be freed with g_free() when no - * longer needed. + * the result. * * The returned string is guaranteed to be non-NULL, unless @format * contains `%lc` or `%ls` conversions, which can fail if no multibyte * representation is available for the given character. * - * Returns: (nullable) (transfer full): a newly-allocated string holding the result + * Returns: (nullable) (transfer full): a newly-allocated string holding the + * result */ gchar* g_strdup_printf (const gchar *format, @@ -549,14 +546,13 @@ g_strdup_printf (const gchar *format, /** * g_strconcat: - * @string1: the first string to add, which must not be %NULL - * @...: a %NULL-terminated list of strings to append to the string + * @string1: the first string to add, which must not be `NULL` + * @...: a `NULL`-terminated list of strings to append to the string * - * Concatenates all of the given strings into one long string. The - * returned string should be freed with g_free() when no longer needed. + * Concatenates all of the given strings into one long string. * - * The variable argument list must end with %NULL. If you forget the %NULL, - * g_strconcat() will start appending random memory junk to your string. + * The variable argument list must end with `NULL`. If you forget the `NULL`, + * `g_strconcat()` will start appending random memory junk to your string. * * Note that this function is usually not the right function to use to * assemble a translated message from pieces, since proper translation @@ -604,23 +600,24 @@ g_strconcat (const gchar *string1, ...) /** * g_strtod: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. + * @nptr: the string to convert to a numeric value + * @endptr: (out) (transfer none) (optional): if non-`NULL`, it returns the + * character after the last character used in the conversion * - * Converts a string to a #gdouble value. - * It calls the standard strtod() function to handle the conversion, but + * Converts a string to a floating point value. + * + * It calls the standard `strtod()` function to handle the conversion, but * if the string is not completely converted it attempts the conversion - * again with g_ascii_strtod(), and returns the best match. + * again with [func@GLib.ascii_strtod], and returns the best match. * * This function should seldom be used. The normal situation when reading - * numbers not for human consumption is to use g_ascii_strtod(). Only when + * numbers not for human consumption is to use [func@GLib.ascii_strtod]. Only when * you know that you must expect both locale formatted and C formatted numbers * should you use this. Make sure that you don't pass strings such as comma * separated lists of values, since the commas may be interpreted as a decimal * point in some locales, causing unexpected results. * - * Returns: the #gdouble value. + * Returns: the converted value **/ gdouble g_strtod (const gchar *nptr, @@ -657,13 +654,13 @@ g_strtod (const gchar *nptr, /** * g_ascii_strtod: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. + * @nptr: the string to convert to a numeric value + * @endptr: (out) (transfer none) (optional): if non-`NULL`, it returns the + * character after the last character used in the conversion * - * Converts a string to a #gdouble value. + * Converts a string to a floating point value. * - * This function behaves like the standard strtod() function + * This function behaves like the standard `strtod()` function * does in the C locale. It does this without actually changing * the current locale, since that would not be thread-safe. * A limitation of the implementation is that this function @@ -672,20 +669,20 @@ g_strtod (const gchar *nptr, * This function is typically used when reading configuration * files or other non-user input that should be locale independent. * To handle input from the user you should normally use the - * locale-sensitive system strtod() function. + * locale-sensitive system `strtod()` function. * - * To convert from a #gdouble to a string in a locale-insensitive - * way, use g_ascii_dtostr(). + * To convert from a gdouble to a string in a locale-insensitive + * way, use [func@GLib.ascii_dtostr]. * - * If the correct value would cause overflow, plus or minus %HUGE_VAL - * is returned (according to the sign of the value), and %ERANGE is - * stored in %errno. If the correct value would cause underflow, - * zero is returned and %ERANGE is stored in %errno. + * If the correct value would cause overflow, plus or minus `HUGE_VAL` + * is returned (according to the sign of the value), and `ERANGE` is + * stored in `errno`. If the correct value would cause underflow, + * zero is returned and `ERANGE` is stored in `errno`. * - * This function resets %errno before calling strtod() so that + * This function resets `errno` before calling `strtod()` so that * you can reliably detect overflow and underflow. * - * Returns: the #gdouble value. + * Returns: the converted value */ gdouble g_ascii_strtod (const gchar *nptr, @@ -858,21 +855,21 @@ g_ascii_strtod (const gchar *nptr, /** * g_ascii_dtostr: - * @buffer: A buffer to place the resulting string in - * @buf_len: The length of the buffer. - * @d: The #gdouble to convert + * @buffer: a buffer to place the resulting string in + * @buf_len: the length of the buffer + * @d: the value to convert * - * Converts a #gdouble to a string, using the '.' as + * Converts a `gdouble` to a string, using the '.' as * decimal point. * * This function generates enough precision that converting - * the string back using g_ascii_strtod() gives the same machine-number + * the string back using [func@GLib.ascii_strtod] gives the same machine-number * (on machines with IEEE compatible 64bit doubles). It is * guaranteed that the size of the resulting string will never - * be larger than %G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating + * be larger than [const@GLib.ASCII_DTOSTR_BUF_SIZE] bytes, including the terminating * nul character, which is always added. * - * Returns: The pointer to the buffer with the converted string. + * Returns: the pointer to the buffer with the converted string **/ gchar * g_ascii_dtostr (gchar *buffer, @@ -887,26 +884,26 @@ g_ascii_dtostr (gchar *buffer, /** * g_ascii_formatd: - * @buffer: A buffer to place the resulting string in - * @buf_len: The length of the buffer. - * @format: The printf()-style format to use for the + * @buffer: a buffer to place the resulting string in + * @buf_len: the length of the buffer + * @format: the `printf()`-style format to use for the * code to use for converting - * @d: The #gdouble to convert + * @d: the value to convert * - * Converts a #gdouble to a string, using the '.' as + * Converts a `gdouble` to a string, using the '.' as * decimal point. To format the number you pass in - * a printf()-style format string. Allowed conversion + * a `printf()`-style format string. Allowed conversion * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. * * The @format must just be a single format specifier - * starting with `%`, expecting a #gdouble argument. + * starting with `%`, expecting a `gdouble` argument. * * The returned buffer is guaranteed to be nul-terminated. * * If you just want to want to serialize the value into a - * string, use g_ascii_dtostr(). + * string, use [func@GLib.ascii_dtostr]. * - * Returns: The pointer to the buffer with the converted string. + * Returns: the pointer to the buffer with the converted string */ gchar * g_ascii_formatd (gchar *buffer, @@ -1140,35 +1137,36 @@ g_parse_long_long (const gchar *nptr, /** * g_ascii_strtoull: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. - * @base: to be used for the conversion, 2..36 or 0 + * @nptr: the string to convert to a numeric value + * @endptr: (out) (transfer none) (optional): if non-`NULL`, it returns the + * character after the last character used in the conversion + * @base: to be used for the conversion, 2..36 or 0 * - * Converts a string to a #guint64 value. - * This function behaves like the standard strtoull() function + * Converts a string to a `guint64` value. + * + * This function behaves like the standard `strtoull()` function * does in the C locale. It does this without actually * changing the current locale, since that would not be * thread-safe. * * Note that input with a leading minus sign (`-`) is accepted, and will return - * the negation of the parsed number, unless that would overflow a #guint64. + * the negation of the parsed number, unless that would overflow a `guint64`. * Critically, this means you cannot assume that a short fixed length input will - * never result in a low return value, as the input could have a leading `-`. + * result in a low return value, as the input could have a leading `-`. * * This function is typically used when reading configuration * files or other non-user input that should be locale independent. * To handle input from the user you should normally use the - * locale-sensitive system strtoull() function. + * locale-sensitive system `strtoull()` function. * - * If the correct value would cause overflow, %G_MAXUINT64 + * If the correct value would cause overflow, [const@GLib.MAXUINT64] * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and * `EINVAL` is stored in `errno`. * If the string conversion fails, zero is returned, and @endptr returns - * @nptr (if @endptr is non-%NULL). + * @nptr (if @endptr is non-`NULL`). * - * Returns: the #guint64 value or zero on error. + * Returns: the converted value, or zero on error * * Since: 2.2 */ @@ -1192,13 +1190,14 @@ g_ascii_strtoull (const gchar *nptr, /** * g_ascii_strtoll: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. - * @base: to be used for the conversion, 2..36 or 0 + * @nptr: the string to convert to a numeric value + * @endptr: (out) (transfer none) (optional): if non-`NULL`, it returns the + * character after the last character used in the conversion + * @base: to be used for the conversion, 2..36 or 0 * - * Converts a string to a #gint64 value. - * This function behaves like the standard strtoll() function + * Converts a string to a `gint64` value. + * + * This function behaves like the standard `strtoll()` function * does in the C locale. It does this without actually * changing the current locale, since that would not be * thread-safe. @@ -1206,16 +1205,16 @@ g_ascii_strtoull (const gchar *nptr, * This function is typically used when reading configuration * files or other non-user input that should be locale independent. * To handle input from the user you should normally use the - * locale-sensitive system strtoll() function. + * locale-sensitive system `strtoll()` function. * - * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 - * is returned, and `ERANGE` is stored in `errno`. + * If the correct value would cause overflow, [const@GLib.MAXINT64] or + * [const@GLib.MININT64] is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and * `EINVAL` is stored in `errno`. If the * string conversion fails, zero is returned, and @endptr returns @nptr - * (if @endptr is non-%NULL). + * (if @endptr is non-`NULL`). * - * Returns: the #gint64 value or zero on error. + * Returns: the converted value, or zero on error * * Since: 2.12 */ @@ -1251,30 +1250,31 @@ g_ascii_strtoll (const gchar *nptr, /** * g_strerror: - * @errnum: the system error number. See the standard C %errno - * documentation + * @errnum: the system error number. See the standard C `errno` documentation * * Returns a string corresponding to the given error code, e.g. "no - * such process". Unlike strerror(), this always returns a string in + * such process". + * + * Unlike `strerror()`, this always returns a string in * UTF-8 encoding, and the pointer is guaranteed to remain valid for - * the lifetime of the process. + * the lifetime of the process. If the error code is unknown, it returns a + * string like “Unknown error ”. * * Note that the string may be translated according to the current locale. * - * The value of %errno will not be changed by this function. However, it may + * The value of `errno` will not be changed by this function. However, it may * be changed by intermediate function calls, so you should save its value * as soon as the call returns: - * |[ - * int saved_errno; + * ```C + * int saved_errno; * - * ret = read (blah); - * saved_errno = errno; + * ret = read (blah); + * saved_errno = errno; * - * g_strerror (saved_errno); - * ]| + * g_strerror (saved_errno); + * ``` * - * Returns: a UTF-8 string describing the error code. If the error code - * is unknown, it returns a string like "Unknown error: ". + * Returns: the string describing the error code */ const gchar * g_strerror (gint errnum) @@ -1351,12 +1351,13 @@ g_strerror (gint errnum) * @signum: the signal number. See the `signal` documentation * * Returns a string describing the given signal, e.g. "Segmentation fault". - * You should use this function in preference to strsignal(), because it - * returns a string in UTF-8 encoding, and since not all platforms support - * the strsignal() function. + * If the signal is unknown, it returns “unknown signal ()”. * - * Returns: a UTF-8 string describing the signal. If the signal is unknown, - * it returns "unknown signal ()". + * You should use this function in preference to `strsignal()`, because it + * returns a string in UTF-8 encoding, and since not all platforms support + * the `strsignal()` function. + * + * Returns: the string describing the signal */ const gchar * g_strsignal (gint signum) @@ -1383,7 +1384,7 @@ g_strsignal (gint signum) /* Functions g_strlcpy and g_strlcat were originally developed by * Todd C. Miller to simplify writing secure code. - * See http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy + * See http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy * for more information. */ @@ -1418,19 +1419,19 @@ g_strlcat (gchar *dest, * @src: source buffer * @dest_size: length of @dest in bytes * - * Portability wrapper that calls strlcpy() on systems which have it, - * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is + * Portability wrapper that calls `strlcpy()` on systems which have it, + * and emulates `strlcpy()` otherwise. Copies @src to @dest; @dest is * guaranteed to be nul-terminated; @src must be nul-terminated; * @dest_size is the buffer size, not the number of bytes to copy. * * At most @dest_size - 1 characters will be copied. Always nul-terminates * (unless @dest_size is 0). This function does not allocate memory. Unlike - * strncpy(), this function doesn't pad @dest (so it's often faster). It - * returns the size of the attempted result, strlen (src), so if + * `strncpy()`, this function doesn't pad @dest (so it's often faster). It + * returns the size of the attempted result, `strlen (src)`, so if * @retval >= @dest_size, truncation occurred. * - * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), - * but if you really want to avoid screwups, g_strdup() is an even better + * Caveat: `strlcpy()` is supposedly more secure than `strcpy()` or `strncpy()`, + * but if you really want to avoid screwups, [func@GLib.strdup] is an even better * idea. * * Returns: length of @src @@ -1476,25 +1477,25 @@ g_strlcpy (gchar *dest, * @dest: destination buffer, already containing one nul-terminated string * @src: source buffer * @dest_size: length of @dest buffer in bytes (not length of existing string - * inside @dest) + * inside @dest) * - * Portability wrapper that calls strlcat() on systems which have it, + * Portability wrapper that calls `strlcat()` on systems which have it, * and emulates it otherwise. Appends nul-terminated @src string to @dest, * guaranteeing nul-termination for @dest. The total size of @dest won't * exceed @dest_size. * - * At most @dest_size - 1 characters will be copied. Unlike strncat(), + * At most @dest_size - 1 characters will be copied. Unlike `strncat()`, * @dest_size is the full size of dest, not the space left over. This * function does not allocate memory. It always nul-terminates (unless * @dest_size == 0 or there were no nul characters in the @dest_size * characters of dest to start with). * - * Caveat: this is supposedly a more secure alternative to strcat() or - * strncat(), but for real security g_strconcat() is harder to mess up. + * Caveat: this is supposedly a more secure alternative to `strcat()` or + * `strncat()`, but for real security [func@GLib.strconcat] is harder to mess up. * - * Returns: size of attempted result, which is MIN (dest_size, strlen - * (original dest)) + strlen (src), so if retval >= dest_size, - * truncation occurred. + * Returns: size of attempted result, which is `MIN (dest_size, strlen + * (original dest)) + strlen (src)`, so if @retval >= @dest_size, + * truncation occurred */ gsize g_strlcat (gchar *dest, @@ -1536,14 +1537,14 @@ g_strlcat (gchar *dest, /** * g_ascii_strdown: * @str: a string - * @len: length of @str in bytes, or -1 if @str is nul-terminated + * @len: length of @str in bytes, or `-1` if @str is nul-terminated * - * Converts all upper case ASCII letters to lower case ASCII letters. + * Converts all upper case ASCII letters to lower case ASCII letters, with + * semantics that exactly match [func@GLib.ascii_tolower]. * - * Returns: a newly-allocated string, with all the upper case - * characters in @str converted to lower case, with semantics that - * exactly match g_ascii_tolower(). (Note that this is unlike the - * old g_strdown(), which modified the string in place.) + * Returns: a newly-allocated string, with all the upper case characters in + * @str converted to lower case. (Note that this is unlike the old + * [func@GLib.strdown], which modified the string in place.) */ gchar* g_ascii_strdown (const gchar *str, @@ -1566,14 +1567,14 @@ g_ascii_strdown (const gchar *str, /** * g_ascii_strup: * @str: a string - * @len: length of @str in bytes, or -1 if @str is nul-terminated + * @len: length of @str in bytes, or `-1` if @str is nul-terminated * - * Converts all lower case ASCII letters to upper case ASCII letters. + * Converts all lower case ASCII letters to upper case ASCII letters, with + * semantics that exactly match [func@GLib.ascii_toupper]. * - * Returns: a newly allocated string, with all the lower case - * characters in @str converted to upper case, with semantics that - * exactly match g_ascii_toupper(). (Note that this is unlike the - * old g_strup(), which modified the string in place.) + * Returns: a newly-allocated string, with all the lower case characters + * in @str converted to upper case. (Note that this is unlike the old + * [func@GLib.strup], which modified the string in place.) */ gchar* g_ascii_strup (const gchar *str, @@ -1600,7 +1601,7 @@ g_ascii_strup (const gchar *str, * Determines if a string is pure ASCII. A string is pure ASCII if it * contains no bytes with the high bit set. * - * Returns: %TRUE if @str is ASCII + * Returns: true if @str is ASCII * * Since: 2.40 */ @@ -1618,15 +1619,15 @@ g_str_is_ascii (const gchar *str) /** * g_strdown: - * @string: the string to convert. + * @string: the string to convert * * Converts a string to lower case. * * Returns: the string * - * Deprecated:2.2: This function is totally broken for the reasons discussed - * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() - * instead. + * Deprecated: 2.2: This function is totally broken for the reasons discussed + * in the [func@GLib.strncasecmp] docs — use [func@GLib.ascii_strdown] or + * [func@GLib.utf8_strdown] instead. **/ gchar* g_strdown (gchar *string) @@ -1655,9 +1656,9 @@ g_strdown (gchar *string) * * Returns: the string * - * Deprecated:2.2: This function is totally broken for the reasons - * discussed in the g_strncasecmp() docs - use g_ascii_strup() - * or g_utf8_strup() instead. + * Deprecated: 2.2: This function is totally broken for the reasons discussed + * in the [func@GLib.strncasecmp] docs — use [func@GLib.ascii_strup] or + * [func@GLib.utf8_strup] instead. */ gchar* g_strup (gchar *string) @@ -1685,11 +1686,11 @@ g_strup (gchar *string) * Reverses all of the bytes in a string. For example, * `g_strreverse ("abcdef")` will result in "fedcba". * - * Note that g_strreverse() doesn't work on UTF-8 strings + * Note that `g_strreverse()` doesn't work on UTF-8 strings * containing multibyte characters. For that purpose, use - * g_utf8_strreverse(). + * [func@GLib.utf8_strreverse]. * - * Returns: the same pointer passed in as @string + * Returns: the @string, reversed in place */ gchar* g_strreverse (gchar *string) @@ -1722,18 +1723,18 @@ g_strreverse (gchar *string) * g_ascii_tolower: * @c: any character * - * Convert a character to ASCII lower case. + * Convert a character to ASCII lower case. If the character is not an + * ASCII upper case letter, it is returned unchanged. * - * Unlike the standard C library tolower() function, this only + * Unlike the standard C library `tolower()` function, this only * recognizes standard ASCII letters and ignores the locale, returning * all non-ASCII characters unchanged, even if they are lower case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so - * don't call it on %EOF but no need to worry about casting to #guchar + * don't call it on `EOF` but no need to worry about casting to `guchar` * before passing a possibly non-ASCII character in. * - * Returns: the result of converting @c to lower case. If @c is - * not an ASCII upper case letter, @c is returned unchanged. + * Returns: the result of the conversion */ gchar g_ascii_tolower (gchar c) @@ -1745,18 +1746,18 @@ g_ascii_tolower (gchar c) * g_ascii_toupper: * @c: any character * - * Convert a character to ASCII upper case. + * Convert a character to ASCII upper case. If the character is not an + * ASCII lower case letter, it is returned unchanged. * - * Unlike the standard C library toupper() function, this only + * Unlike the standard C library `toupper()` function, this only * recognizes standard ASCII letters and ignores the locale, returning * all non-ASCII characters unchanged, even if they are upper case * letters in a particular character set. Also unlike the standard * library function, this takes and returns a char, not an int, so - * don't call it on %EOF but no need to worry about casting to #guchar + * don't call it on `EOF` but no need to worry about casting to `guchar` * before passing a possibly non-ASCII character in. * - * Returns: the result of converting @c to upper case. If @c is not - * an ASCII lower case letter, @c is returned unchanged. + * Returns: the result of the conversion */ gchar g_ascii_toupper (gchar c) @@ -1768,12 +1769,14 @@ g_ascii_toupper (gchar c) * g_ascii_digit_value: * @c: an ASCII character * - * Determines the numeric value of a character as a decimal digit. - * Differs from g_unichar_digit_value() because it takes a char, so + * Determines the numeric value of a character as a decimal digit. If the + * character is not a decimal digit according to [func@GLib.ascii_isdigit], + * `-1` is returned. + * + * Differs from [func@GLib.unichar_digit_value] because it takes a char, so * there's no worry about sign extension if characters are signed. * - * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), - * its numeric value. Otherwise, -1. + * Returns: the numerical value of @c if it is a decimal digit, `-1` otherwise */ int g_ascii_digit_value (gchar c) @@ -1785,15 +1788,19 @@ g_ascii_digit_value (gchar c) /** * g_ascii_xdigit_value: - * @c: an ASCII character. + * @c: an ASCII character * - * Determines the numeric value of a character as a hexadecimal - * digit. Differs from g_unichar_xdigit_value() because it takes - * a char, so there's no worry about sign extension if characters - * are signed. + * Determines the numeric value of a character as a hexadecimal digit. If the + * character is not a hex digit according to [func@GLib.ascii_isxdigit], + * `-1` is returned. * - * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), - * its numeric value. Otherwise, -1. + * Differs from [func@GLib.unichar_xdigit_value] because it takes a char, so + * there's no worry about sign extension if characters are signed. + * + * Differs from [func@GLib.unichar_xdigit_value] because it takes a char, so + * there's no worry about sign extension if characters are signed. + * + * Returns: the numerical value of @c if it is a hex digit, `-1` otherwise */ int g_ascii_xdigit_value (gchar c) @@ -1812,7 +1819,7 @@ g_ascii_xdigit_value (gchar c) * * Compare two strings, ignoring the case of ASCII characters. * - * Unlike the BSD strcasecmp() function, this only recognizes standard + * Unlike the BSD `strcasecmp()` function, this only recognizes standard * ASCII letters and ignores the locale, treating all non-ASCII * bytes as if they are not letters. * @@ -1824,10 +1831,10 @@ g_ascii_xdigit_value (gchar c) * characters include all ASCII letters. If you compare two CP932 * strings using this function, you will get false matches. * - * Both @s1 and @s2 must be non-%NULL. + * Both @s1 and @s2 must be non-`NULL`. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. + * or a positive value if @s1 > @s2 */ gint g_ascii_strcasecmp (const gchar *s1, @@ -1861,16 +1868,16 @@ g_ascii_strcasecmp (const gchar *s1, * less than @n bytes long, comparison will stop at the first nul byte * encountered. * - * Unlike the BSD strcasecmp() function, this only recognizes standard + * Unlike the BSD `strncasecmp()` function, this only recognizes standard * ASCII letters and ignores the locale, treating all non-ASCII * characters as if they are not letters. * - * The same warning as in g_ascii_strcasecmp() applies: Use this + * The same warning as in [func@GLib.ascii_strcasecmp] applies: Use this * function only on strings known to be in encodings where bytes * corresponding to ASCII letters always represent themselves. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. + * or a positive value if @s1 > @s2 */ gint g_ascii_strncasecmp (const gchar *s1, @@ -1900,17 +1907,17 @@ g_ascii_strncasecmp (const gchar *s1, /** * g_strcasecmp: - * @s1: a string - * @s2: a string to compare with @s1 + * @s1: string to compare with @s2 + * @s2: string to compare with @s1 * * A case-insensitive string comparison, corresponding to the standard - * strcasecmp() function on platforms which support it. + * `strcasecmp()` function on platforms which support it. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. + * or a positive value if @s1 > @s2 * - * Deprecated:2.2: See g_strncasecmp() for a discussion of why this - * function is deprecated and how to replace it. + * Deprecated: 2.2: See [func@GLib.strncasecmp] for a discussion of why this + * function is deprecated and how to replace it. */ gint g_strcasecmp (const gchar *s1, @@ -1945,32 +1952,32 @@ g_strcasecmp (const gchar *s1, /** * g_strncasecmp: - * @s1: a string - * @s2: a string to compare with @s1 + * @s1: string to compare with @s2 + * @s2: string to compare with @s1 * @n: the maximum number of characters to compare * * A case-insensitive string comparison, corresponding to the standard - * strncasecmp() function on platforms which support it. It is similar - * to g_strcasecmp() except it only compares the first @n characters of + * `strncasecmp()` function on platforms which support it. It is similar + * to [func@GLib.strcasecmp] except it only compares the first @n characters of * the strings. * * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. + * or a positive value if @s1 > @s2 * - * Deprecated:2.2: The problem with g_strncasecmp() is that it does - * the comparison by calling toupper()/tolower(). These functions - * are locale-specific and operate on single bytes. However, it is - * impossible to handle things correctly from an internationalization - * standpoint by operating on bytes, since characters may be multibyte. - * Thus g_strncasecmp() is broken if your string is guaranteed to be - * ASCII, since it is locale-sensitive, and it's broken if your string - * is localized, since it doesn't work on many encodings at all, - * including UTF-8, EUC-JP, etc. + * Deprecated: 2.2: The problem with `g_strncasecmp()` is that it does + * the comparison by calling `toupper()`/`tolower()`. These functions + * are locale-specific and operate on single bytes. However, it is + * impossible to handle things correctly from an internationalization + * standpoint by operating on bytes, since characters may be multibyte. + * Thus `g_strncasecmp()` is broken if your string is guaranteed to be + * ASCII, since it is locale-sensitive, and it's broken if your string + * is localized, since it doesn't work on many encodings at all, + * including UTF-8, EUC-JP, etc. * - * There are therefore two replacement techniques: g_ascii_strncasecmp(), - * which only works on ASCII and is not locale-sensitive, and - * g_utf8_casefold() followed by strcmp() on the resulting strings, - * which is good for case-insensitive sorting of UTF-8. + * There are therefore two replacement techniques: [func@GLib.ascii_strncasecmp], + * which only works on ASCII and is not locale-sensitive, and + * [func@GLib.utf8_casefold] followed by `strcmp()` on the resulting strings, + * which is good for case-insensitive sorting of UTF-8. */ gint g_strncasecmp (const gchar *s1, @@ -2008,8 +2015,8 @@ g_strncasecmp (const gchar *s1, /** * g_strdelimit: * @string: the string to convert - * @delimiters: (nullable): a string containing the current delimiters, - * or %NULL to use the standard delimiters defined in %G_STR_DELIMITERS + * @delimiters: (nullable): a string containing the current delimiters, or + * `NULL` to use the standard delimiters defined in [const@GLib.STR_DELIMITERS] * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. @@ -2019,18 +2026,16 @@ g_strncasecmp (const gchar *s1, * and returns @string itself, not a copy. * * The return value is to allow nesting such as: + * ```C + * g_ascii_strup (g_strdelimit (str, "abc", '?')) + * ``` * - * |[ - * g_ascii_strup (g_strdelimit (str, "abc", '?')) - * ]| - * - * In order to modify a copy, you may use g_strdup(): - * - * |[ - * reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); - * ... - * g_free (reformatted); - * ]| + * In order to modify a copy, you may use [func@GLib.strdup]: + * ```C + * reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); + * … + * g_free (reformatted); + * ``` * * Returns: the modified @string */ @@ -2066,18 +2071,16 @@ g_strdelimit (gchar *string, * * Modifies @string in place, and return @string itself, not a copy. The * return value is to allow nesting such as: + * ```C + * g_ascii_strup (g_strcanon (str, "abc", '?')) + * ``` * - * |[ - * g_ascii_strup (g_strcanon (str, "abc", '?')) - * ]| - * - * In order to modify a copy, you may use g_strdup(): - * - * |[ - * reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); - * ... - * g_free (reformatted); - * ]| + * In order to modify a copy, you may use [func@GLib.strdup]: + * ```C + * reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); + * … + * g_free (reformatted); + * ``` * * Returns: the modified @string */ @@ -2106,10 +2109,10 @@ g_strcanon (gchar *string, * * Replaces all escaped characters with their one byte equivalent. * - * This function does the reverse conversion of g_strescape(). + * This function does the reverse conversion of [func@GLib.strescape]. * * Returns: a newly-allocated copy of @source with all escaped - * character compressed + * character compressed */ gchar * g_strcompress (const gchar *source) @@ -2190,10 +2193,9 @@ out: * replaced with a '\' followed by their octal representation. * Characters supplied in @exceptions are not escaped. * - * g_strcompress() does the reverse conversion. + * [func@GLib.strcompress] does the reverse conversion. * - * Returns: a newly-allocated copy of @source with certain - * characters escaped. See above. + * Returns: a newly-allocated copy of @source with special characters escaped */ gchar * g_strescape (const gchar *source, @@ -2294,9 +2296,9 @@ g_strescape (const gchar *source, * * The pointer to @string is returned to allow the nesting of functions. * - * Also see g_strchomp() and g_strstrip(). + * Also see [func@GLib.strchomp] and [func@GLib.strstrip]. * - * Returns: @string + * Returns: the modified @string */ gchar * g_strchug (gchar *string) @@ -2325,9 +2327,9 @@ g_strchug (gchar *string) * * The pointer to @string is returned to allow the nesting of functions. * - * Also see g_strchug() and g_strstrip(). + * Also see [func@GLib.strchug] and [func@GLib.strstrip]. * - * Returns: @string + * Returns: the modified @string */ gchar * g_strchomp (gchar *string) @@ -2352,28 +2354,27 @@ g_strchomp (gchar *string) * g_strsplit: * @string: a string to split * @delimiter: a string which specifies the places at which to split - * the string. The delimiter is not included in any of the resulting - * strings, unless @max_tokens is reached. - * @max_tokens: the maximum number of pieces to split @string into. - * If this is less than 1, the string is split completely. + * the string. The delimiter is not included in any of the resulting + * strings, unless @max_tokens is reached. + * @max_tokens: the maximum number of pieces to split @string into + * If this is less than 1, the string is split completely * * Splits a string into a maximum of @max_tokens pieces, using the given * @delimiter. If @max_tokens is reached, the remainder of @string is * appended to the last token. * - * As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a - * %NULL-terminated vector containing the six strings "", "a", "bc", "", "d" - * and "". + * As an example, the result of `g_strsplit (":a:bc::d:", ":", -1)` is an array + * containing the six strings "", "a", "bc", "", "d" and "". * * As a special case, the result of splitting the empty string "" is an empty - * vector, not a vector containing a single string. The reason for this - * special case is that being able to represent an empty vector is typically + * array, not an array containing a single string. The reason for this + * special case is that being able to represent an empty array is typically * more useful than consistent handling of empty elements. If you do need * to represent empty elements, you'll need to check for the empty string - * before calling g_strsplit(). + * before calling `g_strsplit()`. * - * Returns: (transfer full): a newly-allocated %NULL-terminated array of - * strings. Use g_strfreev() to free it. + * Returns: (transfer full): a newly-allocated array of strings, freed with + * [func@GLib.strfreev] */ gchar** g_strsplit (const gchar *string, @@ -2424,37 +2425,35 @@ g_strsplit (const gchar *string, /** * g_strsplit_set: - * @string: The string to be tokenized - * @delimiters: A nul-terminated string containing bytes that are used - * to split the string (it can accept an empty string, which will result - * in no string splitting). - * @max_tokens: The maximum number of tokens to split @string into. - * If this is less than 1, the string is split completely + * @string: a string to split + * @delimiters: a string containing characters that are used to split the + * string. Can be empty, which will result in no string splitting + * @max_tokens: the maximum number of tokens to split @string into. + * If this is less than 1, the string is split completely * * Splits @string into a number of tokens not containing any of the characters - * in @delimiter. A token is the (possibly empty) longest string that does not + * in @delimiters. A token is the (possibly empty) longest string that does not * contain any of the characters in @delimiters. If @max_tokens is reached, the * remainder is appended to the last token. * - * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a - * %NULL-terminated vector containing the three strings "abc", "def", - * and "ghi". + * For example, the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is an + * array containing the three strings "abc", "def", and "ghi". * - * The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated - * vector containing the four strings "", "def", "ghi", and "". + * The result of g_strsplit_set (":def/ghi:", ":/", -1) is an array containing + * the four strings "", "def", "ghi", and "". * * As a special case, the result of splitting the empty string "" is an empty - * vector, not a vector containing a single string. The reason for this - * special case is that being able to represent an empty vector is typically + * array, not an array containing a single string. The reason for this + * special case is that being able to represent an empty array is typically * more useful than consistent handling of empty elements. If you do need * to represent empty elements, you'll need to check for the empty string - * before calling g_strsplit_set(). + * before calling `g_strsplit_set()`. * * Note that this function works on bytes not characters, so it can't be used * to delimit UTF-8 strings for anything but ASCII characters. * - * Returns: (transfer full): a newly-allocated %NULL-terminated array of - * strings. Use g_strfreev() to free it. + * Returns: (transfer full): a newly-allocated array of strings. Use + * [func@GLib.strfreev] to free it. * * Since: 2.4 **/ @@ -2528,17 +2527,17 @@ g_strsplit_set (const gchar *string, * GStrv: * * A typedef alias for gchar**. This is mostly useful when used together with - * g_auto(). + * `g_auto()`. */ /** * g_strfreev: - * @str_array: (array zero-terminated=1) (nullable) (transfer full): a %NULL-terminated array of strings to free + * @str_array: (array zero-terminated=1) (nullable) (transfer full): an + * array of strings to free * - * Frees a %NULL-terminated array of strings, as well as each - * string it contains. + * Frees an array of strings, as well as each string it contains. * - * If @str_array is %NULL, this function simply returns. + * If @str_array is `NULL`, this function simply returns. */ void g_strfreev (gchar **str_array) @@ -2556,14 +2555,15 @@ g_strfreev (gchar **str_array) /** * g_strdupv: - * @str_array: (array zero-terminated=1) (nullable): a %NULL-terminated array of strings + * @str_array: (array zero-terminated=1) (nullable): an array of strings to copy * - * Copies %NULL-terminated array of strings. The copy is a deep copy; - * the new array should be freed by first freeing each string, then - * the array itself. g_strfreev() does this for you. If called - * on a %NULL value, g_strdupv() simply returns %NULL. + * Copies an array of strings. The copy is a deep copy; each string is also + * copied. * - * Returns: (array zero-terminated=1) (nullable) (transfer full): a new %NULL-terminated array of strings. + * If called on a `NULL` value, `g_strdupv()` simply returns `NULL`. + * + * Returns: (array zero-terminated=1) (nullable) (transfer full): a + * newly-allocated array of strings. Use [func@GLib.strfreev] to free it. */ gchar** g_strdupv (gchar **str_array) @@ -2595,20 +2595,18 @@ g_strdupv (gchar **str_array) /** * g_strjoinv: - * @separator: (nullable): a string to insert between each of the - * strings, or %NULL - * @str_array: (array zero-terminated=1): a %NULL-terminated array of strings to join + * @separator: (nullable): a string to insert between each of the strings + * @str_array: (array zero-terminated=1): an array of strings to join * - * Joins a number of strings together to form one long string, with the - * optional @separator inserted between each of them. The returned string - * should be freed with g_free(). + * Joins an array of strings together to form one long string, with the + * optional @separator inserted between each of them. * * If @str_array has no items, the return value will be an * empty string. If @str_array contains a single item, @separator will not * appear in the resulting string. * * Returns: a newly-allocated string containing all of the strings joined - * together, with @separator between them + * together, with @separator between them */ gchar* g_strjoinv (const gchar *separator, @@ -2652,16 +2650,14 @@ g_strjoinv (const gchar *separator, /** * g_strjoin: - * @separator: (nullable): a string to insert between each of the - * strings, or %NULL - * @...: a %NULL-terminated list of strings to join + * @separator: (nullable): a string to insert between each of the strings + * @...: a `NULL`-terminated list of strings to join * * Joins a number of strings together to form one long string, with the - * optional @separator inserted between each of them. The returned string - * should be freed with g_free(). + * optional @separator inserted between each of them. * * Returns: a newly-allocated string containing all of the strings joined - * together, with @separator between them + * together, with @separator between them */ gchar* g_strjoin (const gchar *separator, @@ -2722,17 +2718,19 @@ g_strjoin (const gchar *separator, /** * g_strstr_len: - * @haystack: a nul-terminated string - * @haystack_len: the maximum length of @haystack in bytes. A length of -1 - * can be used to mean "search the entire string", like `strstr()`. + * @haystack: a string to search in + * @haystack_len: the maximum length of @haystack in bytes, or `-1` to + * search it entirely * @needle: the string to search for * * Searches the string @haystack for the first occurrence * of the string @needle, limiting the length of the search * to @haystack_len or a nul terminator byte (whichever is reached first). * - * Returns: a pointer to the found occurrence, or - * %NULL if not found. + * A length of `-1` can be used to mean “search the entire string”, like + * `strstr()`. + * + * Returns: a pointer to the found occurrence, or `NULL` if not found */ gchar * g_strstr_len (const gchar *haystack, @@ -2778,14 +2776,13 @@ g_strstr_len (const gchar *haystack, /** * g_strrstr: - * @haystack: a nul-terminated string - * @needle: the nul-terminated string to search for + * @haystack: a string to search in + * @needle: the string to search for * * Searches the string @haystack for the last occurrence * of the string @needle. * - * Returns: a pointer to the found occurrence, or - * %NULL if not found. + * Returns: a pointer to the found occurrence, or `NULL` if not found */ gchar * g_strrstr (const gchar *haystack, @@ -2827,17 +2824,16 @@ g_strrstr (const gchar *haystack, /** * g_strrstr_len: - * @haystack: a nul-terminated string - * @haystack_len: the maximum length of @haystack in bytes. A length of -1 - * can be used to mean "search the entire string", like g_strrstr(). - * @needle: the nul-terminated string to search for + * @haystack: a string to search in + * @haystack_len: the maximum length of @haystack in bytes. A length of `-1` + * can be used to mean "search the entire string", like [func@GLib.strrstr] + * @needle: the string to search for * * Searches the string @haystack for the last occurrence * of the string @needle, limiting the length of the search * to @haystack_len. * - * Returns: a pointer to the found occurrence, or - * %NULL if not found. + * Returns: a pointer to the found occurrence, or `NULL` if not found */ gchar * g_strrstr_len (const gchar *haystack, @@ -2883,12 +2879,12 @@ g_strrstr_len (const gchar *haystack, /** * g_str_has_suffix: - * @str: a nul-terminated string - * @suffix: the nul-terminated suffix to look for + * @str: a string to look in + * @suffix: the suffix to look for * - * Looks whether the string @str ends with @suffix. + * Looks whether a string ends with @suffix. * - * Returns: %TRUE if @str end with @suffix, %FALSE otherwise. + * Returns: true if @str ends with @suffix, false otherwise * * Since: 2.2 */ @@ -2912,12 +2908,12 @@ gboolean (g_str_has_suffix) (const gchar *str, /** * g_str_has_prefix: - * @str: a nul-terminated string - * @prefix: the nul-terminated prefix to look for + * @str: a string to look in + * @prefix: the prefix to look for * * Looks whether the string @str begins with @prefix. * - * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise. + * Returns: true if @str begins with @prefix, false otherwise * * Since: 2.2 */ @@ -2932,12 +2928,11 @@ gboolean (g_str_has_prefix) (const gchar *str, /** * g_strv_length: - * @str_array: (array zero-terminated=1): a %NULL-terminated array of strings + * @str_array: (array zero-terminated=1): an array of strings * - * Returns the length of the given %NULL-terminated - * string array @str_array. @str_array must not be %NULL. + * Returns the length of an array of strings. @str_array must not be `NULL`. * - * Returns: length of @str_array. + * Returns: length of @str_array * * Since: 2.6 */ @@ -3041,21 +3036,21 @@ split_words (const gchar *value) /** * g_str_tokenize_and_fold: - * @string: a string + * @string: a string to tokenize * @translit_locale: (nullable): the language code (like 'de' or * 'en_GB') from which @string originates - * @ascii_alternates: (out) (optional) (transfer full) (array zero-terminated=1): a - * return location for ASCII alternates + * @ascii_alternates: (out) (optional) (transfer full) (array zero-terminated=1): + * a return location for ASCII alternates * - * Tokenises @string and performs folding on each token. + * Tokenizes @string and performs folding on each token. * * A token is a non-empty sequence of alphanumeric characters in the * source string, separated by non-alphanumeric characters. An * "alphanumeric" character for this purpose is one that matches - * g_unichar_isalnum() or g_unichar_ismark(). + * [func@GLib.unichar_isalnum] or [func@GLib.unichar_ismark]. * * Each token is then (Unicode) normalised and case-folded. If - * @ascii_alternates is non-%NULL and some of the returned tokens + * @ascii_alternates is non-`NULL` and some of the returned tokens * contain non-ASCII characters, ASCII alternatives will be generated. * * The number of ASCII alternatives that are generated and the method @@ -3129,13 +3124,13 @@ g_str_tokenize_and_fold (const gchar *string, * g_str_match_string: * @search_term: the search term from the user * @potential_hit: the text that may be a hit - * @accept_alternates: %TRUE to accept ASCII alternates + * @accept_alternates: if true, ASCII alternates are accepted * * Checks if a search conducted for @search_term should match * @potential_hit. * - * This function calls g_str_tokenize_and_fold() on both - * @search_term and @potential_hit. ASCII alternates are never taken + * This function calls [func@GLib.str_tokenize_and_fold] on both + * @search_term and @potential_hit. ASCII alternates are never taken * for @search_term but will be taken for @potential_hit according to * the value of @accept_alternates. * @@ -3143,9 +3138,9 @@ g_str_tokenize_and_fold (const gchar *string, * folded token from @potential_hit. * * Depending on how you're performing the search, it will typically be - * faster to call g_str_tokenize_and_fold() on each string in + * faster to call `g_str_tokenize_and_fold()` on each string in * your corpus and build an index on the returned folded tokens, then - * call g_str_tokenize_and_fold() on the search term and + * call `g_str_tokenize_and_fold()` on the search term and * perform lookups into that index. * * As some examples, searching for ‘fred’ would match the potential hit @@ -3154,7 +3149,7 @@ g_str_tokenize_and_fold (const gchar *string, * accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo * Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). * - * Returns: %TRUE if @potential_hit is a hit + * Returns: true if @potential_hit is a hit * * Since: 2.40 **/ @@ -3204,12 +3199,13 @@ one_matched: /** * g_strv_contains: - * @strv: (array zero-terminated=1): a %NULL-terminated array of strings - * @str: a string + * @strv: (array zero-terminated=1): an array of strings to search in + * @str: the string to search for * - * Checks if @strv contains @str. @strv must not be %NULL. + * Checks if an array of strings contains the string @str according to + * [func@GLib.str_equal]. @strv must not be `NULL`. * - * Returns: %TRUE if @str is an element of @strv, according to g_str_equal(). + * Returns: true if @str is an element of @strv * * Since: 2.44 */ @@ -3231,17 +3227,24 @@ g_strv_contains (const gchar * const *strv, /** * g_strv_equal: - * @strv1: (array zero-terminated=1): a %NULL-terminated array of strings - * @strv2: (array zero-terminated=1): another %NULL-terminated array of strings + * @strv1: (array zero-terminated=1): an array of strings to compare to @strv2 + * @strv2: (array zero-terminated=1): an array of strings to compare to @strv1 * - * Checks if @strv1 and @strv2 contain exactly the same elements in exactly the - * same order. Elements are compared using g_str_equal(). To match independently - * of order, sort the arrays first (using g_qsort_with_data() or similar). + * Checks if two arrays of strings contain exactly the same elements in + * exactly the same order. * - * Two empty arrays are considered equal. Neither @strv1 not @strv2 may be - * %NULL. + * Elements are compared using [func@GLib.str_equal]. To match independently + * of order, sort the arrays first (using [func@GLib.qsort_with_data] + * or similar). * - * Returns: %TRUE if @strv1 and @strv2 are equal + * Elements are compared using [func@GLib.str_equal]. To match independently + * of order, sort the arrays first (using [func@GLib.qsort_with_data] + * or similar). + * + * Two empty arrays are considered equal. Neither @strv1 nor @strv2 may be + * `NULL`. + * + * Returns: true if @strv1 and @strv2 are equal * Since: 2.60 */ gboolean @@ -3277,7 +3280,7 @@ str_has_hex_prefix (const gchar *str) /** * g_ascii_string_to_signed: - * @str: a string + * @str: a string to convert * @base: base of a parsed number * @min: a lower bound (inclusive) * @max: an upper bound (inclusive) @@ -3297,16 +3300,16 @@ str_has_hex_prefix (const gchar *str) * for octal numbers, since they were usually prefixed with a zero * which does not change the value of the parsed number. * - * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR + * Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` * domain. If the input is invalid, the error code will be - * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of - * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. + * [error@GLib.NumberParserError.INVALID]. If the parsed number is out of + * bounds - [error@GLib.NumberParserError.OUT_OF_BOUNDS]. * - * See g_ascii_strtoll() if you have more complex needs such as + * See [func@GLib.ascii_strtoll] if you have more complex needs such as * parsing a string which starts with a number, but then has other * characters. * - * Returns: %TRUE if @str was a number, otherwise %FALSE. + * Returns: true if @str was a number, false otherwise * * Since: 2.54 */ @@ -3399,16 +3402,16 @@ g_ascii_string_to_signed (const gchar *str, * for octal numbers, since they were usually prefixed with a zero * which does not change the value of the parsed number. * - * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR + * Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` * domain. If the input is invalid, the error code will be - * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of - * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. + * [error@GLib.NumberParserError.INVALID]. If the parsed number is out of + * bounds - [error@GLib.NumberParserError.OUT_OF_BOUNDS]. * - * See g_ascii_strtoull() if you have more complex needs such as + * See [func@GLib.ascii_strtoull] if you have more complex needs such as * parsing a string which starts with a number, but then has other * characters. * - * Returns: %TRUE if @str was a number, otherwise %FALSE. + * Returns: true if @str was a number, false otherwise * * Since: 2.54 */ diff --git a/glib/gstrfuncs.h b/glib/gstrfuncs.h index cb021b658..cfd6631b0 100644 --- a/glib/gstrfuncs.h +++ b/glib/gstrfuncs.h @@ -412,8 +412,8 @@ gboolean g_strv_equal (const gchar * const *strv1, /** * GNumberParserError: - * @G_NUMBER_PARSER_ERROR_INVALID: String was not a valid number. - * @G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS: String was a number, but out of bounds. + * @G_NUMBER_PARSER_ERROR_INVALID: string was not a valid number + * @G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS: string was a number, but out of bounds * * Error codes returned by functions converting a string to a number. *