From 04662a8667c8bf0a594f0c6db7291066c272ad38 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Fri, 16 Jan 2015 08:38:56 +0000 Subject: [PATCH] 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 file changed, 6 insertions(+) diff --git a/glib/gerror.c b/glib/gerror.c index 1722f2036..694e84810 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: