Update the docs

Remove various references to gtk_widget_destroy in the docs.

docs/reference/gtk/getting_started.xml.in

@@ -194,12 +194,13 @@
   a g_signal_connect() with the difference lying in how the callback function is
   treated. g_signal_connect_swapped() allows 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> 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. More information about creating buttons can be found
+  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_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>
 

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>

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.

gtk/gtkcontainer.c

@@ -288,14 +288,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,

gtk/gtkwidget.c

@@ -7277,7 +7277,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),