[gtk/ebassi/gidocgen: 184/465] dialog: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 563fa2f0ca37a894a67e36a53cc4070ace9d8c16
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 26 09:31:38 2021 -0500

    dialog: Convert docs
    
    Convert links, add an example image, generally clean up docs.

 gtk/gtkdialog.c | 270 +++++++++++++++++++++++++++++++-------------------------
 gtk/gtkdialog.h |  13 +--
 2 files changed, 153 insertions(+), 130 deletions(-)
---
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index ad8a1e3116..934bd681f8 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -45,51 +45,57 @@
 #include "gtksizegroup.h"
 
 /**
- * SECTION:gtkdialog
- * @Short_description: Create popup windows
- * @Title: GtkDialog
- * @See_also: #GtkWindow, #GtkMessageDialog
+ * GtkDialog:
  *
  * Dialogs are a convenient way to prompt the user for a small amount
- * of input, e.g. to display a message, ask a question, or anything else
+ * of input.
+ *
+ * ![An example GtkDialog](dialog.png)
+ *
+ * Typical uses are to display a message, ask a question, or anything else
  * that does not require extensive effort on the user’s part.
  *
- * The main area of a GtkDialog is called the "content area", and is yours
- * to populate with widgets such a #GtkLabel or #GtkEntry, to present
- * your information, questions, or tasks to the user. 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.
- * To add action widgets, use GtkDialog using gtk_dialog_new_with_buttons(),
- * gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
- * gtk_dialog_add_action_widget().
+ * The main area of a `GtkDialog` is called the "content area", and is yours
+ * to populate with widgets such a `GtkLabel` or `GtkEntry`, to present
+ * your information, questions, or tasks to the user.
+ *
+ * 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. To add action widgets, create your `GtkDialog` using
+ * [ctor@Gtk.Dialog.new_with_buttons], or use
+ * [method@Gtk.Dialog.add_button], [method@Gtk.Dialog.add_buttons],
+ * or [method@Gtk.Dialog.add_action_widget].
+ *
+ * `GtkDialogs` uses some heuristics to decide whether to add a close
+ * button to the window decorations. If any of the action buttons use
+ * the response ID %GTK_RESPONSE_CLOSE or %GTK_RESPONSE_CANCEL, the
+ * close button is omitted.
  *
  * Clicking a button that was added as an action widget will emit the
- * #GtkDialog::response signal with a response ID that you specified.
+ * [signal@Gtk.Dialog::response] signal with a response ID that you specified.
  * GTK will never assign a meaning to positive response IDs; these are
  * entirely user-defined. But for convenience, you can use the response
- * IDs in the #GtkResponseType enumeration (these all have values less
- * than zero). If a dialog receives a delete event, the
- * #GtkDialog::response signal will be emitted with the
- * #GTK_RESPONSE_DELETE_EVENT response ID.
+ * IDs in the [enum@Gtk.ResponseType] enumeration (these all have values
+ * less than zero). If a dialog receives a delete event, the
+ * [signal@Gtk.Dialog::response] signal will be emitted with the
+ * %GTK_RESPONSE_DELETE_EVENT response ID.
  *
- * Dialogs are created with a call to gtk_dialog_new() or
- * gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is
- * recommended; it allows you to set the dialog title, some convenient
- * flags, and add simple buttons.
+ * Dialogs are created with a call to [ctor Gtk Dialog new] or
+ * [ctor@Gtk.Dialog.new_with_buttons]. The latter is recommended; it allows
+ * you to set the dialog title, some convenient flags, and add buttons.
  *
  * 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. Use the GTK_WINDOW() macro to cast the widget returned from
- * gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons()
- * you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal.
+ * from user input), can be created by calling [method@Gtk.Window.set_modal]
+ * on the dialog. When using [ctor@Gtk.Dialog.new_with_buttons], you can also
+ * pass the %GTK_DIALOG_MODAL flag to make a dialog modal.
  *
- * For the simple dialog in the following example, a #GtkMessageDialog would
- * save some effort. But you’d need to create the dialog contents manually if
- * you had more than a simple message in the dialog.
+ * For the simple dialog in the following example, a [class@Gtk.MessageDialog]
+ * would save some effort. But you’d need to create the dialog contents manually
+ * if you had more than a simple message in the dialog.
  *
- * An example for simple GtkDialog usage:
- * |[<!-- language="C" -->
+ * An example for simple `GtkDialog` usage:
+ * ```c
  * // Function to open a dialog box with a message
  * void
  * quick_message (GtkWindow *parent, char *message)
@@ -120,28 +126,28 @@
  *  gtk_box_append (GTK_BOX (content_area), label);
  *  gtk_widget_show (dialog);
  * }
- * ]|
+ * ```
  *
  * # GtkDialog as GtkBuildable
  *
- * The GtkDialog implementation of the #GtkBuildable interface exposes the
+ * The `GtkDialog` implementation of the `GtkBuildable` interface exposes the
  * @content_area as an internal child with the name “content_area”.
  *
- * GtkDialog supports a custom <action-widgets> element, which can contain
+ * `GtkDialog` supports a custom <action-widgets> element, which can contain
  * multiple <action-widget> elements. The “response” attribute specifies a
  * numeric response, and the content of the element is the id of widget
  * (which should be a child of the dialogs @action_area). To mark a response
  * as default, set the “default“ attribute of the <action-widget> element
  * to true.
  *
- * GtkDialog supports adding action widgets by specifying “action“ as
+ * `GtkDialog` supports adding action widgets by specifying “action“ as
  * the “type“ attribute of a <child> element. The widget will be added
  * either to the action area or the headerbar of the dialog, depending
  * on the “use-header-bar“ property. The response id has to be associated
  * with the action widget using the <action-widgets> element.
  *
  * An example of a #GtkDialog UI definition fragment:
- * |[
+ * ```xml
  * <object class="GtkDialog" id="dialog1">
  *   <child type="action">
  *     <object class="GtkButton" id="button_cancel"/>
@@ -155,11 +161,11 @@
  *     <action-widget response="ok" default="true">button_ok</action-widget>
  *   </action-widgets>
  * </object>
- * ]|
+ * ```
  *
  * # Accessibility
  *
- * GtkDialog uses the #GTK_ACCESSIBLE_ROLE_DIALOG role.
+ * `GtkDialog` uses the %GTK_ACCESSIBLE_ROLE_DIALOG role.
  */
 
 typedef struct _ResponseData ResponseData;
@@ -496,9 +502,11 @@ gtk_dialog_class_init (GtkDialogClass *class)
    * @dialog: the object on which the signal is emitted
    * @response_id: the response ID
    *
-   * Emitted when an action widget is clicked, the dialog receives a
-   * delete event, or the application programmer calls gtk_dialog_response().
-   * On a delete event, the response ID is #GTK_RESPONSE_DELETE_EVENT.
+   * Emitted when an action widget is clicked.
+   *
+   * The signal is also emitted when the dialog receives a
+   * delete event, and when [method@Gtk.Dialog.response] is called.
+   * On a delete event, the response ID is %GTK_RESPONSE_DELETE_EVENT.
    * Otherwise, it depends on which action widget was clicked.
    */
   dialog_signals[RESPONSE] =
@@ -514,10 +522,9 @@ gtk_dialog_class_init (GtkDialogClass *class)
   /**
    * GtkDialog::close:
    *
-   * The ::close signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user uses a keybinding to close
-   * the dialog.
+   * Emitted when the user uses a keybinding to close the dialog.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default binding for this signal is the Escape key.
    */
@@ -533,11 +540,24 @@ gtk_dialog_class_init (GtkDialogClass *class)
   /**
    * GtkDialog:use-header-bar:
    *
-   * %TRUE if the dialog uses a #GtkHeaderBar for action buttons
+   * %TRUE if the dialog uses a headerbar for action buttons
    * instead of the action-area.
    *
    * For technical reasons, this property is declared as an integer
    * property, but you should only set it to %TRUE or %FALSE.
+   *
+   * ## Creating a dialog with headerbar
+   *
+   * Builtin `GtkDialog` subclasses such as [class@Gtk.ColorChooserDialog]
+   * set this property according to platform conventions (using the
+   * [property@Gtk.Settings:gtk-dialogs-use-header] setting).
+   *
+   * Here is how you can achieve the same:
+   *
+   * ```c
+   * g_object_get (settings, "gtk-dialogs-use-header", &header, NULL);
+   * dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL);
+   * ```
    */
   g_object_class_install_property (gobject_class,
                                    PROP_USE_HEADER_BAR,
@@ -664,10 +684,11 @@ gtk_dialog_close (GtkDialog *dialog)
  *
  * Creates a new dialog box.
  *
- * Widgets should not be packed into this #GtkWindow
- * directly, but into the @content_area and @action_area, as described above.
+ * Widgets should not be packed into the `GtkWindow`
+ * directly, but into the @content_area and @action_area,
+ * as described above.
  *
- * Returns: the new dialog as a #GtkWidget
+ * Returns: the new dialog as a `GtkWidget`
  */
 GtkWidget*
 gtk_dialog_new (void)
@@ -705,44 +726,45 @@ gtk_dialog_new_empty (const char      *title,
  * gtk_dialog_new_with_buttons:
  * @title: (allow-none): Title of the dialog, or %NULL
  * @parent: (allow-none): Transient parent of the dialog, or %NULL
- * @flags: from #GtkDialogFlags
+ * @flags: from `GtkDialogFlags`
  * @first_button_text: (allow-none): text to go in first button, or %NULL
  * @...: response ID for first button, then additional buttons, ending with %NULL
  *
- * Creates a new #GtkDialog with title @title (or %NULL for the default
- * title; see gtk_window_set_title()) and transient parent @parent (or
- * %NULL for none; see gtk_window_set_transient_for()). The @flags
- * argument can be used to make the dialog modal (#GTK_DIALOG_MODAL)
- * and/or to have it destroyed along with its transient parent
- * (#GTK_DIALOG_DESTROY_WITH_PARENT). After @flags, button
- * text/response ID pairs should be listed, with a %NULL pointer ending
- * the list. Button text can be arbitrary text. A response ID can be
- * any positive number, or one of the values in the #GtkResponseType
- * enumeration. If the user clicks one of these dialog buttons,
- * #GtkDialog will emit the #GtkDialog::response signal with the corresponding
- * response ID. If a #GtkDialog receives a delete event,
- * it will emit ::response with a response ID of #GTK_RESPONSE_DELETE_EVENT.
+ * Creates a new `GtkDialog` with the given title and transient parent.
+ *
+ * The @flags argument can be used to make the dialog modal, have it
+ * destroyed along with its transient parent, or make it use a headerbar.
+ *
+ * Button text/response ID pairs should be listed in pairs, with a %NULL
+ * pointer ending the list. Button text can be arbitrary text. A response
+ * ID can be any positive number, or one of the values in the
+ * [enum@Gtk.ResponseType] enumeration. If the user clicks one of these
+ * buttons, `GtkDialog` will emit the [signal@Gtk.Dialog::response] signal
+ * with the corresponding response ID.
+ *
+ * If a `GtkDialog` receives a delete event, it will emit ::response with a
+ * response ID of %GTK_RESPONSE_DELETE_EVENT.
+ *
  * However, destroying a dialog does not emit the ::response signal;
  * so be careful relying on ::response when using the
- * #GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right,
- * so the first button in the list will be the leftmost button in the dialog.
+ * %GTK_DIALOG_DESTROY_WITH_PARENT flag.
  *
  * Here’s a simple example:
- * |[<!-- language="C" -->
- *  GtkWindow *main_app_window; // Window the dialog should show up on
- *  GtkWidget *dialog;
- *  GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
- *  dialog = gtk_dialog_new_with_buttons ("My dialog",
- *                                        main_app_window,
- *                                        flags,
- *                                        _("_OK"),
- *                                        GTK_RESPONSE_ACCEPT,
- *                                        _("_Cancel"),
- *                                        GTK_RESPONSE_REJECT,
- *                                        NULL);
- * ]|
+ * ```c
+ * GtkWindow *main_app_window; // Window the dialog should show up on
+ * GtkWidget *dialog;
+ * GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT;
+ * dialog = gtk_dialog_new_with_buttons ("My dialog",
+ *                                       main_app_window,
+ *                                       flags,
+ *                                       _("_OK"),
+ *                                       GTK_RESPONSE_ACCEPT,
+ *                                       _("_Cancel"),
+ *                                       GTK_RESPONSE_REJECT,
+ *                                       NULL);
+ * ```
  *
- * Returns: a new #GtkDialog
+ * Returns: a new `GtkDialog`
  */
 GtkWidget*
 gtk_dialog_new_with_buttons (const char     *title,
@@ -821,17 +843,20 @@ get_response_data (GtkDialog *dialog,
 
 /**
  * gtk_dialog_add_action_widget:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @child: an activatable widget
  * @response_id: response ID for @child
  *
- * Adds an activatable widget to the action area of a #GtkDialog,
- * connecting a signal handler that will emit the #GtkDialog::response
- * signal on the dialog when the widget is activated. The widget is
- * appended to the end of the dialog’s action area. If you want to add a
- * non-activatable widget, simply pack it into the @action_area field
- * of the #GtkDialog struct.
- **/
+ * Adds an activatable widget to the action area of a `GtkDialog`.
+ *
+ * GTK connects a signal handler that will emit the
+ * [signal@Gtk.Dialog::response] signal on the dialog when the widget
+ * is activated. The widget is appended to the end of the dialog’s action
+ * area.
+ *
+ * If you want to add a non-activatable widget, simply pack it into
+ * the @action_area field of the `GtkDialog` struct.
+ */
 void
 gtk_dialog_add_action_widget (GtkDialog *dialog,
                               GtkWidget *child,
@@ -860,18 +885,19 @@ gtk_dialog_add_action_widget (GtkDialog *dialog,
 
 /**
  * gtk_dialog_add_button:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @button_text: text of button
  * @response_id: response ID for the button
  *
- * Adds a button with the given text and sets things up so that
- * clicking the button will emit the #GtkDialog::response signal with
- * the given @response_id. The button is appended to the end of the
- * dialog’s action area. The button widget is returned, but usually
- * you don’t need it.
+ * Adds a button with the given text.
  *
- * Returns: (transfer none): the #GtkButton widget that was added
- **/
+ * GTK arranges things so that clicking the button will emit the
+ * [signal@Gtk.Dialog::response] signal with the given @response_id.
+ * The button is appended to the end of the dialog’s action area.
+ * The button widget is returned, but usually you don’t need it.
+ *
+ * Returns: (transfer none): the `GtkButton` widget that was added
+ */
 GtkWidget*
 gtk_dialog_add_button (GtkDialog   *dialog,
                        const char *button_text,
@@ -919,13 +945,15 @@ gtk_dialog_add_buttons_valist (GtkDialog      *dialog,
 
 /**
  * gtk_dialog_add_buttons:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @first_button_text: button text
  * @...: response ID for first button, then more text-response_id pairs
  *
- * Adds more buttons, same as calling gtk_dialog_add_button()
- * repeatedly.  The variable argument list should be %NULL-terminated
- * as with gtk_dialog_new_with_buttons(). Each button must have both
+ * Adds multiple buttons.
+ *
+ * This is the same as calling [method@Gtk.Dialog.add_button]
+ * repeatedly. The variable argument list should be %NULL-terminated
+ * as with [new@Gtk.Dialog.new_with_buttons]. Each button must have both
  * text and response ID.
  */
 void
@@ -946,14 +974,15 @@ gtk_dialog_add_buttons (GtkDialog   *dialog,
 
 /**
  * gtk_dialog_set_response_sensitive:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @response_id: a response ID
  * @setting: %TRUE for sensitive
  *
+ * A convenient way to sensitize/desensitize dialog buttons.
+ *
  * Calls `gtk_widget_set_sensitive (widget, @setting)`
  * for each widget in the dialog’s action area with the given @response_id.
- * A convenient way to sensitize/desensitize dialog buttons.
- **/
+ */
 void
 gtk_dialog_set_response_sensitive (GtkDialog *dialog,
                                    int        response_id,
@@ -973,13 +1002,13 @@ gtk_dialog_set_response_sensitive (GtkDialog *dialog,
 
 /**
  * gtk_dialog_set_default_response:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @response_id: a response ID
  *
- * Sets the last widget in the dialog’s action area with the given @response_id
- * as the default widget for the dialog. Pressing “Enter” normally activates
- * the default widget.
- **/
+ * Sets the default widget for the dialog based on the response ID.
+ *
+ * Pressing “Enter” normally activates the default widget.
+ */
 void
 gtk_dialog_set_default_response (GtkDialog *dialog,
                                  int        response_id)
@@ -1000,14 +1029,14 @@ gtk_dialog_set_default_response (GtkDialog *dialog,
 }
 
 /**
- * gtk_dialog_response:
- * @dialog: a #GtkDialog
+ * gtk_dialog_response: (attributes org.gtk.Method.signal=response)
+ * @dialog: a `GtkDialog`
  * @response_id: response ID
  *
- * Emits the #GtkDialog::response signal with the given response ID.
+ * Emits the ::response signal with the given response ID.
  *
  * Used to indicate that the user has responded to the dialog in some way.
- **/
+ */
 void
 gtk_dialog_response (GtkDialog *dialog,
                      int        response_id)
@@ -1022,7 +1051,7 @@ gtk_dialog_response (GtkDialog *dialog,
 
 /**
  * gtk_dialog_get_widget_for_response:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @response_id: the response ID used by the @dialog widget
  *
  * Gets the widget button that uses the given response ID in the action area
@@ -1051,7 +1080,7 @@ gtk_dialog_get_widget_for_response (GtkDialog *dialog,
 
 /**
  * gtk_dialog_get_response_for_widget:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  * @widget: a widget in the action area of @dialog
  *
  * Gets the response id of a widget in the action area
@@ -1360,11 +1389,12 @@ gtk_dialog_get_action_area (GtkDialog *dialog)
 
 /**
  * gtk_dialog_get_header_bar:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  *
- * Returns the header bar of @dialog. Note that the
- * headerbar is only used by the dialog if the
- * #GtkDialog:use-header-bar property is %TRUE.
+ * Returns the header bar of @dialog.
+ *
+ * Note that the headerbar is only used by the dialog if the
+ * [property@Gtk.Dialog:use-header-bar] property is %TRUE.
  *
  * Returns: (type Gtk.HeaderBar) (transfer none): the header bar
  */
@@ -1380,12 +1410,12 @@ gtk_dialog_get_header_bar (GtkDialog *dialog)
 
 /**
  * gtk_dialog_get_content_area:
- * @dialog: a #GtkDialog
+ * @dialog: a `GtkDialog`
  *
  * Returns the content area of @dialog.
  *
  * Returns: (type Gtk.Box) (transfer none): the content area #GtkBox.
- **/
+ */
 GtkWidget *
 gtk_dialog_get_content_area (GtkDialog *dialog)
 {
diff --git a/gtk/gtkdialog.h b/gtk/gtkdialog.h
index 3656d26157..b23c42ba13 100644
--- a/gtk/gtkdialog.h
+++ b/gtk/gtkdialog.h
@@ -35,10 +35,8 @@ G_BEGIN_DECLS
 
 /**
  * GtkDialogFlags:
- * @GTK_DIALOG_MODAL: Make the constructed dialog modal,
- *     see gtk_window_set_modal()
- * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its
- *     parent is destroyed, see gtk_window_set_destroy_with_parent()
+ * @GTK_DIALOG_MODAL: Make the constructed dialog modal
+ * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its parent is destroyed
  * @GTK_DIALOG_USE_HEADER_BAR: Create dialog with actions in header
  *     bar instead of action area
  *
@@ -67,6 +65,7 @@ typedef enum
  * @GTK_RESPONSE_HELP: Returned by Help buttons in GTK dialogs
  *
  * Predefined values for use as response ids in gtk_dialog_add_button().
+ *
  * All predefined values are negative; GTK leaves values of 0 or greater for
  * application-defined response ids.
  */
@@ -97,12 +96,6 @@ typedef enum
 typedef struct _GtkDialog              GtkDialog;
 typedef struct _GtkDialogClass         GtkDialogClass;
 
-/**
- * GtkDialog:
- *
- * The #GtkDialog-struct contains only private fields
- * and should not be directly accessed.
- */
 struct _GtkDialog
 {
   GtkWindow parent_instance;