[gtk/ebassi/gidocgen: 211/478] filechooserdialog: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit 9f46ed48018e82e6f248fe855987b8dc6cfaf99c
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 26 16:10:01 2021 -0500

    filechooserdialog: Convert docs

 gtk/gtkfilechooserdialog.c | 126 +++++++++++++++++++++------------------------
 1 file changed, 60 insertions(+), 66 deletions(-)
---
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index b571a46f1e..1e345412e8 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -40,33 +40,33 @@
 
 
 /**
- * SECTION:gtkfilechooserdialog
- * @Short_description: A file chooser dialog, suitable for “File Open” or “File Save” commands
- * @Title: GtkFileChooserDialog
- * @See_also: #GtkFileChooser, #GtkDialog, #GtkFileChooserNative
- *
- * #GtkFileChooserDialog is a dialog box suitable for use with
- * “File Open” or “File Save” commands.  This widget works by
- * putting a #GtkFileChooserWidget inside a #GtkDialog.  It exposes
- * the #GtkFileChooser interface, so you can use all of the
- * #GtkFileChooser functions on the file chooser dialog as well as
- * those for #GtkDialog.
- *
- * Note that #GtkFileChooserDialog does not have any methods of its
- * own.  Instead, you should use the functions that work on a
- * #GtkFileChooser.
+ * GtkFileChooserDialog:
+ *
+ * `GtkFileChooserDialog` is a dialog suitable for use with
+ * “File Open” or “File Save” commands.
+ *
+ * ![An example GtkFileChooserDialog](filechooser.png)
+ *
+ * This widget works by putting a [class@Gtk.FileChooserWidget]
+ * inside a [class@Gtk.Dialog]. It exposes the [iface@Gtk.FileChooser]
+ * interface, so you can use all of the [iface@Gtk.FileChooser] functions
+ * on the file chooser dialog as well as those for [class@Gtk.Dialog].
+ *
+ * Note that `GtkFileChooserDialog` does not have any methods of its
+ * own. Instead, you should use the functions that work on a
+ * [iface@Gtk.FileChooser].
  *
  * If you want to integrate well with the platform you should use the
- * #GtkFileChooserNative API, which will use a platform-specific
- * dialog if available and fall back to GtkFileChooserDialog
+ * [class@Gtk.FileChooserNative] API, which will use a platform-specific
+ * dialog if available and fall back to `GtkFileChooserDialog`
  * otherwise.
  *
- * ## Typical usage ## {#gtkfilechooser-typical-usage}
+ * ## Typical usage
  *
  * In the simplest of cases, you can the following code to use
- * #GtkFileChooserDialog to select a file for opening:
+ * `GtkFileChooserDialog` to select a file for opening:
  *
- * |[
+ * ```c
  * static void
  * on_open_response (GtkDialog *dialog,
  *                   int        response)
@@ -101,11 +101,11 @@
  *   g_signal_connect (dialog, "response",
  *                     G_CALLBACK (on_open_response),
  *                     NULL);
- * ]|
+ * ```
  *
  * To use a dialog for saving, you can use this:
  *
- * |[
+ * ```c
  * static void
  * on_save_response (GtkDialog *dialog,
  *                   int        response)
@@ -147,41 +147,36 @@
  *   g_signal_connect (dialog, "response",
  *                     G_CALLBACK (on_save_response),
  *                     NULL);
- * ]|
+ * ```
  *
- * ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up}
+ * ## Setting up a file chooser dialog
  *
- * There are various cases in which you may need to use a #GtkFileChooserDialog:
+ * There are various cases in which you may need to use a `GtkFileChooserDialog`:
  *
- * - To select a file for opening. Use #GTK_FILE_CHOOSER_ACTION_OPEN.
+ * - To select a file for opening, use %GTK_FILE_CHOOSER_ACTION_OPEN.
  *
- * - To save a file for the first time. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
- *   and suggest a name such as “Untitled” with gtk_file_chooser_set_current_name().
+ * - To save a file for the first time, use %GTK_FILE_CHOOSER_ACTION_SAVE,
+ *   and suggest a name such as “Untitled” with
+ *   [method@Gtk.FileChooser.set_current_name].
  *
- * - To save a file under a different name. Use #GTK_FILE_CHOOSER_ACTION_SAVE,
- *   and set the existing file with gtk_file_chooser_set_file().
+ * - To save a file under a different name, use %GTK_FILE_CHOOSER_ACTION_SAVE,
+ *   and set the existing file with [method@Gtk.FileChooser.set_file].
  *
- * - To choose a folder instead of a file. Use #GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
+ * - To choose a folder instead of a filem use %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
  *
- * Note that old versions of the file chooser’s documentation suggested
- * using gtk_file_chooser_set_current_folder() in various
- * situations, with the intention of letting the application
- * suggest a reasonable default folder.  This is no longer
- * considered to be a good policy, as now the file chooser is
- * able to make good suggestions on its own.  In general, you
- * should only cause the file chooser to show a specific folder
- * when it is appropriate to use gtk_file_chooser_set_file(),
- * i.e. when you are doing a Save As command and you already
- * have a file saved somewhere.
+ * In general, you should only cause the file chooser to show a specific
+ * folder when it is appropriate to use [method@Gtk,FileChooser.set_file],
+ * i.e. when you are doing a “Save As” command and you already have a file
+ * saved somewhere.
 
- * ## Response Codes ## {#gtkfilechooserdialog-responses}
+ * ## Response Codes
  *
- * #GtkFileChooserDialog inherits from #GtkDialog, so buttons that
- * go in its action area have response codes such as
- * #GTK_RESPONSE_ACCEPT and #GTK_RESPONSE_CANCEL.  For example, you
- * could call gtk_file_chooser_dialog_new() as follows:
+ * `GtkFileChooserDialog` inherits from [class@Gtk.Dialog], so buttons that
+ * go in its action area have response codes such as %GTK_RESPONSE_ACCEPT and
+ * %GTK_RESPONSE_CANCEL. For example, you could call
+ * [ctor Gtk FileChooserDialog new] as follows:
  *
- * |[
+ * ```c
  * GtkWidget *dialog;
  * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
  *
@@ -193,29 +188,27 @@
  *                                       _("_Open"),
  *                                       GTK_RESPONSE_ACCEPT,
  *                                       NULL);
- * ]|
+ * ```
  *
  * This will create buttons for “Cancel” and “Open” that use predefined
- * response identifiers from #GtkResponseType.  For most dialog
+ * response identifiers from [enum@Gtk.ResponseType].  For most dialog
  * boxes you can use your own custom response codes rather than the
- * ones in #GtkResponseType, but #GtkFileChooserDialog assumes that
+ * ones in [enum@Gtk.ResponseType], but `GtkFileChooserDialog` assumes that
  * its “accept”-type action, e.g. an “Open” or “Save” button,
  * will have one of the following response codes:
  *
- * - #GTK_RESPONSE_ACCEPT
- * - #GTK_RESPONSE_OK
- * - #GTK_RESPONSE_YES
- * - #GTK_RESPONSE_APPLY
+ * - %GTK_RESPONSE_ACCEPT
+ * - %GTK_RESPONSE_OK
+ * - %GTK_RESPONSE_YES
+ * - %GTK_RESPONSE_APPLY
  *
- * This is because #GtkFileChooserDialog must intercept responses
- * and switch to folders if appropriate, rather than letting the
- * dialog terminate — the implementation uses these known
- * response codes to know which responses can be blocked if
- * appropriate.
+ * This is because `GtkFileChooserDialog` must intercept responses and switch
+ * to folders if appropriate, rather than letting the dialog terminate — the
+ * implementation uses these known response codes to know which responses can
+ * be blocked if appropriate.
  *
- * To summarize, make sure you use a
- * [predefined response code][gtkfilechooserdialog-responses]
- * when you use #GtkFileChooserDialog to ensure proper operation.
+ * To summarize, make sure you use a predefined response code
+ * when you use `GtkFileChooserDialog` to ensure proper operation.
  */
 
 typedef struct _GtkFileChooserDialogPrivate GtkFileChooserDialogPrivate;
@@ -720,11 +713,12 @@ gtk_file_chooser_dialog_new_valist (const char           *title,
  * @first_button_text: (allow-none): text to go in the first button, or %NULL
  * @...: response ID for the first button, then additional (button, id) pairs, ending with %NULL
  *
- * Creates a new #GtkFileChooserDialog.  This function is analogous to
- * gtk_dialog_new_with_buttons().
+ * Creates a new `GtkFileChooserDialog`.
+ *
+ * This function is analogous to [ctor@Gtk.Dialog.new_with_buttons].
  *
- * Returns: a new #GtkFileChooserDialog
- **/
+ * Returns: a new `GtkFileChooserDialog`
+ */
 GtkWidget *
 gtk_file_chooser_dialog_new (const char           *title,
                              GtkWindow            *parent,