[gtk/window-destroy] Update the docs

[Matthias Clasen <matthiasc src gnome org>]

commit 1c06e1d92d5de0a27802303c546054ccfa46567f
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 9 20:01:21 2020 -0400

    Update the docs
    
    Remove various references to gtk_widget_destroy in the docs.

 docs/reference/gtk/getting_started.xml.in |  7 ++++---
 docs/reference/gtk/question_index.xml     | 15 ++++-----------
 gtk/gtkbuilder.c                          |  4 ++--
 gtk/gtkcontainer.c                        |  6 ++----
 gtk/gtkwidget.c                           |  2 +-
 5 files changed, 13 insertions(+), 21 deletions(-)
---
diff --git a/docs/reference/gtk/getting_started.xml.in b/docs/reference/gtk/getting_started.xml.in
index 3f2405caa4..4d636d48a5 100644
--- a/docs/reference/gtk/getting_started.xml.in
+++ b/docs/reference/gtk/getting_started.xml.in
@@ -193,11 +193,12 @@
   a g_signal_connect() with the difference lying in how the callback function is
   treated. g_signal_connect_swapped() allow you to specify what the callback
   function should take as parameter by letting you pass it as data. In this case
-  the function being called back is gtk_widget_destroy() and the <varname>window</varname>
+  the function being called back is gtk_window_destroy() and the <varname>window</varname>
   pointer is passed to it. This has the effect that when the button is clicked,
   the whole GTK window is destroyed. In contrast if a normal g_signal_connect() were used
-  to connect the "clicked" signal with gtk_widget_destroy(), then the <varname>button</varname>
-  itself would have been destroyed, not the window.
+  to connect the "clicked" signal with gtk_window_destroy(), then the function
+  would be called on <varname>button</varname> (which would not go well, since
+  the function expects a GtkWindow as argument).
   More information about creating buttons can be found
   <ulink url="https://wiki.gnome.org/HowDoI/Buttons";>here</ulink>.
   </para>
diff --git a/docs/reference/gtk/question_index.xml b/docs/reference/gtk/question_index.xml
index 0cd8062185..3353b754f0 100644
--- a/docs/reference/gtk/question_index.xml
+++ b/docs/reference/gtk/question_index.xml
@@ -123,8 +123,8 @@ after creating it ?
 <para>
 If <structname>GtkFoo</structname> isn't a toplevel window, then
 <informalexample><programlisting>
- foo = gtk_foo_new (<!-- -->);
- gtk_widget_destroy (foo);
+ foo = gtk_foo_new ();
+ g_object_unref (foo);
 </programlisting></informalexample>
 is a memory leak, because no one assumed the initial floating
 reference. If you are using a widget and you aren't immediately
@@ -137,19 +137,12 @@ To get this, you must acquire a reference to the widget and drop the
 floating reference (<quote>ref and sink</quote> in GTK parlance) after
 creating it:
 <informalexample><programlisting>
- foo = gtk_foo_new (<!-- -->);
+ foo = gtk_foo_new ();
  g_object_ref_sink (foo);
 </programlisting></informalexample>
-When you want to get rid of the widget, you must call gtk_widget_destroy()
-to break any external connections to the widget before dropping your
-reference:
-<informalexample><programlisting>
- gtk_widget_destroy (foo);
- g_object_unref (foo);
-</programlisting></informalexample>
 When you immediately add a widget to a container, it takes care of
 assuming the initial floating reference and you don't have to worry
-about reference counting at all ... just call gtk_widget_destroy()
+about reference counting at all ... just call gtk_container_remove()
 to get rid of the widget.
 </para>
 </answer>
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index a4351bade1..803180c65f 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -39,14 +39,14 @@
  * and drops these references when it is finalized. This finalization 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 call gtk_widget_destroy()
+ * builder, it is the responsibility of the user to call gtk_window_destroy()
  * to get rid of them and all the widgets they contain.
  *
  * The functions gtk_builder_get_object() and gtk_builder_get_objects()
  * 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
  * functions will stay around until the user explicitly destroys them
- * with gtk_widget_destroy(). Other widgets will either be part of a
+ * with gtk_window_destroy(). 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 to make use of them.
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index c7eaebd8a4..ff647488a8 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -290,14 +290,12 @@ gtk_container_add (GtkContainer *container,
  * @widget: a current child of @container
  *
  * Removes @widget from @container. @widget must be inside @container.
+ *
  * Note that @container will own a reference to @widget, and that this
  * may be the last reference held; so removing a widget from its
  * container can destroy that widget. If you want to use @widget
  * again, you need to add a reference to it before removing it from
- * a container, using g_object_ref(). If you don’t want to use @widget
- * again it’s usually more efficient to simply destroy it directly
- * using gtk_widget_destroy() since this will remove it from the
- * container and help break any circular reference count cycles.
+ * a container, using g_object_ref().
  **/
 void
 gtk_container_remove (GtkContainer *container,
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 8780165cff..1b0ce5d61a 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -7236,7 +7236,7 @@ gtk_widget_real_destroy (GtkWidget *object)
          FinalizeAssertion *assertion = l->data;
 
          if (!assertion->did_finalize)
-           g_critical ("Automated component '%s' of class '%s' did not finalize in gtk_widget_destroy(). "
+           g_critical ("Automated component '%s' of class '%s' did not finalize in dispose()"
                        "Current reference count is %d",
                        assertion->child_class->name,
                        g_type_name (assertion->widget_type),