[gtkmm-documentation/gtkmm-3-22] Clarify when the user shall delete the wrap() result

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 0a78a3ab2d83d6956548837684534fdcf7aa2f24
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Wed Nov 15 15:23:47 2017 +0100

    Clarify when the user shall delete the wrap() result
    
    There are situations when the user is responsible for deleting
    the wrap() result. Bug 788646

 docs/tutorial/C/index-in.docbook |   30 +++++++++++++++++++-----------
 1 files changed, 19 insertions(+), 11 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index 0c415f6..f6ab828 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -477,16 +477,17 @@ just connecting to the existing &gtkmm; signals, see the <link linkend="chapter-
 
 <sect1 id="sec-basics-gobj-and-wrap">
 <title>Mixing C and C++ APIs</title>
-<para>You can use C APIs which do not yet have convenient C++ interfaces. It is generally not a problem to 
use C APIs from C++, and &gtkmm; helps by providing access to the underlying C object, and providing an easy 
way to create a C++ wrapper object from a C object, provided that the C API is also based on the GObject 
system.</para>
+<para>You can use C APIs which do not yet have convenient C++ interfaces.
+It is generally not a problem to use C APIs from C++, and &gtkmm; helps by
+providing access to the underlying C object, and providing an easy way to create
+a C++ wrapper object from a C object, provided that the C API is also based on
+the <classname>GObject</classname> system.</para>
 
 <para>
 To use a &gtkmm; instance with a C function that requires a C
 <classname>GObject</classname> instance, use the C++ instance’s
 <function>gobj()</function> function to obtain a pointer to the underlying C
 instance. For example:
-</para>
-
-<para>
 <programlisting>
 Gtk::Button* button = new Gtk::Button("example");
 gtk_button_do_something_that_gtkmm_cannot(button-&gt;gobj());
@@ -495,20 +496,27 @@ gtk_button_do_something_that_gtkmm_cannot(button-&gt;gobj());
 
 <para>
 To obtain a &gtkmm; instance from a C <classname>GObject</classname> instance,
-use the <function>Glib::wrap()</function> function. The returned C++ wrapper is
-lazily initialized and owned by &gtkmm;, so you should not delete it. The C
-instance’s reference count is not incremented, unless you set the optional
+use one of the many overloaded <function>Glib::wrap()</function> functions.
+The C instance’s reference count is not incremented, unless you set the optional
 <parameter>take_copy</parameter> argument to <literal>true</literal>. For
 example:
-</para>
-
-<para>
 <programlisting>
 GtkButton* cbutton = get_a_button();
 Gtk::Button* button = Glib::wrap(cbutton);
-button.set_label("Now I speak C++ too!");
+button-&gt;set_label("Now I speak C++ too!");
 </programlisting>
+The C++ wrapper shall be explicitly deleted if
+<itemizedlist>
+<listitem><para>it's a widget or other class that inherits from <classname>Gtk::Object</classname>, 
and</para></listitem>
+<listitem><para>the C instance has a floating reference when the wrapper is created, and</para></listitem>
+<listitem><para><function>Gtk::manage()</function> is not called.</para></listitem>
+</itemizedlist>
+<function>Glib::wrap()</function> binds the C and C++ instances to each other.
+Don't delete the C++ instance before you want the C instance to die.
 </para>
+<para>In all other cases the C++ instance is automatically deleted when the last reference
+to the C instance is dropped. This includes all <function>Glib::wrap()</function>
+overloads that return a <classname>Glib::RefPtr</classname>.</para>
 
 </sect1>