[gtk/ebassi/gidocgen: 209/471] nativedialog: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit f61650b4d144d968482eddccc85de0af8c4bd3b0
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 26 16:11:44 2021 -0500

    nativedialog: Convert docs

 gtk/gtknativedialog.c | 151 +++++++++++++++++++++++++-------------------------
 1 file changed, 77 insertions(+), 74 deletions(-)
---
diff --git a/gtk/gtknativedialog.c b/gtk/gtknativedialog.c
index 71cceb4f8c..972616905a 100644
--- a/gtk/gtknativedialog.c
+++ b/gtk/gtknativedialog.c
@@ -36,24 +36,22 @@
 #include "gtklabel.h"
 
 /**
- * SECTION:gtknativedialog
- * @Short_description: Integrate with native dialogs
- * @Title: GtkNativeDialog
- * @See_also: #GtkFileChooserNative, #GtkDialog
+ * GtkNativeDialog:
  *
- * Native dialogs are platform dialogs that don't use #GtkDialog or
- * #GtkWindow. They are used in order to integrate better with a
- * platform, by looking the same as other native applications and
- * supporting platform specific features.
+ * Native dialogs are platform dialogs that don't use `GtkDialog`.
  *
- * The #GtkDialog functions cannot be used on such objects, but we
- * need a similar API in order to drive them. The #GtkNativeDialog
+ * They are used in order to integrate better with a platform, by
+ * looking the same as other native applications and supporting
+ * platform specific features.
+ *
+ * The [class@Gtk.Dialog] functions cannot be used on such objects,
+ * but we need a similar API in order to drive them. The `GtkNativeDialog`
  * object is an API that allows you to do this. It allows you to set
  * various common properties on the dialog, as well as show and hide
- * it and get a #GtkNativeDialog::response signal when the user finished
- * with the dialog.
+ * it and get a [signal@Gtk.NativeDialog::response] signal when the user
+ * finished with the dialog.
  *
- * Note that unlike #GtkDialog, #GtkNativeDialog objects are not
+ * Note that unlike `GtkDialog`, `GtkNativeDialog` objects are not
  * toplevel widgets, and GTK does not keep them alive. It is your
  * responsibility to keep a reference until you are done with the
  * object.
@@ -205,7 +203,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
   gobject_class->dispose = gtk_native_dialog_dispose;
 
   /**
-   * GtkNativeDialog:title:
+   * GtkNativeDialog:title: (attributes org.gtk.Property.get=gtk_native_dialog_get_title 
org.gtk.Property.set=gtk_native_dialog_set_title)
    *
    * The title of the dialog window
    */
@@ -217,7 +215,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
                          GTK_PARAM_READWRITE);
 
   /**
-   * GtkNativeDialog:modal:
+   * GtkNativeDialog:modal: (attributes org.gtk.Property.get=gtk_native_dialog_get_modal 
org.gtk.Property.set=gtk_native_dialog_set_modal)
    *
    * Whether the window should be modal with respect to its transient parent.
    */
@@ -229,7 +227,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
                           GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkNativeDialog:visible:
+   * GtkNativeDialog:visible: (attributes org.gtk.Property.get=gtk_native_dialog_get_visible)
    *
    * Whether the window is currently visible.
    */
@@ -241,7 +239,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
                           GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkNativeDialog:transient-for:
+   * GtkNativeDialog:transient-for: (attributes org.gtk.Property.get=gtk_native_dialog_get_transient_for 
org.gtk.Property.set=gtk_native_dialog_set_transient_for)
    *
    * The transient parent of the dialog, or %NULL for none.
    */
@@ -263,8 +261,8 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class)
    *
    * When this is called the dialog has been hidden.
    *
