[gtk/kill-containers: 43/43] docs: Update migration guide

[Matthias Clasen <matthiasc src gnome org>]

commit 2db9cd0d68c928c952ac4827eba5c79fd2315d31
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 9 22:24:00 2020 -0400

    docs: Update migration guide
    
    Add sections about GtkBin, GtkContainer and gtk_widget_destroy().

 docs/reference/gtk/migrating-3to4.xml | 76 +++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
---
diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index 53c1b67ef1..199dd11e11 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -560,6 +560,82 @@
       </para>
     </section>
 
+    <section>
+      <title>Adapt to GtkBin removal</title>
+      <para>
+        The abstract base class GtkBin for single-child containers has been
+        removed. The former subclasses are now derived directly from GtkWidget,
+        and have a "child" property for their child widget. The affected classes
+        are:
+      </para>
+      <simplelist>
+        <member>GtkAspectFrame</member>
+        <member>GtkButton (and subclasses)</member>
+        <member>GtkComboBox</member>
+        <member>GtkFlowBoxChild</member>
+        <member>GtkFrame</member>
+        <member>GtkListBoxRow</member>
+        <member>GtkOverlay</member>
+        <member>GtkPopover</member>
+        <member>GtkRevealer</member>
+        <member>GtkScrolledWindow</member>
+        <member>GtkSearchBar</member>
+        <member>GtkViewport</member>
+        <member>GtkWindow (and subclasses)</member>
+      </simplelist>
+      <para>
+        To add a child, use the setter for the "child" property (e.g.
+        gtk_frame_set_child()) instead of gtk_container_add(). Adding a child
+        in a ui file with <tag class="starttag">child</tag> still works.
+      </para>
+    </section>
+
+    <section>
+      <title>Adapt to GtkContainer removal</title>
+      <para>
+        The abstract bas class GtkContainer for general containers has been
+        removed. The former subclasses are now derived directly from GtkWidget,
+        and have class-specific add and remove functions. The affected classes
+        are:
+      </para>
+      <simplelist>
+        <member>GtkActionBar</member>
+        <member>GtkBox (and subclasses)</member>
+        <member>GtkExpander</member>
+        <member>GtkFixed</member>
+        <member>GtkFlowBox</member>
+        <member>GtkGrid</member>
+        <member>GtkHeaderBar</member>
+        <member>GtkIconView</member>
+        <member>GtkInfoBar</member>
+        <member>GtkListBox</member>
+        <member>GtkNotebook</member>
+        <member>GtkPaned</member>
+        <member>GtkStack</member>
+        <member>GtkTextView</member>
+        <member>GtkTreeView</member>
+      </simplelist>
+      <para>
+        The most noticable change will be to use gtk_box_append() or gtk_box_prepend()
+        instead of gtk_container_add() for adding children to GtkBox, and the change
+        to use container-specific remove functions, such as gtk_stack_remove() instead
+        of gtk_container_remove(). Adding a child in a ui file with
+        <tag class="starttag">child</tag> still works.
+      </para>
+    </section>
+
+    <section>
+      <title>Adapt to gtk_widget_destroy() removal</title>
+      <para>
+        The function gtk_widget_destroy() has been removed. To explicitly destroy
+        a toplevel window, use gtk_window_destroy(). To destroy a widget that is
+        part of a hierarchy, remove it from its parent using a container-specific
+        remove api, such as gtk_box_remove() or gtk_stack_remove(). To destroy
+        a freestanding non-toplevel widget, use g_object_unref() to drop your
+        reference.
+      </para>
+    </section>
+
     <section>
       <title>Adapt to GtkStyleContext API changes</title>
       <para>