diff --git a/glib/gutf8.c b/glib/gutf8.c index dd9966df5..d26a63094 100644 --- a/glib/gutf8.c +++ b/glib/gutf8.c @@ -131,14 +131,14 @@ const gchar * const g_utf8_skip = utf8_skip_data; * @p: pointer to some position within @str * * Given a position @p with a UTF-8 encoded string @str, find the start - * of the previous UTF-8 character starting before @p. Returns %NULL if no + * of the previous UTF-8 character starting before @p. Returns `NULL` if no * UTF-8 characters are present in @str before @p. * * @p does not have to be at the beginning of a UTF-8 character. No check * is made to see if the character found is actually valid other than * it starts with an appropriate byte. * - * Returns: (transfer none) (nullable): a pointer to the found character or %NULL. + * Returns: (transfer none) (nullable): a pointer to the found character */ gchar * g_utf8_find_prev_char (const gchar *str, @@ -157,7 +157,7 @@ g_utf8_find_prev_char (const gchar *str, * g_utf8_find_next_char: * @p: a pointer to a position within a UTF-8 encoded string * @end: (nullable): a pointer to the byte following the end of the string, - * or %NULL to indicate that the string is nul-terminated + * or `NULL` to indicate that the string is nul-terminated * * Finds the start of the next UTF-8 character in the string after @p. * @@ -165,12 +165,12 @@ g_utf8_find_prev_char (const gchar *str, * is made to see if the character found is actually valid other than * it starts with an appropriate byte. * - * If @end is %NULL, the return value will never be %NULL: if the end of the + * If @end is `NULL`, the return value will never be `NULL`: if the end of the * string is reached, a pointer to the terminating nul byte is returned. If - * @end is non-%NULL, the return value will be %NULL if the end of the string + * @end is non-`NULL`, the return value will be `NULL` if the end of the string * is reached. * - * Returns: (transfer none) (nullable): a pointer to the found character or %NULL if @end is + * Returns: (transfer none) (nullable): a pointer to the found character or `NULL` if @end is * set and is reached */ gchar * @@ -200,7 +200,8 @@ g_utf8_find_next_char (const gchar *p, * @p does not have to be at the beginning of a UTF-8 character. No check * is made to see if the character found is actually valid other than * it starts with an appropriate byte. If @p might be the first - * character of the string, you must use g_utf8_find_prev_char() instead. + * character of the string, you must use [func@GLib.utf8_find_prev_char] + * instead. * * Returns: (transfer none) (not nullable): a pointer to the found character */ @@ -219,13 +220,13 @@ g_utf8_prev_char (const gchar *p) * g_utf8_strlen: * @p: pointer to the start of a UTF-8 encoded string * @max: the maximum number of bytes to examine. If @max - * is less than 0, then the string is assumed to be - * nul-terminated. If @max is 0, @p will not be examined and - * may be %NULL. If @max is greater than 0, up to @max - * bytes are examined + * is less than 0, then the string is assumed to be + * nul-terminated. If @max is 0, @p will not be examined and + * may be `NULL`. If @max is greater than 0, up to @max + * bytes are examined * * Computes the length of the string in characters, not including - * the terminating nul character. If the @max'th byte falls in the + * the terminating nul character. If the @max’th byte falls in the * middle of a character, the last (partial) character is not counted. * * Returns: the length of the string in characters @@ -283,7 +284,7 @@ g_utf8_strlen (const gchar *p, * end of the string. * * Returns: (transfer full): a newly allocated copy of the requested - * substring. Free with g_free() when no longer needed. + * substring. Free with [func@GLib.free] when no longer needed. * * Since: 2.30 */ @@ -323,7 +324,7 @@ g_utf8_substring (const gchar *str, * * If @p does not point to a valid UTF-8 encoded character, results * are undefined. If you are not sure that the bytes are complete - * valid Unicode characters, you should use g_utf8_get_char_validated() + * valid Unicode characters, you should use [func@GLib.utf8_get_char_validated] * instead. * * Returns: the resulting character @@ -356,9 +357,9 @@ g_utf8_get_char (const gchar *p) * instead of forwards if @offset is in the last fourth of the string, * since moving forward is about 3 times faster than moving backward. * - * Note that this function doesn't abort when reaching the end of @str. + * Note that this function doesn’t abort when reaching the end of @str. * Therefore you should be sure that @offset is within string boundaries - * before calling that function. Call g_utf8_strlen() when unsure. + * before calling that function. Call [func@GLib.utf8_strlen] when unsure. * This limitation exists as this function is called frequently during * text rendering and therefore has to be as fast as possible. * @@ -434,10 +435,12 @@ g_utf8_pointer_to_offset (const gchar *str, * @src: UTF-8 encoded string * @n: character count * - * Like the standard C strncpy() function, but copies a given number - * of characters instead of a given number of bytes. The @src string - * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all - * text before trying to use UTF-8 utility functions with it.) + * Like the standard C [`strncpy()`](man:strncpy) function, but copies a given + * number of characters instead of a given number of bytes. + * + * The @src string must be valid UTF-8 encoded text. (Use + * [func@GLib.utf8_validate] on all text before trying to use UTF-8 utility + * functions with it.) * * Note you must ensure @dest is at least 4 * @n + 1 to fit the * largest possible UTF-8 characters @@ -532,8 +535,8 @@ g_utf8_truncate_middle (const gchar *string, * g_unichar_to_utf8: * @c: a Unicode character code * @outbuf: (out caller-allocates) (optional): output buffer, must have at - * least 6 bytes of space. If %NULL, the length will be computed and - * returned and nothing will be written to @outbuf. + * least 6 bytes of space. If `NULL`, the length will be computed and + * returned and nothing will be written to @outbuf. * * Converts a single character to UTF-8. * @@ -600,11 +603,12 @@ g_unichar_to_utf8 (gunichar c, * * Finds the leftmost occurrence of the given Unicode character * in a UTF-8 encoded string, while limiting the search to @len bytes. - * If @len is -1, allow unbounded search. * - * Returns: (transfer none) (nullable): %NULL if the string does not contain the character, - * otherwise, a pointer to the start of the leftmost occurrence - * of the character in the string. + * If @len is `-1`, allow unbounded search. + * + * Returns: (transfer none) (nullable): `NULL` if the string does not contain + * the character, otherwise, a pointer to the start of the leftmost occurrence + * of the character in the string. */ gchar * g_utf8_strchr (const char *p, @@ -628,11 +632,12 @@ g_utf8_strchr (const char *p, * * Find the rightmost occurrence of the given Unicode character * in a UTF-8 encoded string, while limiting the search to @len bytes. - * If @len is -1, allow unbounded search. * - * Returns: (transfer none) (nullable): %NULL if the string does not contain the character, - * otherwise, a pointer to the start of the rightmost occurrence - * of the character in the string. + * If @len is `-1`, allow unbounded search. + * + * Returns: (transfer none) (nullable): `NULL` if the string does not contain + * the character, otherwise, a pointer to the start of the rightmost + * occurrence of the character in the string. */ gchar * g_utf8_strrchr (const char *p, @@ -741,22 +746,23 @@ g_utf8_get_char_extended (const gchar *p, /** * g_utf8_get_char_validated: * @p: a pointer to Unicode character encoded as UTF-8 - * @max_len: the maximum number of bytes to read, or -1 if @p is nul-terminated + * @max_len: the maximum number of bytes to read, or `-1` if @p is nul-terminated * * Convert a sequence of bytes encoded as UTF-8 to a Unicode character. + * * This function checks for incomplete characters, for invalid characters * such as characters that are out of the range of Unicode, and for * overlong encodings of valid characters. * - * Note that g_utf8_get_char_validated() returns (gunichar)-2 if + * Note that [func@GLib.utf8_get_char_validated] returns `(gunichar)-2` if * @max_len is positive and any of the bytes in the first UTF-8 character * sequence are nul. * * Returns: the resulting character. If @p points to a partial - * sequence at the end of a string that could begin a valid - * character (or if @max_len is zero), returns (gunichar)-2; - * otherwise, if @p does not point to a valid UTF-8 encoded - * Unicode character, returns (gunichar)-1. + * sequence at the end of a string that could begin a valid + * character (or if @max_len is zero), returns `(gunichar)-2`; + * otherwise, if @p does not point to a valid UTF-8 encoded + * Unicode character, returns `(gunichar)-1`. */ gunichar g_utf8_get_char_validated (const gchar *p, @@ -787,19 +793,20 @@ g_utf8_get_char_validated (const gchar *p, /** * g_utf8_to_ucs4_fast: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. + * @len: the maximum length of @str to use, in bytes. If @len is negative, + * then the string is nul-terminated. * @items_written: (out) (optional): location to store the - * number of characters in the result, or %NULL. + * number of characters in the result, or `NULL`. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4, assuming valid UTF-8 input. - * This function is roughly twice as fast as g_utf8_to_ucs4() - * but does no error checking on the input. A trailing 0 character + * + * This function is roughly twice as fast as [func@GLib.utf8_to_ucs4] + * but does no error checking on the input. A trailing nul character (U+0000) * will be added to the string after the converted text. * * Returns: (transfer full): a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). + * This value must be freed with [func@GLib.free]. */ gunichar * g_utf8_to_ucs4_fast (const gchar *str, @@ -904,28 +911,28 @@ try_malloc_n (gsize n_blocks, gsize n_block_bytes, GError **error) /** * g_utf8_to_ucs4: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. + * @len: the maximum length of @str to use, in bytes. If @len is negative, + * then the string is nul-terminated. * @items_read: (out) (optional): location to store number of - * bytes read, or %NULL. - * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - * returned in case @str contains a trailing partial - * character. If an error occurs then the index of the - * invalid input is stored here. + * bytes read, or `NULL`. + * If `NULL`, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial + * character. If an error occurs then the index of the + * invalid input is stored here. * @items_written: (out) (optional): location to store number - * of characters written or %NULL. The value here stored does not include - * the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * of characters written or `NULL`. The value here stored does not include + * the trailing nul character. + * @error: location to store the error occurring, or `NULL` to ignore + * errors. Any of the errors in [error@GLib.ConvertError] other than + * [error@GLib.ConvertError.NO_CONVERSION] may occur. * - * Convert a string from UTF-8 to a 32-bit fixed width - * representation as UCS-4. A trailing 0 character will be added to the - * string after the converted text. + * Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4. + * + * A trailing nul character (U+0000) will be added to the string after the + * converted text. * * Returns: (transfer full): a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. + * This value must be freed with [func@GLib.free]. */ gunichar * g_utf8_to_ucs4 (const gchar *str, @@ -991,23 +998,25 @@ g_utf8_to_ucs4 (const gchar *str, * g_ucs4_to_utf8: * @str: (array length=len) (element-type gunichar): a UCS-4 encoded string * @len: the maximum length (number of characters) of @str to use. - * If @len < 0, then the string is nul-terminated. + * If @len is negative, then the string is nul-terminated. * @items_read: (out) (optional): location to store number of - * characters read, or %NULL. + * characters read, or `NULL`. * @items_written: (out) (optional): location to store number - * of bytes written or %NULL. The value here stored does not include the - * trailing 0 byte. + * of bytes written or `NULL`. The value here stored does not include the + * trailing nul byte. * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from a 32-bit fixed width representation as UCS-4. - * to UTF-8. The result will be terminated with a 0 byte. + * to UTF-8. + * + * The result will be terminated with a nul byte. * * Returns: (transfer full): a pointer to a newly allocated UTF-8 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. In that case, @items_read - * will be set to the position of the first invalid input character. + * This value must be freed with [func@GLib.free]. If an error occurs, + * @items_read will be set to the position of the first invalid input + * character. */ gchar * g_ucs4_to_utf8 (const gunichar *str, @@ -1065,36 +1074,36 @@ g_ucs4_to_utf8 (const gunichar *str, * g_utf16_to_utf8: * @str: (array length=len) (element-type guint16): a UTF-16 encoded string * @len: the maximum length (number of #gunichar2) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - * be returned in case @str contains a trailing partial character. If - * an error occurs then the index of the invalid input is stored here. - * It’s guaranteed to be non-negative. + * If @len is negative, then the string is nul-terminated. + * @items_read: (out) (optional): location to store number of words read, or + * `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will + * be returned in case @str contains a trailing partial character. If + * an error occurs then the index of the invalid input is stored here. + * It’s guaranteed to be non-negative. * @items_written: (out) (optional): location to store number - * of bytes written, or %NULL. The value stored here does not include the - * trailing 0 byte. It’s guaranteed to be non-negative. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * of bytes written, or `NULL`. The value stored here does not include the + * trailing nul byte. It’s guaranteed to be non-negative. + * @error: location to store the error occurring, or `NULL` to ignore + * errors. Any of the errors in [error@GLib.ConvertError] other than + * [error@GLib.ConvertError.NO_CONVERSION] may occur. * - * Convert a string from UTF-16 to UTF-8. The result will be - * terminated with a 0 byte. + * Convert a string from UTF-16 to UTF-8. + * + * The result will be terminated with a nul byte. * * Note that the input is expected to be already in native endianness, * an initial byte-order-mark character is not handled specially. - * g_convert() can be used to convert a byte buffer of UTF-16 data of + * [func@GLib.convert] can be used to convert a byte buffer of UTF-16 data of * ambiguous endianness. * * Further note that this function does not validate the result - * string; it may e.g. include embedded NUL characters. The only + * string; it may (for example) include embedded nul characters. The only * validation done by this function is to ensure that the input can - * be correctly interpreted as UTF-16, i.e. it doesn't contain + * be correctly interpreted as UTF-16, i.e. it doesn’t contain * unpaired surrogates or partial character sequences. * * Returns: (transfer full): a pointer to a newly allocated UTF-8 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. + * This value must be freed with [func@GLib.free]. **/ gchar * g_utf16_to_utf8 (const gunichar2 *str, @@ -1221,24 +1230,24 @@ g_utf16_to_utf8 (const gunichar2 *str, * g_utf16_to_ucs4: * @str: (array length=len) (element-type guint16): a UTF-16 encoded string * @len: the maximum length (number of #gunichar2) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - * be returned in case @str contains a trailing partial character. If - * an error occurs then the index of the invalid input is stored here. + * If @len is negative, then the string is nul-terminated. + * @items_read: (out) (optional): location to store number of words read, or + * `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be + * returned in case @str contains a trailing partial character. If + * an error occurs then the index of the invalid input is stored here. * @items_written: (out) (optional): location to store number - * of characters written, or %NULL. The value stored here does not include - * the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * of characters written, or `NULL`. The value stored here does not include + * the trailing nul character. + * @error: location to store the error occurring, or `NULL` to ignore + * errors. Any of the errors in [error@GLib.ConvertError] other than + * [error@GLib.ConvertError.NO_CONVERSION] may occur. * - * Convert a string from UTF-16 to UCS-4. The result will be - * nul-terminated. + * Convert a string from UTF-16 to UCS-4. + * + * The result will be nul-terminated. * * Returns: (transfer full): a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. + * This value must be freed with [func@GLib.free]. */ gunichar * g_utf16_to_ucs4 (const gunichar2 *str, @@ -1359,24 +1368,24 @@ g_utf16_to_ucs4 (const gunichar2 *str, * g_utf8_to_utf16: * @str: a UTF-8 encoded string * @len: the maximum length (number of bytes) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - * be returned in case @str contains a trailing partial character. If - * an error occurs then the index of the invalid input is stored here. + * If @len is negative, then the string is nul-terminated. + * @items_read: (out) (optional): location to store number of bytes read, or + * `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will + * be returned in case @str contains a trailing partial character. If + * an error occurs then the index of the invalid input is stored here. * @items_written: (out) (optional): location to store number - * of #gunichar2 written, or %NULL. The value stored here does not include - * the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * of `gunichar2` written, or `NULL`. The value stored here does not include + * the trailing nul. + * @error: location to store the error occurring, or `NULL` to ignore + * errors. Any of the errors in [error@GLib.ConvertError] other than + * [error@GLib.ConvertError.NO_CONVERSION] may occur. * - * Convert a string from UTF-8 to UTF-16. A 0 character will be - * added to the result after the converted text. + * Convert a string from UTF-8 to UTF-16. + * + * A nul character (U+0000) will be added to the result after the converted text. * * Returns: (transfer full): a pointer to a newly allocated UTF-16 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. + * This value must be freed with [func@GLib.free]. */ gunichar2 * g_utf8_to_utf16 (const gchar *str, @@ -1476,23 +1485,23 @@ g_utf8_to_utf16 (const gchar *str, * g_ucs4_to_utf16: * @str: (array length=len) (element-type gunichar): a UCS-4 encoded string * @len: the maximum length (number of characters) of @str to use. - * If @len < 0, then the string is nul-terminated. + * If @len is negative, then the string is nul-terminated. * @items_read: (out) (optional): location to store number of - * bytes read, or %NULL. If an error occurs then the index of the invalid - * input is stored here. + * bytes read, or `NULL`. If an error occurs then the index of the invalid + * input is stored here. * @items_written: (out) (optional): location to store number - * of #gunichar2 written, or %NULL. The value stored here does not include - * the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. + * of `gunichar2` written, or `NULL`. The value stored here does not include + * the trailing nul. + * @error: location to store the error occurring, or `NULL` to ignore + * errors. Any of the errors in [error@GLib.ConvertError] other than + * [error@GLib.ConvertError.NO_CONVERSION] may occur. * - * Convert a string from UCS-4 to UTF-16. A 0 character will be - * added to the result after the converted text. + * Convert a string from UCS-4 to UTF-16. + * + * A nul character (U+0000) will be added to the result after the converted text. * * Returns: (transfer full): a pointer to a newly allocated UTF-16 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. + * This value must be freed with [func@GLib.free]. */ gunichar2 * g_ucs4_to_utf16 (const gunichar *str, @@ -1730,26 +1739,28 @@ fast_validate_len (const char *str, /** * g_utf8_validate: * @str: (array length=max_len) (element-type guint8): a pointer to character data - * @max_len: max bytes to validate, or -1 to go until NUL + * @max_len: max bytes to validate, or `-1` to go until nul * @end: (out) (optional) (transfer none): return location for end of valid data * - * Validates UTF-8 encoded text. @str is the text to validate; - * if @str is nul-terminated, then @max_len can be -1, otherwise - * @max_len should be the number of bytes to validate. - * If @end is non-%NULL, then the end of the valid range - * will be stored there (i.e. the start of the first invalid - * character if some bytes were invalid, or the end of the text - * being validated otherwise). + * Validates UTF-8 encoded text. * - * Note that g_utf8_validate() returns %FALSE if @max_len is - * positive and any of the @max_len bytes are nul. + * @str is the text to validate; if @str is nul-terminated, then @max_len can be + * `-1`, otherwise @max_len should be the number of bytes to validate. * - * Returns %TRUE if all of @str was valid. Many GLib and GTK + * If @end is non-`NULL`, then the end of the valid range will be stored there. + * This is the first byte of the first invalid character if some bytes were + * invalid, or the end of the text being validated otherwise — either the + * trailing nul byte, or the first byte beyond @max_len (if it’s positive). + * + * Note that `g_utf8_validate()` returns `FALSE` if @max_len is positive and + * any of the @max_len bytes are nul. + * + * Returns `TRUE` if all of @str was valid. Many GLib and GTK * routines require valid UTF-8 as input; so data read from a file - * or the network should be checked with g_utf8_validate() before + * or the network should be checked with `g_utf8_validate()` before * doing anything else with it. * - * Returns: %TRUE if the text was valid UTF-8 + * Returns: `TRUE` if the text was valid UTF-8 */ gboolean g_utf8_validate (const char *str, @@ -1781,10 +1792,10 @@ g_utf8_validate (const char *str, * * Validates UTF-8 encoded text. * - * As with g_utf8_validate(), but @max_len must be set, and hence this function - * will always return %FALSE if any of the bytes of @str are nul. + * As with [func@GLib.utf8_validate], but @max_len must be set, and hence this + * function will always return `FALSE` if any of the bytes of @str are nul. * - * Returns: %TRUE if the text was valid UTF-8 + * Returns: `TRUE` if the text was valid UTF-8 * Since: 2.60 */ gboolean @@ -1810,11 +1821,12 @@ g_utf8_validate_len (const char *str, * g_unichar_validate: * @ch: a Unicode character * - * Checks whether @ch is a valid Unicode character. Some possible - * integer values of @ch will not be valid. 0 is considered a valid - * character, though it's normally a string terminator. + * Checks whether @ch is a valid Unicode character. + * + * Some possible integer values of @ch will not be valid. U+0000 is considered a + * valid character, though it’s normally a string terminator. * - * Returns: %TRUE if @ch is a valid Unicode character + * Returns: `TRUE` if @ch is a valid Unicode character **/ gboolean g_unichar_validate (gunichar ch) @@ -1825,12 +1837,13 @@ g_unichar_validate (gunichar ch) /** * g_utf8_strreverse: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. + * @len: the maximum length of @str to use, in bytes. If @len is negative, + * then the string is nul-terminated. * - * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. - * (Use g_utf8_validate() on all text before trying to use UTF-8 - * utility functions with it.) + * Reverses a UTF-8 string. + * + * @str must be valid UTF-8 encoded text. (Use [func@GLib.utf8_validate] on all + * text before trying to use UTF-8 utility functions with it.) * * This function is intended for programmatic uses of reversed strings. * It pays no attention to decomposed characters, combining marks, byte @@ -1838,8 +1851,8 @@ g_unichar_validate (gunichar ch) * characters which might need special handling when reversing a string * for display purposes. * - * Note that unlike g_strreverse(), this function returns - * newly-allocated memory, which should be freed with g_free() when + * Note that unlike [func@GLib.strreverse], this function returns + * newly-allocated memory, which should be freed with [func@GLib.free] when * no longer needed. * * Returns: (transfer full): a newly-allocated string which is the reverse of @str @@ -1875,8 +1888,8 @@ g_utf8_strreverse (const gchar *str, /** * g_utf8_make_valid: * @str: string to coerce into UTF-8 - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. + * @len: the maximum length of @str to use, in bytes. If @len is negative, + * then the string is nul-terminated. * * If the provided string is valid UTF-8, return a copy of it. If not, * return a copy in which bytes that could not be interpreted as valid Unicode