Add missing allow-none annotations for function parameters.

[platform/upstream/glib.git] / glib / gerror.c

diff --git a/glib/gerror.c b/glib/gerror.c
index 2f5f8a9..e6ce3c0 100644 (file)
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -265,7 +265,7 @@
  * <listitem><para>
  *   The quark function for the error domain is called
  *   <literal>&lt;namespace&gt;_&lt;module&gt;_error_quark</literal>,
- *   for example g_spawn_error_quark() or %g_thread_error_quark().
+ *   for example g_spawn_error_quark() or g_thread_error_quark().
  * </para></listitem>
  * <listitem><para>
  *   The error codes are in an enumeration called
@@ -281,7 +281,7 @@
  *   If there's a "generic" or "unknown" error code for unrecoverable
  *   errors it doesn't make sense to distinguish with specific codes,
  *   it should be called <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</literal>,
- *   for example %G_SPAWN_ERROR_FAILED or %G_THREAD_ERROR_FAILED.
+ *   for example %G_SPAWN_ERROR_FAILED.
  * </para></listitem>
  * </itemizedlist>
  *
@@ -315,6 +315,10 @@
  *   immediately.
  * </para></listitem>
  * <listitem><para>
+ *   If a #GError is reported, out parameters are not guaranteed to
+ *   be set to any defined value.
+ * </para></listitem>
+ * <listitem><para>
  *   A #GError* must be initialized to %NULL before passing its address
  *   to a function that can report errors.
  * </para></listitem>
@@ -352,6 +356,7 @@
 
 #include "gerror.h"
 
+#include "gslice.h"
 #include "gstrfuncs.h"
 #include "gtestutils.h"
 
@@ -377,6 +382,14 @@ g_error_new_valist (GQuark       domain,
 {
   GError *error;
 
+  /* Historically, GError allowed this (although it was never meant to work),
+   * and it has significant use in the wild, which g_return_val_if_fail
+   * would break. It should maybe g_return_val_if_fail in GLib 4.
+   * (GNOME#660371, GNOME#560482)
+   */
+  g_warn_if_fail (domain != 0);
+  g_warn_if_fail (format != NULL);
+
   error = g_slice_new (GError);
 
   error->domain = domain;
@@ -391,7 +404,7 @@ g_error_new_valist (GQuark       domain,
  * @domain: error domain
  * @code: error code
  * @format: printf()-style format for error message
- * @Varargs: parameters for message format
+ * @...: parameters for message format
  *
  * Creates a new #GError with the given @domain and @code,
  * and a message formatted with @format.
@@ -479,6 +492,9 @@ g_error_copy (const GError *error)
   GError *copy;
  
   g_return_val_if_fail (error != NULL, NULL);
+  /* See g_error_new_valist for why these don't return */
+  g_warn_if_fail (error->domain != 0);
+  g_warn_if_fail (error->message != NULL);
 
   copy = g_slice_new (GError);
 
@@ -491,7 +507,7 @@ g_error_copy (const GError *error)
 
 /**
  * g_error_matches:
- * @error: a #GError or %NULL
+ * @error: (allow-none): a #GError or %NULL
  * @domain: an error domain
  * @code: an error code
  *
@@ -517,11 +533,11 @@ g_error_matches (const GError *error,
 
 /**
  * g_set_error:
- * @err: a return location for a #GError, or %NULL
+ * @err: (allow-none): a return location for a #GError, or %NULL
  * @domain: error domain
  * @code: error code
  * @format: printf()-style format
- * @Varargs: args for @format
+ * @...: args for @format
  *
  * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err
  * must be %NULL. A new #GError is created and assigned to *@err.
@@ -552,7 +568,7 @@ g_set_error (GError      **err,
 
 /**
  * g_set_error_literal:
- * @err: a return location for a #GError, or %NULL
+ * @err: (allow-none): a return location for a #GError, or %NULL
  * @domain: error domain
  * @code: error code
  * @message: error message
@@ -646,7 +662,7 @@ g_error_add_prefix (gchar       **string,
 
 /**
  * g_prefix_error:
- * @err: a return location for a #GError, or %NULL
+ * @err: (allow-none): a return location for a #GError, or %NULL
  * @format: printf()-style format string
  * @...: arguments to @format
  *