[glib: 2/3] glib: add parameter annotations for g_vasprintf and callers

[Philip Withnall <pwithnall src gnome org>]

commit 109be1e90d60ac58bd66a3a1992872537b12dafa
Author: Daniel P. Berrangé <berrange redhat com>
Date:   Fri Oct 4 15:04:01 2019 +0100

    glib: add parameter annotations for g_vasprintf and callers
    
    Document that g_vasprintf and g_strdup_printf are guaranteed to return a
    non-NULL string, unless the format string contains the locale sensitive
    conversions %lc or %ls.
    
    Further annotate that the output parameter for g_vasprintf and the
    format string for all functions must be non-NULL.
    
    Fixes #1622
    
    Signed-off-by: Daniel P. Berrangé <berrange redhat com>

 glib/gprintf.c   |  8 ++++++--
 glib/gstrfuncs.c | 12 ++++++++++--
 glib/gstring.c   |  4 ++--
 3 files changed, 18 insertions(+), 6 deletions(-)
---
diff --git a/glib/gprintf.c b/glib/gprintf.c
index d4d0b3e0c..6be85c70f 100644
--- a/glib/gprintf.c
+++ b/glib/gprintf.c
@@ -295,8 +295,8 @@ g_vsnprintf (gchar   *string,
 
 /**
  * g_vasprintf:
- * @string: the return location for the newly-allocated string.
- * @format: a standard printf() format string, but notice
+ * @string: (not optional) (nullable): the return location for the newly-allocated string.
+ * @format: (not nullable): a standard printf() format string, but notice
  *          [string precision pitfalls][string-precision]
  * @args: the list of arguments to insert in the output.
  *
@@ -306,6 +306,10 @@ g_vsnprintf (gchar  *string,
  * 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
+ * @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.
diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c
index a37ef899c..57aec6823 100644
--- a/glib/gstrfuncs.c
+++ b/glib/gstrfuncs.c
@@ -491,7 +491,7 @@ g_stpcpy (gchar       *dest,
 
 /**
  * g_strdup_vprintf:
- * @format: a standard printf() format string, but notice
+ * @format: (not nullable): a standard printf() format string, but notice
  *     [string precision pitfalls][string-precision]
  * @args: the list of parameters to insert into the format string
  *
@@ -500,6 +500,10 @@ g_stpcpy (gchar       *dest,
  * the result. The returned string should be freed with g_free() when
  * no longer needed.
  *
+ * 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
  * additionally returns the length of the allocated string.
  *
@@ -518,7 +522,7 @@ g_strdup_vprintf (const gchar *format,
 
 /**
  * g_strdup_printf:
- * @format: a standard printf() format string, but notice
+ * @format: (not nullable): a standard printf() format string, but notice
  *     [string precision pitfalls][string-precision]
  * @...: the parameters to insert into the format string
  *
@@ -527,6 +531,10 @@ g_strdup_vprintf (const gchar *format,
  * the result. The returned string should be freed with g_free() when no
  * longer needed.
  *
+ * 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: a newly-allocated string holding the result
  */
 gchar*
diff --git a/glib/gstring.c b/glib/gstring.c
index 24692f135..be456ffb4 100644
--- a/glib/gstring.c
+++ b/glib/gstring.c
@@ -1144,7 +1144,7 @@ g_string_up (GString *string)
 /**
  * g_string_append_vprintf:
  * @string: a #GString
- * @format: the string format. See the printf() documentation
+ * @format: (not nullable): the string format. See the printf() documentation
  * @args: the list of arguments to insert in the output
  *
  * Appends a formatted string onto the end of a #GString.
@@ -1179,7 +1179,7 @@ g_string_append_vprintf (GString     *string,
 /**
  * g_string_vprintf:
  * @string: a #GString
- * @format: the string format. See the printf() documentation
+ * @format: (not nullable): the string format. See the printf() documentation
  * @args: the parameters to insert into the format string
  *
  * Writes a formatted string into a #GString.