[gtk/ebassi/gidocgen: 213/481] filechooser: Convert docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 213/481] filechooser: Convert docs
Date: Sun, 7 Mar 2021 23:55:09 +0000 (UTC)

commit 8df47bda4cdd744d7f2ed6e2da30b7b9169dedd9
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 26 16:09:23 2021 -0500

    filechooser: Convert docs

 gtk/gtkfilechooser.c | 403 ++++++++++++++++++++++++++++-----------------------
 gtk/gtkfilechooser.h |   6 +-
 2 files changed, 222 insertions(+), 187 deletions(-)
---
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index d7eaae85b7..3fabd9acd1 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -26,19 +26,19 @@
 
 
 /**
- * SECTION:gtkfilechooser
- * @Short_description: File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog
- * @Title: GtkFileChooser
- * @See_also: #GtkFileChooserDialog, #GtkFileChooserWidget
- *
- * #GtkFileChooser is an interface that can be implemented by file
- * selection widgets.  In GTK, the main objects that implement this
- * interface are #GtkFileChooserWidget and #GtkFileChooserDialog.  You do not
- * need to write an object that implements the #GtkFileChooser interface
- * unless you are trying to adapt an existing file selector to expose a
- * standard programming interface.
- *
- * #GtkFileChooser allows for shortcuts to various places in the filesystem.
+ * GtkFileChooser:
+ *
+ * `GtkFileChooser` is an interface that can be implemented by file
+ * selection widgets.
+ *
+ * In GTK, the main objects that implement this interface are
+ * [class@Gtk.FileChooserWidget] and [class@Gtk.FileChooserDialog].
+ *
+ * You do not need to write an object that implements the `GtkFileChooser`
+ * interface unless you are trying to adapt an existing file selector to
+ * expose a standard programming interface.
+ *
+ * `GtkFileChooser` allows for shortcuts to various places in the filesystem.
  * In the default implementation these are displayed in the left pane. It
  * may be a bit confusing at first that these shortcuts come from various
  * sources and in various flavours, so lets explain the terminology here:
@@ -56,15 +56,14 @@
  *
  * # File Names and Encodings
  *
- * When the user is finished selecting files in a
- * #GtkFileChooser, your program can get the selected filenames as
- * #GFiles.
+ * When the user is finished selecting files in a `GtkFileChooser`, your
+ * program can get the selected filenames as `GFile`s.
  *
- * # Adding options 
+ * # Adding options
  *
  * You can add extra widgets to a file chooser to provide options
  * that are not present in the default design, by using
- * gtk_file_chooser_add_choice(). Each choice has an identifier and
+ * [method@Gtk.FileChooser.add_choice]. Each choice has an identifier and
  * a user visible label; additionally, each choice can have multiple
  * options. If a choice has no option, it will be rendered as a
  * check button with the given label; if a choice has options, it will
@@ -78,6 +77,11 @@ G_DEFINE_INTERFACE (GtkFileChooser, gtk_file_chooser, G_TYPE_OBJECT);
 static void
 gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
 {
+  /**
+   * GtkFileChooser:action: (attributes org.gtk.Property.get=gtk_file_chooser_get_action 
org.gtk.Property.set=gtk_file_chooser_set_action)
+   *
+   * The type of operation that the file chooser is performing.
+   */
   g_object_interface_install_property (iface,
                                        g_param_spec_enum ("action",
                                                           P_("Action"),
@@ -85,12 +89,25 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
                                                           GTK_TYPE_FILE_CHOOSER_ACTION,
                                                           GTK_FILE_CHOOSER_ACTION_OPEN,
                                                           GTK_PARAM_READWRITE));
