[gtkmm] Gtk::Widget::signal_destroy(): Format the description to fit Doxygen

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 0c0b21219774e3040e379fabefa79046aef7e5e8
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Tue Aug 2 16:42:27 2022 +0200

    Gtk::Widget::signal_destroy(): Format the description to fit Doxygen

 gtk/src/widget.hg | 51 ++++++++++++++++++++++++++++-----------------------
 1 file changed, 28 insertions(+), 23 deletions(-)
---
diff --git a/gtk/src/widget.hg b/gtk/src/widget.hg
index 5182aac9..bcde1491 100644
--- a/gtk/src/widget.hg
+++ b/gtk/src/widget.hg
@@ -571,29 +571,34 @@ public:
 
   _WRAP_SIGNAL(bool mnemonic_activate(bool group_cycling), "mnemonic_activate")
 
-  // Use this if you are implementing an object, which is 1. a direct
-  // descendant of Gtk::Widget, 2. contains other objects, and 3. want it to
-  // work well as a managed object. The children of the object need to be
-  // unparented *both* from the handler of this signal *and* from the
-  // destructor. Reason: when your class is used as a managed object, then the
-  // C++ destructor is called too late, but when your class is managed via the
-  // standard C++ manner, then this signal is not emitted at all.
-  //
-  // When your class inherits from Gtk::Box, you do not need to worry about
-  // handling this signal, Box will do the unparenting for you. When you are
-  // implementing a custom widget that does not have contained widgets, but
-  // rather only uses custom drawing, then you also do not need to worry about
-  // handling this signal.
-  //
-  // This signal is emitted by Gtk::Widget during the dispose phase of object
-  // destruction.  See the "Reference count" section in the GObject concepts
-  // documentation (https://docs.gtk.org/gobject/concepts.html#reference-count)
-  // for the specification of the dispose and the finalize phases of object
-  // destruction. In short: the contract is that after dispose, the object is
-  // not supposed to hold any reference to other member objects. Note that
-  // dispose may be called multiple times, so your implementation of this
-  // signal must tolerate that.
-  _WRAP_SIGNAL(void destroy(), "destroy", no_default_handler)
+  /** Emitted during the dispose phase.
+   *
+   * You need to connect to this signal only if you are implementing a widget, which
+   * 1. is a direct descendant of %Gtk::Widget,
+   * 2. contains other widgets (is a container widget), and
+   * 3. shall work well as a managed object.
+   *
+   * The children of the object need to be unparented *both* from the handler
+   * of this signal *and* from the destructor. Reason: when your class is used
+   * as a managed object, then the C++ destructor is called too late, but when
+   * your class is managed via the standard C++ manner, then this signal is not
+   * emitted at all.
+   *
+   * When your class inherits from a container widget, such as Gtk::Box, you
+   * do not need to handle this signal. When your widget does not have child
+   * widgets, then you also do not need to handle this signal.
+   *
+   * This signal is emitted by %Gtk::Widget during the dispose phase of object
+   * destruction. See the <a href="https://docs.gtk.org/gobject/concepts.html#reference-count";>
+   * Reference count</a> section in the GObject concepts documentation
+   * for the specification of the dispose and the finalize phases of object
+   * destruction. After dispose, the object is not supposed to hold any reference
+   * to other member objects.
+   *
+   * Dispose may be called multiple times, so your implementation of this
+   * signal must tolerate that.
+   */
+  _WRAP_SIGNAL(void destroy(), "destroy", no_default_handler, newin "4,8")
 
 #m4begin
 dnl// Hook in special code to catch explicit uses of gtk_object_destroy() by