[gtk/ebassi/finish-template: 9/15] docs: Include clear_template() in the templates overview

[Emmanuele Bassi <ebassi src gnome org>]

commit c2ec244b840b1a5e9a2969ecf2b4c917e24fd14c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Jul 6 13:29:31 2022 +0100

    docs: Include clear_template() in the templates overview
    
    Make sure that it's clear how to use it in idiomatic code, by tying it
    to gtk_widget_init_template().

 gtk/gtkwidget.c | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 8c943d15af..2a3fa3042e 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -386,11 +386,29 @@
  * static void
  * foo_widget_init (FooWidget *self)
  * {
- *   // ...
  *   gtk_widget_init_template (GTK_WIDGET (self));
+ *
+ *   // Initialize the rest of the widget...
  * }
  * ```
  *
+ * as well as calling [method@Gtk.Widget.clear_template] from the dispose
+ * function:
+ *
+ * ```c
+ * static void
+ * foo_widget_dispose (GObject *gobject)
+ * {
+ *   FooWidget *self = FOO_WIDGET (gobject);
+ *
+ *   // Dispose objects for which you have a reference...
+ *
+ *   // Clear the template children for this widget type
+ *   gtk_widget_clear_template (GTK_WIDGET (self), FOO_TYPE_WIDGET);
+ *
+ *   G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject);
+ * }
+ *
  * You can access widgets defined in the template using the
  * [id@gtk_widget_get_template_child] function, but you will typically declare
  * a pointer in the instance private data structure of your type using the same
@@ -408,9 +426,19 @@
  * G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX)
  *
  * static void
+ * foo_widget_dispose (GObject *gobject)
+ * {
+ *   gtk_widget_clear_template (GTK_WIDGET (gobject), FOO_TYPE_WIDGET);
+ *
+ *   G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject);
+ * }
+ *
+ * static void
  * foo_widget_class_init (FooWidgetClass *klass)
  * {
  *   // ...
+ *   G_OBJECT_CLASS (klass)->dispose = foo_widget_dispose;
+ *
  *   gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
  *                                                "/com/example/ui/foowidget.ui");
  *   gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass),
@@ -422,7 +450,7 @@
  * static void
  * foo_widget_init (FooWidget *widget)
  * {
- *
+ *   gtk_widget_init_template (GTK_WIDGET (widget));
  * }
  * ```
  *