+
+
+  /**
+   * GtkFileChooser:filter: (attributes org.gtk.Property.get=gtk_file_chooser_get_filter 
org.gtk.Property.set=gtk_file_chooser_set_filter)
+   *
+   * The current filter for selecting files that are displayed.
+   */
   g_object_interface_install_property (iface,
                                        g_param_spec_object ("filter",
                                                             P_("Filter"),
                                                             P_("The current filter for selecting which files 
are displayed"),
                                                             GTK_TYPE_FILE_FILTER,
                                                             GTK_PARAM_READWRITE));
+
+  /**
+   * GtkFileChooser:select-multiple: (attributes org.gtk.Property.get=gtk_file_chooser_get_select_multiple 
org.gtk.Property.set=gtk_file_chooser_set_select_multiple)
+   *
+   * Whether to allow multiple files to be selected.
+   */
   g_object_interface_install_property (iface,
                                        g_param_spec_boolean ("select-multiple",
                                                              P_("Select Multiple"),
@@ -99,9 +116,9 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
                                                              GTK_PARAM_READWRITE));
 
   /**
-   * GtkFileChooser:filters:
+   * GtkFileChooser:filters: (attributes org.gtk.Property.get=gtk_file_chooser_get_filters)
    *
-   * A #GListModel containing the filters that have been
+   * A `GListModel` containing the filters that have been
    * added with gtk_file_chooser_add_filter().
    *
    * The returned object should not be modified. It may
@@ -115,9 +132,9 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
                                                           GTK_PARAM_READABLE));
 
   /**
-   * GtkFileChooser:shortcut-folders:
+   * GtkFileChooser:shortcut-folders: (attributes org.gtk.Property.get=gtk_file_chooser_get_shortcut_folders)
    *
-   * A #GListModel containing the shortcut folders that have been
+   * A `GListModel` containing the shortcut folders that have been
    * added with gtk_file_chooser_add_shortcut_folder().
    *
    * The returned object should not be modified. It may
@@ -131,8 +148,8 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
                                                           GTK_PARAM_READABLE));
 
   /**
-   * GtkFileChooser:create-folders:
-   * 
+   * GtkFileChooser:create-folders: (attributes org.gtk.Property.get=gtk_file_chooser_get_create_folders 
org.gtk.Property.set=gtk_file_chooser_set_create_folders)
+   *
    * Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode
    * will offer the user to create new folders.
    */
@@ -148,9 +165,9 @@ gtk_file_chooser_default_init (GtkFileChooserInterface *iface)
 /**
  * gtk_file_chooser_error_quark:
  *
- * Registers an error quark for #GtkFileChooser if necessary.
+ * Registers an error quark for `GtkFileChooser` errors.
  * 
- * Returns: The error quark used for #GtkFileChooser errors.
+ * Returns: The error quark used for `GtkFileChooser` errors.
  **/
 GQuark
 gtk_file_chooser_error_quark (void)
@@ -159,15 +176,17 @@ gtk_file_chooser_error_quark (void)
 }
 
 /**
- * gtk_file_chooser_set_action:
- * @chooser: a #GtkFileChooser
+ * gtk_file_chooser_set_action: (attributes org.gtk.Method.set_property=action)
+ * @chooser: a `GtkFileChooser`
  * @action: the action that the file selector is performing
- * 
- * Sets the type of operation that the chooser is performing; the
- * user interface is adapted to suit the selected action. For example,
- * an option to create a new folder might be shown if the action is
- * %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is
- * %GTK_FILE_CHOOSER_ACTION_OPEN.
+ *
+ * Sets the type of operation that the chooser is performing.
+ *
+ * The user interface is adapted to suit the selected action.
+ *
+ * For example, an option to create a new folder might be shown
+ * if the action is %GTK_FILE_CHOOSER_ACTION_SAVE but not if the
+ * action is %GTK_FILE_CHOOSER_ACTION_OPEN.
  **/
 void
 gtk_file_chooser_set_action (GtkFileChooser       *chooser,
@@ -179,14 +198,13 @@ gtk_file_chooser_set_action (GtkFileChooser       *chooser,
 }
 
 /**
- * gtk_file_chooser_get_action:
- * @chooser: a #GtkFileChooser
- * 
- * Gets the type of operation that the file chooser is performing; see
- * gtk_file_chooser_set_action().
- * 
+ * gtk_file_chooser_get_action: (attributes org.gtk.Method.get_property=action)
+ * @chooser: a `GtkFileChooser`
+ *
+ * Gets the type of operation that the file chooser is performing.
+ *
  * Returns: the action that the file selector is performing
- **/
+ */
 GtkFileChooserAction
 gtk_file_chooser_get_action (GtkFileChooser *chooser)
 {
@@ -200,14 +218,16 @@ gtk_file_chooser_get_action (GtkFileChooser *chooser)
 }
 
 /**
- * gtk_file_chooser_set_select_multiple:
- * @chooser: a #GtkFileChooser
+ * gtk_file_chooser_set_select_multiple: (attributes org.gtk.Method.set_property=select-multiple)
+ * @chooser: a `GtkFileChooser`
  * @select_multiple: %TRUE if multiple files can be selected.
- * 
- * Sets whether multiple files can be selected in the file selector.  This is
- * only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or
+ *
+ * Sets whether multiple files can be selected in the file chooser.
+ *
+ * This is only relevant if the action is set to be
+ * %GTK_FILE_CHOOSER_ACTION_OPEN or
  * %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.
- **/
+ */
 void
 gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
                                       gboolean        select_multiple)