-   * If you call gtk_native_dialog_hide() before the user responds to
-   * the dialog this signal will not be emitted.
+   * If you call [method Gtk NativeDialog hide] before the user
+   * responds to the dialog this signal will not be emitted.
    */
   native_signals[RESPONSE] =
     g_signal_new (I_("response"),
@@ -284,15 +282,16 @@ gtk_native_dialog_init (GtkNativeDialog *self)
 
 /**
  * gtk_native_dialog_show:
- * @self: a #GtkNativeDialog
+ * @self: a `GtkNativeDialog`
+ *
+ * Shows the dialog on the display.
  *
- * Shows the dialog on the display, allowing the user to interact with
- * it. When the user accepts the state of the dialog the dialog will
- * be automatically hidden and the #GtkNativeDialog::response signal
- * will be emitted.
+ * When the user accepts the state of the dialog the dialog will
+ * be automatically hidden and the [signal@Gtk.NativeDialog::response]
+ * signal will be emitted.
  *
  * Multiple calls while the dialog is visible will be ignored.
- **/
+ */
 void
 gtk_native_dialog_show (GtkNativeDialog *self)
 {
@@ -302,7 +301,7 @@ gtk_native_dialog_show (GtkNativeDialog *self)
   g_return_if_fail (GTK_IS_NATIVE_DIALOG (self));
 
   if (priv->visible)
-    return;
+   return;
 
   klass = GTK_NATIVE_DIALOG_GET_CLASS (self);
 
@@ -316,14 +315,16 @@ gtk_native_dialog_show (GtkNativeDialog *self)
 
 /**
  * gtk_native_dialog_hide:
- * @self: a #GtkNativeDialog
+ * @self: a `GtkNativeDialog`
  *
- * Hides the dialog if it is visilbe, aborting any interaction. Once this
- * is called the  #GtkNativeDialog::response signal will not be emitted
- * until after the next call to gtk_native_dialog_show().
+ * Hides the dialog if it is visible, aborting any interaction.
+ *
+ * Once this is called the [signal@Gtk.NativeDialog::response] signal
+ * will *not* be emitted until after the next call to
+ * [method Gtk NativeDialog show].
  *
  * If the dialog is not visible this does nothing.
- **/
+ */
 void
 gtk_native_dialog_hide (GtkNativeDialog *self)
 {
@@ -348,18 +349,20 @@ gtk_native_dialog_hide (GtkNativeDialog *self)
 
 /**
  * gtk_native_dialog_destroy:
- * @self: a #GtkNativeDialog
+ * @self: a `GtkNativeDialog`
  *
  * Destroys a dialog.
  *
  * When a dialog is destroyed, it will break any references it holds
- * to other objects. If it is visible it will be hidden and any underlying
- * window system resources will be destroyed.
+ * to other objects.
  *
- * Note that this does not release any reference to the object (as opposed to
- * destroying a GtkWindow) because there is no reference from the windowing
- * system to the #GtkNativeDialog.
- **/
+ * If it is visible it will be hidden and any underlying window system
+ * resources will be destroyed.
+ *
+ * Note that this does not release any reference to the object (as opposed
+ * to destroying a `GtkWindow`) because there is no reference from the
+ * windowing system to the `GtkNativeDialog`.
+ */
 void
 gtk_native_dialog_destroy (GtkNativeDialog *self)
 {
@@ -380,13 +383,13 @@ _gtk_native_dialog_emit_response (GtkNativeDialog *self,
 }
 
 /**
- * gtk_native_dialog_get_visible:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_get_visible: (attributes org.gtk.Method.get_property=visible)
+ * @self: a `GtkNativeDialog`
  *
  * Determines whether the dialog is visible.
  *
  * Returns: %TRUE if the dialog is visible
- **/
+ */
 gboolean
 gtk_native_dialog_get_visible (GtkNativeDialog *self)
 {
@@ -398,17 +401,18 @@ gtk_native_dialog_get_visible (GtkNativeDialog *self)
 }
 
 /**
- * gtk_native_dialog_set_modal:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_set_modal: (attributes org.gtk.Method.set_property=modal)
+ * @self: a `GtkNativeDialog`
  * @modal: whether the window is modal
  *
- * Sets a dialog modal or non-modal. Modal dialogs prevent interaction
- * with other windows in the same application. To keep modal dialogs
- * on top of main application windows, use
- * gtk_native_dialog_set_transient_for() to make the dialog transient for the
- * parent; most [window managers][gtk-X11-arch]
- * will then disallow lowering the dialog below the parent.
- **/
+ * Sets a dialog modal or non-modal.
+ *
+ * Modal dialogs prevent interaction with other windows in the same
+ * application. To keep modal dialogs on top of main application
+ * windows, use [method@Gtk.NativeDialog.set_transient_for] to make
+ * the dialog transient for the parent; most window managers will
+ * then disallow lowering the dialog below the parent.
+ */
 void
 gtk_native_dialog_set_modal (GtkNativeDialog *self,
                              gboolean modal)
@@ -427,13 +431,13 @@ gtk_native_dialog_set_modal (GtkNativeDialog *self,
 }
 
 /**
- * gtk_native_dialog_get_modal:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_get_modal: (attributes org.gtk.Method.get_property=modal)
+ * @self: a `GtkNativeDialog`
  *
- * Returns whether the dialog is modal. See gtk_native_dialog_set_modal().
+ * Returns whether the dialog is modal.
  *
  * Returns: %TRUE if the dialog is set to be modal
- **/
+ */
 gboolean
 gtk_native_dialog_get_modal (GtkNativeDialog *self)
 {
@@ -445,12 +449,12 @@ gtk_native_dialog_get_modal (GtkNativeDialog *self)
 }
 
 /**
- * gtk_native_dialog_set_title:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_set_title: (attributes org.gtk.Method.set_property=title)
+ * @self: a `GtkNativeDialog`
  * @title: title of the dialog
  *
- * Sets the title of the #GtkNativeDialog.
- **/
+ * Sets the title of the `GtkNativeDialog.`
+ */
 void
 gtk_native_dialog_set_title (GtkNativeDialog *self,
                                    const char *title)
@@ -466,15 +470,15 @@ gtk_native_dialog_set_title (GtkNativeDialog *self,
 }
 
 /**
- * gtk_native_dialog_get_title:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_get_title: (attributes org.gtk.Method.get_property=title)
+ * @self: a `GtkNativeDialog`
  *
- * Gets the title of the #GtkNativeDialog.
+ * Gets the title of the `GtkNativeDialog`.
  *
  * Returns: (nullable): the title of the dialog, or %NULL if none has
  *    been set explicitly. The returned string is owned by the widget
  *    and must not be modified or freed.
- **/
+ */
 const char *
 gtk_native_dialog_get_title (GtkNativeDialog *self)
 {
@@ -495,15 +499,15 @@ parent_destroyed (GtkWidget       *parent,
 }
 
 /**
- * gtk_native_dialog_set_transient_for:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_set_transient_for: (attributes org.gtk.Method.set_property=transient-for)
+ * @self: a `GtkNativeDialog`
  * @parent: (allow-none): parent window, or %NULL
  *
  * Dialog windows should be set transient for the main application
- * window they were spawned from. This allows
- * [window managers][gtk-X11-arch] to e.g. keep the
- * dialog on top of the main window, or center the dialog over the
- * main window.
+ * window they were spawned from.
+ *
+ * This allows window managers to e.g. keep the dialog on top of the
+ * main window, or center the dialog over the main window.
  *
  * Passing %NULL for @parent unsets the current transient window.
  */
@@ -530,15 +534,14 @@ gtk_native_dialog_set_transient_for (GtkNativeDialog *self,
 }
 
 /**
- * gtk_native_dialog_get_transient_for:
- * @self: a #GtkNativeDialog
+ * gtk_native_dialog_get_transient_for: (attributes org.gtk.Method.get_property=transient-for)
+ * @self: a `GtkNativeDialog`
  *
- * Fetches the transient parent for this window. See
- * gtk_native_dialog_set_transient_for().
+ * Fetches the transient parent for this window.
  *
  * Returns: (nullable) (transfer none): the transient parent for this window,
- * or %NULL if no transient parent has been set.
- **/
+ *   or %NULL if no transient parent has been set.
+ */
 GtkWindow *
 gtk_native_dialog_get_transient_for (GtkNativeDialog *self)
 {