gmessages: Document error case for g_printf_string_upper_bound()

Spotted in https://gitlab.gnome.org/GNOME/glib/-/issues/3187.

In an ideal world, this API would have been designed with an error
return path to begin with — perhaps by returning a `GError` or a
`gssize`. We can’t change the API now, though, which leads to this
slightly awkward “0 indicates an error or success” pattern.

I think that’s justified in this case because:
 - This API does not see much use.
 - Format strings tend to be literals, and almost always are
   non-zero-length, so it tends to be statically possible to determine
   that the function won’t return zero on success.
 - If callers do need to differentiate the two zero return value cases,
   they can just call `g_vsnprintf()` directly instead.

Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3187

glib/tests/test-printf.c

@@ -897,6 +897,9 @@ test_upper_bound (void)
 
   res = upper_bound ("bla %s %d: %g\n", "bla", 123, 0.123);
   g_assert_cmpint (res, ==, 20);
+
+  res = upper_bound ("Invalid case: %ls", L"\xD800" /* incomplete surrogate pair */);
+  g_assert_cmpint (res, ==, 0);
 }
 
 #if !defined(__APPLE__) && !defined(__FreeBSD__)