[gtkmm] Gtk::Builder: Add more documentation

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 301a083980e6706368852b3f5c3a0e92443c6eaf
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu Jun 19 11:12:56 2014 +0200

    Gtk::Builder: Add more documentation
    
    * gtk/src/builder.hg: Copy some documentation from GtkBuilder, describing
    the lifetime of windows, other widgets and other objects. Bug #731444.

 gtk/src/builder.hg |   26 +++++++++++++++++++++++---
 1 files changed, 23 insertions(+), 3 deletions(-)
---
diff --git a/gtk/src/builder.hg b/gtk/src/builder.hg
index 0b72b9f..5811378 100644
--- a/gtk/src/builder.hg
+++ b/gtk/src/builder.hg
@@ -32,12 +32,32 @@ class Application;
  */
 _WRAP_GERROR(BuilderError,GtkBuilderError,GTK_BUILDER_ERROR)
 
-/** Build an interface from a UI definition description.
+/** Build an interface from an XML UI definition description.
  *
  * This object represents an `instantiation' of an UI definition description.
- * When one of these objects is created, the XML file is read, and the interface
+ * When one of these objects is created, the XML file is read, and the user interface
  * is created. The Gtk::Builder object then provides an interface for accessing the
- * widgets in the interface by the names assigned to them inside the UI description.
+ * widgets in the user interface by the names assigned to them inside the UI description.
+ *
+ * A Gtk::Builder holds a reference to all objects that it has constructed
+ * and drops these references when it is deleted. This deletion can
+ * cause the destruction of non-widget objects or widgets which are not
+ * contained in a toplevel window. For toplevel windows constructed by a
+ * builder, it is the responsibility of the user to get them with get_widget()
+ * or get_widget_derived() and delete them to get rid of them and all
+ * the widgets they contain.
+ *
+ * The methods get_widget() and get_widget_derived()
+ * can be used to access the widgets in the interface by the names assigned
+ * to them inside the UI description. Toplevel windows returned by these
+ * methods will stay around until the user explicitly deletes them.
+ * Other widgets will either be part of a
+ * larger hierarchy constructed by the builder (in which case you should
+ * not have to worry about their lifecycle), or without a parent, in which
+ * case they have to be added to some container before the builder is deleted
+ * to make use of them.
+ * Non-widget objects need to be fetched with get_object() or get_objects()
+ * to keep them beyond the lifespan of the builder.
  *
  * @newin{2,12}
  */