@@ -218,14 +238,14 @@ gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
 }
 
 /**
- * gtk_file_chooser_get_select_multiple:
- * @chooser: a #GtkFileChooser
- * 
+ * gtk_file_chooser_get_select_multiple: (attributes org.gtk.Method.get_property=select-multiple)
+ * @chooser: a `GtkFileChooser`
+ *
  * Gets whether multiple files can be selected in the file
- * selector. See gtk_file_chooser_set_select_multiple().
- * 
+ * chooser.
+ *
  * Returns: %TRUE if multiple files can be selected.
- **/
+ */
 gboolean
 gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
 {
@@ -239,14 +259,15 @@ gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
 }
 
 /**
- * gtk_file_chooser_set_create_folders:
- * @chooser: a #GtkFileChooser
+ * gtk_file_chooser_set_create_folders: (attributes org.gtk.Method.set_property=create-folders)
+ * @chooser: a `GtkFileChooser`
  * @create_folders: %TRUE if the Create Folder button should be displayed
- * 
+ *
  * Sets whether file chooser will offer to create new folders.
- * This is only relevant if the action is not set to be 
+ *
+ * This is only relevant if the action is not set to be
  * %GTK_FILE_CHOOSER_ACTION_OPEN.
- **/
+ */
 void
 gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
                                      gboolean        create_folders)
