gutf8: Clarify return value docs for g_utf8_find_next_char()

Make it clearer that it will only return NULL if @end is non-NULL. Add a
test for this too.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

https://bugzilla.gnome.org/show_bug.cgi?id=773842

glib/gutf8.c

@@ -162,7 +162,13 @@ g_utf8_find_prev_char (const char *str,
  * is made to see if the character found is actually valid other than
  * it starts with an appropriate byte.
  * 
- * Returns: a pointer to the found character or %NULL
+ * 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
+ * is reached.
+ *
+ * Returns: (nullable): a pointer to the found character or %NULL if @end is
+ *    set and is reached
  */
 gchar *
 g_utf8_find_next_char (const gchar *p,

glib/tests/utf8-pointer.c

@@ -128,6 +128,15 @@ test_find (void)
 
   q = g_utf8_find_next_char (str + strlen (str), NULL);
   g_assert (q == str + strlen (str) + 1);
+
+  /* Check return values when reaching the end of the string,
+   * with @end set and unset. */
+  q = g_utf8_find_next_char (str + 10, NULL);
+  g_assert_nonnull (q);
+  g_assert (*q == '\0');
+
+  q = g_utf8_find_next_char (str + 10, str + 11);
+  g_assert_null (q);
 }
 
 int main (int argc, char *argv[])