Merge branch 'utf8-docs' into 'main'

gutf8: Convert docs to gi-docgen linking syntax

See merge request GNOME/glib!4304

1 files changed, 171 insertions, 158 deletions

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.
  *
- * Convert a string from UTF-16 to UTF-8. The result will be
- * terminated with a 0 byte.
+ * 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.
  *
- * Convert a string from UTF-16 to UCS-4. The result will be
- * nul-terminated.
+ * 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).
- *
- * 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
+ * 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.
+ * 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.
  *
- * 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.)
+ * @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