[gtk+] docs: GtkBuilder: warn about unusual GError use

[Ryan Lortie <ryanl src gnome org>]

commit 1bc7359123aa188d4e33aaedf33068ce0bbc1a55
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Jul 14 11:03:29 2012 -0400

    docs: GtkBuilder: warn about unusual GError use
    
    GtkBuilder returns GError for _add_from_{file,resource,string}(),
    implying that the user should be able to recover from these errors.
    Mention in the docs that it's unreasonable to try to do this.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=679930

 gtk/gtkbuilder.c |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index 7842565..c048c00 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -973,6 +973,13 @@ gtk_builder_new (void)
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR 
  * domain.
  *
+ * It's not really reasonable to attempt to handle failures of this
+ * call.  You should not use this function with untrusted files (ie:
+ * files that are not part of your application).  Broken #GtkBuilder
+ * files can easily crash your program, and it's possible that memory
+ * was leaked leading up to the reported failure.  The only reasonable
+ * thing to do when an error is detected is to call g_error().
+ *
  * Returns: A positive value on success, 0 if an error occurred
  *
  * Since: 2.12
@@ -1143,6 +1150,10 @@ _gtk_builder_extend_with_template (GtkBuilder    *builder,
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR
  * domain.
  *
+ * It's not really reasonable to attempt to handle failures of this
+ * call.  The only reasonable thing to do when an error is detected is
+ * to call g_error().
+ *
  * Returns: A positive value on success, 0 if an error occurred
  *
  * Since: 3.4
@@ -1294,6 +1305,10 @@ gtk_builder_add_objects_from_resource (GtkBuilder   *builder,
  * Upon errors 0 will be returned and @error will be assigned a
  * #GError from the #GTK_BUILDER_ERROR or #G_MARKUP_ERROR domain.
  *
+ * It's not really reasonable to attempt to handle failures of this
+ * call.  The only reasonable thing to do when an error is detected is
+ * to call g_error().
+ *
  * Returns: A positive value on success, 0 if an error occurred
  *
  * Since: 2.12