[glib] gerror: Document advantages of GError over numeric error codes

[Philip Withnall <pwithnall src gnome org>]

commit 04662a8667c8bf0a594f0c6db7291066c272ad38
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Jan 16 08:38:56 2015 +0000

    gerror: Document advantages of GError over numeric error codes
    
    Despite knowing about GError, there are multiple cases where developers
    have still used traditional numeric error codes, and then got themselves
    into a mess about bindability and generation of error messages.
    
    Try and avoid this by including a brief paragraph on the benefits of
    GError over EINVAL-style error codes.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=743011

 glib/gerror.c |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)
---
diff --git a/glib/gerror.c b/glib/gerror.c
index 1722f20..694e848 100644
--- a/glib/gerror.c
+++ b/glib/gerror.c
@@ -51,6 +51,12 @@
  * be eliminated by fixing the bug in the program. This is why most
  * functions in GLib and GTK+ do not use the #GError facility.
  *
+ * #GError has several advantages over numeric error codes: importantly, tools
+ * like [gobject-introspection](https://developer.gnome.org/gi/stable/)
+ * understand #GErrors and convert them to exceptions in bindings; the message
+ * includes more information than just a code; and use of a domain helps prevent
+ * misinterpretation of error codes.
+ *
  * Functions that can fail take a return location for a #GError as their
  * last argument. On error, a new #GError instance will be allocated and
  * returned to the caller via this argument. For example: