[gtk/ebassi/gidocgen: 216/501] messagedialog: Convert docs




commit 9c9da051e700840b61fd5e9a9f21fc81aec85e6a
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Feb 25 23:22:36 2021 -0500

    messagedialog: Convert docs
    
    Convert link format, add an example image, add
    property annotations. General cleanup.

 gtk/gtkmessagedialog.c | 217 +++++++++++++++++++++++++------------------------
 gtk/gtkmessagedialog.h |   7 +-
 2 files changed, 116 insertions(+), 108 deletions(-)
---
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index af61f8cb55..df675d0191 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -38,62 +38,63 @@
 #include <string.h>
 
 /**
- * SECTION:gtkmessagedialog
- * @Short_description: A convenient message window
- * @Title: GtkMessageDialog
- * @See_also:#GtkDialog
+ * GtkMessageDialog:
  *
- * #GtkMessageDialog presents a dialog with some message text. It’s simply a
- * convenience widget; you could construct the equivalent of #GtkMessageDialog
- * from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
+ * `GtkMessageDialog` presents a dialog with some message text.
+ *
+ * ![An example GtkMessageDialog](messagedialog.png)
+ *
+ * It’s simply a convenience widget; you could construct the equivalent of
+ * `GtkMessageDialog` from `GtkDialog` without too much effort, but
+ * `GtkMessageDialog` saves typing.
  *
  * The easiest way to do a modal message dialog is to use the %GTK_DIALOG_MODAL
- * flag, which will call gtk_window_set_modal() internally. The dialog will
+ * flag, which will call [method@Gtk.Window.set_modal] internally. The dialog will
  * prevent interaction with the parent window until it's hidden or destroyed.
- * You can use the #GtkDialog::response signal to know when the user dismissed
- * the dialog.
+ * You can use the [signal@Gtk.Dialog::response] signal to know when the user
+ * dismissed the dialog.
  *
  * An example for using a modal dialog:
- * |[<!-- language="C" -->
- *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT | GTK_DIALOG_MODAL;
- *  dialog = gtk_message_dialog_new (parent_window,
- *                                   flags,
- *                                   GTK_MESSAGE_ERROR,
- *                                   GTK_BUTTONS_CLOSE,
- *                                   "Error reading “%s”: %s",
- *                                   filename,
- *                                   g_strerror (errno));
- *  // Destroy the dialog when the user responds to it
- *  // (e.g. clicks a button)
- *
- *  g_signal_connect (dialog, "response",
- *                    G_CALLBACK (gtk_window_destroy),
- *                    NULL);
- * ]|
- *
- * You might do a non-modal #GtkMessageDialog simply by omitting the
+ * ```c
+ * GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT | GTK_DIALOG_MODAL;
+ * dialog = gtk_message_dialog_new (parent_window,
+ *                                  flags,
+ *                                  GTK_MESSAGE_ERROR,
+ *                                  GTK_BUTTONS_CLOSE,
+ *                                  "Error reading “%s”: %s",
+ *                                  filename,
+ *                                  g_strerror (errno));
+ * // Destroy the dialog when the user responds to it
+ * // (e.g. clicks a button)
+ *
+ * g_signal_connect (dialog, "response",
+ *                   G_CALLBACK (gtk_window_destroy),
+ *                   NULL);
+ * ```
+ *
+ * You might do a non-modal `GtkMessageDialog` simply by omitting the
  * %GTK_DIALOG_MODAL flag:
  *
- * |[<!-- language="C" -->
- *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
- *  dialog = gtk_message_dialog_new (parent_window,
- *                                   flags,
- *                                   GTK_MESSAGE_ERROR,
- *                                   GTK_BUTTONS_CLOSE,
- *                                   "Error reading “%s”: %s",
- *                                   filename,
- *                                   g_strerror (errno));
- *
- *  // Destroy the dialog when the user responds to it
- *  // (e.g. clicks a button)
- *  g_signal_connect (dialog, "response",
- *                    G_CALLBACK (gtk_window_destroy),
- *                    NULL);
- * ]|
+ * ```c
+ * GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ * dialog = gtk_message_dialog_new (parent_window,
+ *                                  flags,
+ *                                  GTK_MESSAGE_ERROR,
+ *                                  GTK_BUTTONS_CLOSE,
+ *                                  "Error reading “%s”: %s",
+ *                                  filename,
+ *                                  g_strerror (errno));
+ *
+ * // Destroy the dialog when the user responds to it
+ * // (e.g. clicks a button)
+ * g_signal_connect (dialog, "response",
+ *                   G_CALLBACK (gtk_window_destroy),
+ *                   NULL);
+ * ```
  *
  * # GtkMessageDialog as GtkBuildable
  *
- * The GtkMessageDialog implementation of the GtkBuildable interface exposes
+ * The `GtkMessageDialog` implementation of the `GtkBuildable` interface exposes
  * the message area as an internal child with the name “message_area”.
  */
 
