[gtkmm] Gtk::Dialog: Update the class description

[Kjell Ahlstedt <kjellahl src gnome org>]

commit d01e811cc8b64e3ec053d6c8702a8a70afa8569e
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Wed Jul 13 11:07:24 2022 +0200

    Gtk::Dialog: Update the class description

 gtk/src/dialog.hg | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)
---
diff --git a/gtk/src/dialog.hg b/gtk/src/dialog.hg
index f1dd19b6..713b4f89 100644
--- a/gtk/src/dialog.hg
+++ b/gtk/src/dialog.hg
@@ -37,25 +37,29 @@ _WRAP_ENUM(ResponseType, GtkResponseType, CONV_TO_INT, decl_prefix GTKMM_API)
 
 /** Create popup windows.
  *
- * Dialog boxes are a convenient way to prompt the user for a small amount
+ * %Dialog boxes are a convenient way to prompt the user for a small amount
  * of input, eg. to display a message, ask a question, or anything else that
  * does not require extensive effort on the user's part.
  *
- * gtkmm treats a dialog as a window split vertically. The top section is a
- * vertical Gtk::Box, and is where widgets such as a Gtk::Label or a Gtk::Entry should be
- * packed. The bottom area is known as the action_area. This is generally
- * used for packing buttons into the dialog which may perform functions such
- * as cancel, ok, or apply.
+ * The main area of a %Dialog is called the "content area", and is yours
+ * to populate with widgets such a Gtk::Label or Gtk::Entry, to present
+ * your information, questions, or tasks to the user.
  *
- * A “modal” dialog (that is, one which freezes the rest of the application
- * from user input), can be created by calling Gtk::Window::set_modal() on the
- * dialog. It is also possible to set the modal property in the constructor. 
+ * In addition, dialogs allow you to add "action widgets". Most commonly,
+ * action widgets are buttons. Depending on the platform, action widgets may
+ * be presented in the header bar at the top of the window, or at the bottom
+ * of the window.
  *
  * When adding buttons using add_button(), clicking the button will emit
  * signal_response() with a "response id" you specified. You are encouraged
- * to use the Gtk::ResponseType enum. If a dialog receives a delete event,
- * the "response" signal will be emitted with a response id of
- * Gtk::ResponseType::DELETE_EVENT.
+ * to use the @ref Gtk::ResponseType_Wrapper::ResponseType "Gtk::ResponseType"
+ * enum (these all have values less than zero). If a dialog receives a delete
+ * event, the "response" signal will be emitted with a response id of
+ * @ref Gtk::ResponseType_Wrapper::ResponseType "Gtk::ResponseType::DELETE_EVENT".
+ *
+ * A “modal” dialog (that is, one which freezes the rest of the application
+ * from user input), can be created by calling Gtk::Window::set_modal() on the
+ * dialog. It is also possible to set the modal property in the constructor.
  *
  * @ingroup Dialogs
  */