[gtkmm-documentation/gtkmm-3-22] Mixing C & C++: Clarify ownership of wrap() result

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 09e84521a5e8bd3b966e8ab582a5c5bf6f414bfb
Author: Daniel Boles <dboles src gmail com>
Date:   Sat Oct 7 19:05:31 2017 +0100

    Mixing C & C++: Clarify ownership of wrap() result
    
    Make it clear that wrap() returns a pointer to an instance owned by
    glibmm, so users should not try to delete it. Also mention the effect on
    refcount, i.e. nothing if (!take_copy). Finally, show the C++ instance
    actually being used (though a better example would show more advantage).
    
    While here, I split the long paragraphs for readability & to help git, &
    add some missing <classname>/<function> tags for readability/semantics.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=788646

 docs/tutorial/C/index-in.docbook |   21 ++++++++++++++++++---
 1 files changed, 18 insertions(+), 3 deletions(-)
---
diff --git a/docs/tutorial/C/index-in.docbook b/docs/tutorial/C/index-in.docbook
index c31c6c0..0c415f6 100644
--- a/docs/tutorial/C/index-in.docbook
+++ b/docs/tutorial/C/index-in.docbook
@@ -479,22 +479,37 @@ just connecting to the existing &gtkmm; signals, see the <link linkend="chapter-
 <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>To use a &gtkmm; instance with a C function that requires a C GObject instance, use the 
<function>gobj()</function> function to obtain a pointer to the underlying GObject instance. For 
instance</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_new(button-&gt;gobj());
+gtk_button_do_something_that_gtkmm_cannot(button-&gt;gobj());
 </programlisting>
 </para>
 
-<para>To obtain a &gtkmm; instance from a C GObject instance, use the Glib::wrap() function. For 
instance</para>
+<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
+<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!");
 </programlisting>
 </para>
+
 </sect1>
 
 <sect1 id="sec-helloworld">