@@ -377,8 +378,9 @@ gtk_message_dialog_class_init (GtkMessageDialogClass *class)
   /**
    * GtkMessageDialog:text:
    *
-   * The primary text of the message dialog. If the dialog has
-   * a secondary text, this will appear as the title.
+   * The primary text of the message dialog.
+   *
+   * If the dialog has a secondary text, this will appear as the title.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_TEXT,
@@ -391,7 +393,8 @@ gtk_message_dialog_class_init (GtkMessageDialogClass *class)
    * GtkMessageDialog:use-markup:
    *
    * %TRUE if the primary text of the dialog includes Pango markup.
-   * See pango_parse_markup().
+   *
+   * See [func@Pango.parse_markup].
    */
   g_object_class_install_property (gobject_class,
                                    PROP_USE_MARKUP,
@@ -416,7 +419,8 @@ gtk_message_dialog_class_init (GtkMessageDialogClass *class)
    * GtkMessageDialog:secondary-use-markup:
    *
    * %TRUE if the secondary text of the dialog includes Pango markup.
-   * See pango_parse_markup().
+   *
+   * See [func@Pango.parse_markup].
    */
   g_object_class_install_property (gobject_class,
                                    PROP_SECONDARY_USE_MARKUP,
@@ -428,9 +432,10 @@ gtk_message_dialog_class_init (GtkMessageDialogClass *class)
   /**
    * GtkMessageDialog:message-area:
    *
-   * The #GtkBox that corresponds to the message area of this dialog.  See
-   * gtk_message_dialog_get_message_area() for a detailed description of this
-   * area.
+   * The `GtkBox` that corresponds to the message area of this dialog.
+   *
+   * See [method@Gtk.MessageDialog.get_message_area] for a detailed
+   * description of this area.
    */
   g_object_class_install_property (gobject_class,
                                    PROP_MESSAGE_AREA,
@@ -480,12 +485,14 @@ gtk_message_dialog_init (GtkMessageDialog *dialog)
  * @message_format: (allow-none): printf()-style format string, or %NULL
  * @...: arguments for @message_format
  *
- * Creates a new message dialog, which is a simple dialog with some text
- * the user may want to see. When the user clicks a button a “response”
- * signal is emitted with response IDs from #GtkResponseType. See
- * #GtkDialog for more details.
+ * Creates a new message dialog.
  *
- * Returns: (transfer none): a new #GtkMessageDialog
+ * This is a simple dialog with some text the user may want to see.
+ * When the user clicks a button a “response” signal is emitted with
+ * response IDs from [enum@Gtk.ResponseType]. See [class@Gtk.Dialog]
+ * for more details.
+ *
+ * Returns: (transfer none): a new `GtkMessageDialog`
  */
 GtkWidget*
 gtk_message_dialog_new (GtkWindow     *parent,
@@ -542,33 +549,36 @@ gtk_message_dialog_new (GtkWindow     *parent,
  * @message_format: (allow-none): printf()-style format string, or %NULL
  * @...: arguments for @message_format
  *
- * Creates a new message dialog, which is a simple dialog with some text that
- * is marked up with the [Pango text markup language][PangoMarkupFormat].
- * When the user clicks a button a “response” signal is emitted with
- * response IDs from #GtkResponseType. See #GtkDialog for more details.
+ * Creates a new message dialog.
+ *
+ * This is a simple dialog with some text that is marked up with
+ * Pango markup. When the user clicks a button a “response” signal
+ * is emitted with response IDs from [enum@Gtk.ResponseType]. See
+ * [class@Gtk.Dialog] for more details.
  *
  * Special XML characters in the printf() arguments passed to this
  * function will automatically be escaped as necessary.
  * (See g_markup_printf_escaped() for how this is implemented.)
  * Usually this is what you want, but if you have an existing
  * Pango markup string that you want to use literally as the
- * label, then you need to use gtk_message_dialog_set_markup()
+ * label, then you need to use [method@Gtk.MessageDialog.set_markup]
  * instead, since you can’t pass the markup string either
  * as the format (it might contain “%” characters) or as a string
  * argument.
- * |[<!-- language="C" -->
- *  GtkWidget *dialog;
- *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
- *  dialog = gtk_message_dialog_new (parent_window,
- *                                   flags,
- *                                   GTK_MESSAGE_ERROR,
- *                                   GTK_BUTTONS_CLOSE,
- *                                   NULL);
- *  gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog),
- *                                 markup);
- * ]|
- *
- * Returns: a new #GtkMessageDialog
+ *
+ * ```c
+ * GtkWidget *dialog;
+ * GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ * dialog = gtk_message_dialog_new (parent_window,
+ *                                  flags,
+ *                                  GTK_MESSAGE_ERROR,
+ *                                  GTK_BUTTONS_CLOSE,
+ *                                  NULL);
+ * gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog),
+ *                                markup);
+ * ```
+ *
+ * Returns: a new `GtkMessageDialog`
  **/
 GtkWidget*
 gtk_message_dialog_new_with_markup (GtkWindow     *parent,
@@ -602,12 +612,11 @@ gtk_message_dialog_new_with_markup (GtkWindow     *parent,
 
 /**
  * gtk_message_dialog_set_markup:
- * @message_dialog: a #GtkMessageDialog
- * @str: markup string (see [Pango markup format][PangoMarkupFormat])
+ * @message_dialog: a `GtkMessageDialog`
+ * @str: string with Pango markup
  *
- * Sets the text of the message dialog to be @str, which is marked
- * up with the [Pango text markup language][PangoMarkupFormat].
- **/
+ * Sets the text of the message dialog.
+ */
 void
 gtk_message_dialog_set_markup (GtkMessageDialog *message_dialog,
                                const char       *str)
@@ -622,12 +631,11 @@ gtk_message_dialog_set_markup (GtkMessageDialog *message_dialog,
 
 /**
  * gtk_message_dialog_format_secondary_text:
- * @message_dialog: a #GtkMessageDialog
+ * @message_dialog: a `GtkMessageDialog`
  * @message_format: (allow-none): printf()-style format string, or %NULL
  * @...: arguments for @message_format
  *
- * Sets the secondary text of the message dialog to be @message_format
- * (with printf()-style).
+ * Sets the secondary text of the message dialog.
  */
 void
 gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
@@ -664,28 +672,27 @@ gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
 
 /**
  * gtk_message_dialog_format_secondary_markup:
- * @message_dialog: a #GtkMessageDialog
- * @message_format: printf()-style markup string (see
-     [Pango markup format][PangoMarkupFormat]), or %NULL
+ * @message_dialog: a `GtkMessageDialog`
+ * @message_format: printf()-style string with Pango markup
  * @...: arguments for @message_format
  *
- * Sets the secondary text of the message dialog to be @message_format (with
- * printf()-style), which is marked up with the
- * [Pango text markup language][PangoMarkupFormat].
+ * Sets the secondary text of the message dialog.
  *
- * Due to an oversight, this function does not escape special XML characters
- * like gtk_message_dialog_new_with_markup() does. Thus, if the arguments
- * may contain special XML characters, you should use g_markup_printf_escaped()
- * to escape it.
-
- * |[<!-- language="C" -->
+ * The @message_format is assumed to contain Pango markup.
+ *
+ * Due to an oversight, this function does not escape special
+ * XML characters like [ctor@Gtk.MessageDialog.new_with_markup]
+ * does. Thus, if the arguments may contain special XML characters,
+ * you should use g_markup_printf_escaped() to escape it.
+ *
+ * ```c
  * char *msg;
  *
  * msg = g_markup_printf_escaped (message_format, ...);
  * gtk_message_dialog_format_secondary_markup (message_dialog,
  *                                             "%s", msg);
  * g_free (msg);
- * ]|
+ * ```
  */
 void
 gtk_message_dialog_format_secondary_markup (GtkMessageDialog *message_dialog,
@@ -722,17 +729,18 @@ gtk_message_dialog_format_secondary_markup (GtkMessageDialog *message_dialog,
 
 /**
  * gtk_message_dialog_get_message_area:
- * @message_dialog: a #GtkMessageDialog
+ * @message_dialog: a `GtkMessageDialog`
+ *
+ * Returns the message area of the dialog.
  *
- * Returns the message area of the dialog. This is the box where the
- * dialog’s primary and secondary labels are packed. You can add your
- * own extra content to that box and it will appear below those labels.
- * See gtk_dialog_get_content_area() for the corresponding
- * function in the parent #GtkDialog.
+ * This is the box where the dialog’s primary and secondary labels
+ * are packed. You can add your own extra content to that box and it
+ * will appear below those labels. See [method@Gtk.Dialog.get_content_area]
+ * for the corresponding function in the parent [class@Gtk.Dialog].
  *
- * Returns: (transfer none): A #GtkBox corresponding to the
+ * Returns: (transfer none): A `GtkBox` corresponding to the
  *     “message area” in the @message_dialog.
- **/
+ */
 GtkWidget *
 gtk_message_dialog_get_message_area (GtkMessageDialog *message_dialog)
 {
@@ -742,4 +750,3 @@ gtk_message_dialog_get_message_area (GtkMessageDialog *message_dialog)
 
   return priv->message_area;
 }
-
diff --git a/gtk/gtkmessagedialog.h b/gtk/gtkmessagedialog.h
index 4a1ababd74..ac4198bea3 100644
--- a/gtk/gtkmessagedialog.h
+++ b/gtk/gtkmessagedialog.h
@@ -56,9 +56,10 @@ struct _GtkMessageDialog
  * @GTK_BUTTONS_YES_NO: Yes and No buttons
  * @GTK_BUTTONS_OK_CANCEL: OK and Cancel buttons
  *
- * Prebuilt sets of buttons for the dialog. If
- * none of these choices are appropriate, simply use %GTK_BUTTONS_NONE
- * then call gtk_dialog_add_buttons().
+ * Prebuilt sets of buttons for `GtkDialog`.
+ *
+ * If none of these choices are appropriate, simply use
+ * %GTK_BUTTONS_NONE and call [method@Gtk.Dialog.add_buttons].
  *
  * > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO
  * > and %GTK_BUTTONS_OK_CANCEL are discouraged by the


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]