[glib] gerror: Minor clarifications to the GError documentation

[Philip Withnall <pwithnall src gnome org>]

commit bdfc8231c6252dfe11cc0d614e71dd98e7570b53
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 18:21:30 2014 +0000

    gerror: Minor clarifications to the GError documentation
    
     • Clarify that GError** parameters are for the return of _newly
       allocated_ GError*s.
     • Clarify that errors may need to be checked for explicitly if the
       return value of a function doesn’t reliably indicate them.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 glib/gerror.c |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)
---
diff --git a/glib/gerror.c b/glib/gerror.c
index 4eed58e..958f776 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -52,7 +52,8 @@
  * functions in GLib and GTK+ do not use the #GError facility.
  *
  * Functions that can fail take a return location for a #GError as their
- * last argument. For example:
+ * last argument. On error, a new #GError instance will be allocated and
+ * returned to the caller via this argument. For example:
  * |[<!-- language="C" -->
  * gboolean g_file_get_contents (const gchar  *filename,
  *                               gchar       **contents,
@@ -161,7 +162,8 @@
  * ]|
  *
  * If the sub-function does not indicate errors other than by
- * reporting a #GError, you need to create a temporary #GError
+ * reporting a #GError (or if its return value does not reliably indicate
+ * errors) you need to create a temporary #GError
  * since the passed-in one may be %NULL. g_propagate_error() is
  * intended for use in this case.
  * |[<!-- language="C" -->