@@ -257,14 +278,13 @@ gtk_file_chooser_set_create_folders (GtkFileChooser *chooser,
 }
 
 /**
- * gtk_file_chooser_get_create_folders:
- * @chooser: a #GtkFileChooser
- * 
+ * gtk_file_chooser_get_create_folders: (attributes org.gtk.Method.get_property=create-folders)
+ * @chooser: a `GtkFileChooser`
+ *
  * Gets whether file chooser will offer to create new folders.
- * See gtk_file_chooser_set_create_folders().
- * 
+ *
  * Returns: %TRUE if the Create Folder button should be displayed.
- **/
+ */
 gboolean
 gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
 {
@@ -279,20 +299,22 @@ gtk_file_chooser_get_create_folders (GtkFileChooser *chooser)
 
 /**
  * gtk_file_chooser_set_current_name:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  * @name: (type utf8): the filename to use, as a UTF-8 string
- * 
+ *
  * Sets the current name in the file selector, as if entered
- * by the user. Note that the name passed in here is a UTF-8
- * string rather than a filename. This function is meant for
- * such uses as a suggested name in a “Save As...” dialog.  You can
- * pass “Untitled.doc” or a similarly suitable suggestion for the @name.
+ * by the user.
+ *
+ * Note that the name passed in here is a UTF-8 string rather
+ * than a filename. This function is meant for such uses as a
+ * suggested name in a “Save As...” dialog.  You can pass
+ * “Untitled.doc” or a similarly suitable suggestion for the @name.
  *
- * If you want to preselect a particular existing file, you should use
- * gtk_file_chooser_set_file() instead.
+ * If you want to preselect a particular existing file, you should
+ * use [method@Gtk.FileChooser.set_file] instead.
  *
- * Please see the documentation for those functions for an example of using
- * gtk_file_chooser_set_current_name() as well.
+ * Please see the documentation for those functions for an example
+ * of using [method@Gtk.FileChooser.set_current_name] as well.
  **/
 void
 gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
@@ -306,19 +328,19 @@ gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
 
 /**
  * gtk_file_chooser_get_current_name:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  *
- * Gets the current name in the file selector, as entered by the user in the
- * text entry for “Name”.
+ * Gets the current name in the file selector, as entered by the user.
  *
- * This is meant to be used in save dialogs, to get the currently typed filename
- * when the file itself does not exist yet.
+ * This is meant to be used in save dialogs, to get the currently typed
+ * filename when the file itself does not exist yet.
  *
- * Returns: The raw text from the file chooser’s “Name” entry.  Free this with
- * g_free().  Note that this string is not a full pathname or URI; it is
- * whatever the contents of the entry are.  Note also that this string is in
- * UTF-8 encoding, which is not necessarily the system’s encoding for filenames.
- **/
+ * Returns: The raw text from the file chooser’s “Name” entry. Free with
+ *   g_free(). Note that this string is not a full pathname or URI; it is
+ *   whatever the contents of the entry are. Note also that this string is
+ *   in UTF-8 encoding, which is not necessarily the system’s encoding for
+ *   filenames.
+ */
 char *
 gtk_file_chooser_get_current_name (GtkFileChooser *chooser)
 {
@@ -346,15 +368,15 @@ gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
 
 /**
  * gtk_file_chooser_set_current_folder:
- * @chooser: a #GtkFileChooser
- * @file: the #GFile for the new folder
+ * @chooser: a `GtkFileChooser`
+ * @file: the `GFile` for the new folder
  * @error: location to store error, or %NULL.
  *
  * Sets the current folder for @chooser from a #GFile.
  *
  * Returns: %TRUE if the folder could be changed successfully, %FALSE
- * otherwise.
- **/
+ *   otherwise.
+ */
 gboolean
 gtk_file_chooser_set_current_folder (GtkFileChooser  *chooser,
                                      GFile           *file,
@@ -369,11 +391,11 @@ gtk_file_chooser_set_current_folder (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_get_current_folder:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  *
  * Gets the current folder of @chooser as #GFile.
  *
- * Returns: (transfer full): the #GFile for the current folder.
+ * Returns: (transfer full): the `GFile` for the current folder.
  */
 GFile *
 gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
@@ -407,14 +429,14 @@ gtk_file_chooser_unselect_file (GtkFileChooser *chooser,
 
 /**
  * gtk_file_chooser_get_files:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  *
  * Lists all the selected files and subfolders in the current folder
  * of @chooser as #GFile.
  *
- * Returns: (transfer full): a list model containing a #GFile for each
- *     selected file and subfolder in the current folder. Free the returned
- *     list with g_object_unref().
+ * Returns: (transfer full): a list model containing a `GFile` for each
+ *   selected file and subfolder in the current folder. Free the returned
+ *   list with g_object_unref().
  */
 GListModel *
 gtk_file_chooser_get_files (GtkFileChooser *chooser)
@@ -426,14 +448,15 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
 
 /**
  * gtk_file_chooser_set_file:
- * @chooser: a #GtkFileChooser
- * @file: the #GFile to set as current
+ * @chooser: a `GtkFileChooser`
+ * @file: the `GFile` to set as current
  * @error: (allow-none): location to store the error, or %NULL to ignore errors.
  *
- * Sets @file as the current filename for the file chooser, by changing
- * to the file’s parent folder and actually selecting the file in list.  If
- * the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name
- * will also appear in the dialog’s file name entry.
+ * Sets @file as the current filename for the file chooser.
+ *
+ * This includes changing to the file’s parent folder and actually selecting
+ * the file in list. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode,
+ * the file’s base name will also appear in the dialog’s file name entry.
  *
  * If the file name isn’t in the current folder of @chooser, then the current
  * folder of @chooser will be changed to the folder containing @filename.
@@ -441,14 +464,15 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  * Note that the file must exist, or nothing will be done except
  * for the directory change.
  *
- * If you are implementing a save dialog,
- * you should use this function if you already have a file name to which the
- * user may save; for example, when the user opens an existing file and then
- * does Save As...  If you don’t have
- * a file name already — for example, if the user just created a new
- * file and is saving it for the first time, do not call this function.
+ * If you are implementing a save dialog, you should use this function if
+ * you already have a file name to which the user may save; for example,
+ * when the user opens an existing file and then does “Save As…”. If you
+ * don’t have a file name already — for example, if the user just created
+ * a new file and is saving it for the first time, do not call this function.
+ *
  * Instead, use something similar to this:
- * |[<!-- language="C" -->
+ *
+ * ```c
  * static void
  * prepare_file_chooser (GtkFileChooser *chooser,
  *                       GFile          *existing_file)
@@ -469,10 +493,10 @@ gtk_file_chooser_get_files (GtkFileChooser *chooser)
  *       gtk_file_chooser_set_file (chooser, existing_file, NULL);
  *     }
  * }
- * ]|
+ * ```
  *
- * Returns: Not useful.
- **/
+ * Returns: Not useful
+ */
 gboolean
 gtk_file_chooser_set_file (GtkFileChooser  *chooser,
                            GFile           *file,
@@ -488,18 +512,20 @@ gtk_file_chooser_set_file (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_get_file:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  *
- * Gets the #GFile for the currently selected file in
- * the file selector. If multiple files are selected,
- * one of the files will be returned at random.
+ * Gets the `GFile` for the currently selected file in
+ * the file selector.
  *
- * If the file chooser is in folder mode, this function returns the selected
- * folder.
+ * If multiple files are selected, one of the files will be
+ * returned at random.
  *
- * Returns: (transfer full): a selected #GFile. You own the returned file;
- *     use g_object_unref() to release it.
- **/
+ * If the file chooser is in folder mode, this function returns
+ * the selected folder.
+ *
+ * Returns: (transfer full): a selected `GFile`. You own the
+ *   returned file; use g_object_unref() to release it.
+ */
 GFile *
 gtk_file_chooser_get_file (GtkFileChooser *chooser)
 {
@@ -518,15 +544,16 @@ gtk_file_chooser_get_file (GtkFileChooser *chooser)
 
 /**
  * gtk_file_chooser_add_shortcut_folder:
- * @chooser: a #GtkFileChooser
- * @folder: a #GFile for the folder to add
+ * @chooser: a `GtkFileChooser`
+ * @folder: a `GFile` for the folder to add
  * @error: location to store error, or %NULL
- * 
- * Adds a folder to be displayed with the shortcut folders in a file chooser.
- * 
- * Returns: %TRUE if the folder could be added successfully, %FALSE
- * otherwise.
- **/
+ *
+ * Adds a folder to be displayed with the shortcut folders
+ * in a file chooser.
+ *
+ * Returns: %TRUE if the folder could be added successfully,
+ *   %FALSE otherwise.
+ */
 gboolean
 gtk_file_chooser_add_shortcut_folder (GtkFileChooser  *chooser,
                                       GFile           *folder,
@@ -540,15 +567,15 @@ gtk_file_chooser_add_shortcut_folder (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_remove_shortcut_folder:
- * @chooser: a #GtkFileChooser
- * @folder: a #GFile for the folder to remove
+ * @chooser: a `GtkFileChooser`
+ * @folder: a `GFile` for the folder to remove
  * @error: location to store error, or %NULL
- * 
+ *
  * Removes a folder from the shortcut folders in a file chooser.
- * 
- * Returns: %TRUE if the folder could be removed successfully, %FALSE
- * otherwise.
- **/
+ *
+ * Returns: %TRUE if the folder could be removed successfully,
+ *   %FALSE otherwise.
+ */
 gboolean
 gtk_file_chooser_remove_shortcut_folder (GtkFileChooser  *chooser,
                                          GFile           *folder,
@@ -562,16 +589,17 @@ gtk_file_chooser_remove_shortcut_folder (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_add_filter:
- * @chooser: a #GtkFileChooser
- * @filter: (transfer none): a #GtkFileFilter
- * 
+ * @chooser: a `GtkFileChooser`
+ * @filter: (transfer none): a `GtkFileFilter`
+ *
  * Adds @filter to the list of filters that the user can select between.
+ *
  * When a filter is selected, only files that are passed by that
- * filter are displayed. 
- * 
+ * filter are displayed.
+ *
  * Note that the @chooser takes ownership of the filter if it is floating,
  * so you have to ref and sink it if you want to keep a reference.
- **/
+ */
 void
 gtk_file_chooser_add_filter (GtkFileChooser *chooser,
                              GtkFileFilter  *filter)
@@ -583,11 +611,11 @@ gtk_file_chooser_add_filter (GtkFileChooser *chooser,
 
 /**
  * gtk_file_chooser_remove_filter:
- * @chooser: a #GtkFileChooser
- * @filter: a #GtkFileFilter
- * 
+ * @chooser: a `GtkFileChooser`
+ * @filter: a `GtkFileFilter`
+ *
  * Removes @filter from the list of filters that the user can select between.
- **/
+ */
 void
 gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
                                 GtkFileFilter  *filter)
@@ -598,18 +626,20 @@ gtk_file_chooser_remove_filter (GtkFileChooser *chooser,
 }
 
 /**
- * gtk_file_chooser_get_filters:
- * @chooser: a #GtkFileChooser
- * 
- * Gets the current set of user-selectable filters, as a list model; see
- * gtk_file_chooser_add_filter(), gtk_file_chooser_remove_filter().
+ * gtk_file_chooser_get_filters: (attributes org.gtk.Method.get_property=filters)
+ * @chooser: a `GtkFileChooser`
+ *
+ * Gets the current set of user-selectable filters, as a list model.
+ *
+ * See [method@Gtk.FileChooser.add_filter] and
+ * [method@Gtk.FileChooser.remove_filter] for changing individual filters.
  *
  * You should not modify the returned list model. Future changes to
  * @chooser may or may not affect the returned model.
  *
- * Returns: (transfer full): a #GListModel containing the current set
- *     of user-selectable filters.
- **/
+ * Returns: (transfer full): a `GListModel` containing the current set
+ *   of user-selectable filters.
+ */
 GListModel *
 gtk_file_chooser_get_filters (GtkFileChooser *chooser)
 {
@@ -619,17 +649,20 @@ gtk_file_chooser_get_filters (GtkFileChooser *chooser)
 }
 
 /**
- * gtk_file_chooser_set_filter:
- * @chooser: a #GtkFileChooser
- * @filter: a #GtkFileFilter
- * 
- * Sets the current filter; only the files that pass the
- * filter will be displayed. If the user-selectable list of filters
- * is non-empty, then the filter should be one of the filters
- * in that list. Setting the current filter when the list of
- * filters is empty is useful if you want to restrict the displayed
+ * gtk_file_chooser_set_filter: (attributes org.gtk.Method.set_property=filter)
+ * @chooser: a `GtkFileChooser`
+ * @filter: a `GtkFileFilter`
+ *
+ * Sets the current filter.
+ *
+ * Only the files that pass the filter will be displayed.
+ * If the user-selectable list of filters is non-empty, then
+ * the filter should be one of the filters in that list.
+ *
+ * Setting the current filter when the list of filters is
+ * empty is useful if you want to restrict the displayed
  * set of files without letting the user change it.
- **/
+ */
 void
 gtk_file_chooser_set_filter (GtkFileChooser *chooser,
                              GtkFileFilter  *filter)
@@ -641,13 +674,13 @@ gtk_file_chooser_set_filter (GtkFileChooser *chooser,
 }
 
 /**
- * gtk_file_chooser_get_filter:
- * @chooser: a #GtkFileChooser
+ * gtk_file_chooser_get_filter: (attributes org.gtk.Method.get_property=filter)
+ * @chooser: a `GtkFileChooser`
  *
- * Gets the current filter; see gtk_file_chooser_set_filter().
+ * Gets the current filter.
  *
  * Returns: (nullable) (transfer none): the current filter, or %NULL
- **/
+ */
 GtkFileFilter *
 gtk_file_chooser_get_filter (GtkFileChooser *chooser)
 {
@@ -667,16 +700,15 @@ gtk_file_chooser_get_filter (GtkFileChooser *chooser)
 }
 
 /**
- * gtk_file_chooser_get_shortcut_folders:
- * @chooser: a #GtkFileChooser
- * 
- * Queries the list of shortcut folders in the file chooser, as set by
- * gtk_file_chooser_add_shortcut_folder().
+ * gtk_file_chooser_get_shortcut_folders: (attributes org.gtk.Method.get_property=shortcut-folders)
+ * @chooser: a `GtkFileChooser`
+ *
+ * Queries the list of shortcut folders in the file chooser.
  *
  * You should not modify the returned list model. Future changes to
  * @chooser may or may not affect the returned model.
  *
- * Returns: (transfer full): A list model of #GFiles
+ * Returns: (transfer full): A list model of `GFile`s
  */
 GListModel *
 gtk_file_chooser_get_shortcut_folders (GtkFileChooser *chooser)
@@ -688,17 +720,20 @@ gtk_file_chooser_get_shortcut_folders (GtkFileChooser *chooser)
 
 /**
  * gtk_file_chooser_add_choice:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  * @id: id for the added choice
  * @label: user-visible label for the added choice
  * @options: (nullable) (array zero-terminated=1): ids for the options of the choice, or %NULL for a boolean 
choice
  * @option_labels: (nullable) (array zero-terminated=1): user-visible labels for the options, must be the 
same length as @options
  *
- * Adds a 'choice' to the file chooser. This is typically implemented
- * as a combobox or, for boolean choices, as a checkbutton. You can select
- * a value using gtk_file_chooser_set_choice() before the dialog is shown,
- * and you can obtain the user-selected value in the ::response signal handler
- * using gtk_file_chooser_get_choice().
+ * Adds a 'choice' to the file chooser.
+ *
+ * This is typically implemented as a combobox or, for boolean choices,
+ * as a checkbutton. You can select a value using
+ * [method@Gtk.FileChooser.set_choice] before the dialog is shown,
+ * and you can obtain the user-selected value in the
+ * [signal@Gtk.Dialog::response] signal handler using
+ * [method@Gtk.FileChooser.get_choice].
  */
 void
 gtk_file_chooser_add_choice (GtkFileChooser  *chooser,
@@ -715,7 +750,7 @@ gtk_file_chooser_add_choice (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_remove_choice:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  * @id: the ID of the choice to remove
  *
  * Removes a 'choice' that has been added with gtk_file_chooser_add_choice().
@@ -732,13 +767,14 @@ gtk_file_chooser_remove_choice (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_set_choice:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  * @id: the ID of the choice to set
  * @option: the ID of the option to select
  *
  * Selects an option in a 'choice' that has been added with
- * gtk_file_chooser_add_choice(). For a boolean choice, the
- * possible options are "true" and "false".
+ * gtk_file_chooser_add_choice().
+ *
+ * For a boolean choice, the possible options are "true" and "false".
  */
 void
 gtk_file_chooser_set_choice (GtkFileChooser  *chooser,
@@ -753,7 +789,7 @@ gtk_file_chooser_set_choice (GtkFileChooser  *chooser,
 
 /**
  * gtk_file_chooser_get_choice:
- * @chooser: a #GtkFileChooser
+ * @chooser: a `GtkFileChooser`
  * @id: the ID of the choice to get
  *
  * Gets the currently selected option in the 'choice' with the given ID.
@@ -771,4 +807,3 @@ gtk_file_chooser_get_choice (GtkFileChooser  *chooser,
 
   return NULL;
 }
-
diff --git a/gtk/gtkfilechooser.h b/gtk/gtkfilechooser.h
index 9fd20da3c9..e5b68de3dd 100644
--- a/gtk/gtkfilechooser.h
+++ b/gtk/gtkfilechooser.h
@@ -45,7 +45,7 @@ typedef struct _GtkFileChooser      GtkFileChooser;
  *  selecting folders.  The file chooser will let the user pick an
  *  existing folder.
  *
- * Describes whether a #GtkFileChooser is being used to open existing files
+ * Describes whether a `GtkFileChooser` is being used to open existing files
  * or to save to a possibly new file.
  */
 typedef enum
@@ -62,7 +62,7 @@ GType gtk_file_chooser_get_type (void) G_GNUC_CONST;
 /**
  * GTK_FILE_CHOOSER_ERROR:
  *
- * Used to get the #GError quark for #GtkFileChooser errors.
+ * Used to get the `GError` quark for `GtkFileChooser` errors.
  */
 #define GTK_FILE_CHOOSER_ERROR (gtk_file_chooser_error_quark ())
 
@@ -76,7 +76,7 @@ GType gtk_file_chooser_get_type (void) G_GNUC_CONST;
  *  (e.g. "http://foo"; without a slash after that).
  *
  * These identify the various errors that can occur while calling
- * #GtkFileChooser functions.
+ * `GtkFileChooser` functions.
  */
 typedef enum {
   GTK_FILE_CHOOSER_ERROR_NONEXISTENT,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]