[gtk/ebassi/gidocgen: 101/471] application: Convert docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 101/471] application: Convert docs
Date: Mon, 8 Mar 2021 18:23:15 +0000 (UTC)

commit 7acbd03c0868ea6f435e925ba88d654d00062427
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Feb 22 14:55:55 2021 +0000

    application: Convert docs
    
    Drop mentions of command line arguments parsed by gtk_init(), and of the
    GDK lock.

 gtk/gtkapplication.c | 282 ++++++++++++++++++++++++++-------------------------
 1 file changed, 143 insertions(+), 139 deletions(-)
---
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index 6ab86c4cfb..2408d92c9b 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -52,74 +52,68 @@
  * @title: GtkApplication
  * @short_description: Application class
  *
- * #GtkApplication is a class that handles many important aspects
+ * `GtkApplication` is a class that handles many important aspects
  * of a GTK application in a convenient fashion, without enforcing
  * a one-size-fits-all application model.
  *
- * Currently, GtkApplication handles GTK initialization, application
+ * Currently, `GtkApplication` handles GTK initialization, application
  * uniqueness, session management, provides some basic scriptability and
  * desktop shell integration by exporting actions and menus and manages a
  * list of toplevel windows whose life-cycle is automatically tied to the
  * life-cycle of your application.
  *
- * While GtkApplication works fine with plain #GtkWindows, it is recommended
- * to use it together with #GtkApplicationWindow.
+ * While `GtkApplication` works fine with plain [class@Gtk.Window]s, it is
+ * recommended to use it together with [class@Gtk.ApplicationWindow].
  *
- * When GDK threads are enabled, GtkApplication will acquire the GDK
- * lock when invoking actions that arrive from other processes.  The GDK
- * lock is not touched for local action invocations.  In order to have
- * actions invoked in a predictable context it is therefore recommended
- * that the GDK lock be held while invoking actions locally with
- * g_action_group_activate_action().  The same applies to actions
- * associated with #GtkApplicationWindow and to the “activate” and
- * “open” #GApplication methods.
+ * ## Automatic resources
  *
- * ## Automatic resources ## {#automatic-resources}
- *
- * #GtkApplication will automatically load menus from the #GtkBuilder
+ * #GtkApplication will automatically load menus from the [class@Gtk.Builder]
  * resource located at "gtk/menus.ui", relative to the application's
- * resource base path (see g_application_set_resource_base_path()).
+ * resource base path (see `g_application_set_resource_base_path()`).
  * The menu with the ID "menubar" is taken as the application's
- * menubar.  Additional menus (most interesting submenus) can be named
- * and accessed via gtk_application_get_menu_by_id() which allows for
+ * menubar. Additional menus (most interesting submenus) can be named
+ * and accessed via [method@Gtk.Application.get_menu_by_id] which allows for
  * dynamic population of a part of the menu structure.
  *
  * It is also possible to provide the menubar manually using
- * gtk_application_set_menubar().
+ * [method@Gtk.Application.set_menubar].
  *
- * #GtkApplication will also automatically setup an icon search path for
+ * `GtkApplication` will also automatically setup an icon search path for
  * the default icon theme by appending "icons" to the resource base
- * path.  This allows your application to easily store its icons as
- * resources.  See gtk_icon_theme_add_resource_path() for more
+ * path. This allows your application to easily store its icons as
+ * resources. See [method@Gtk.IconTheme.add_resource_path] for more
  * information.
  *
  * If there is a resource located at "gtk/help-overlay.ui" which
- * defines a #GtkShortcutsWindow with ID "help_overlay" then GtkApplication
+ * defines a [class@Gtk.ShortcutsWindow] with ID "help_overlay" then `GtkApplication`
  * associates an instance of this shortcuts window with each
- * #GtkApplicationWindow and sets up the keyboard accelerator Control-?
- * to open it. To create a menu item that displays the
- * shortcuts window, associate the item with the action win.show-help-overlay.
+ * [class@Gtk.ApplicationWindow] and sets up the keyboard accelerator
+ * <kbd>Control</kbd>+<kbd>?</kbd> to open it. To create a menu item that
+ * displays the shortcuts window, associate the item with the action
+ * `win.show-help-overlay`.
  *
- * ## A simple application ## {#gtkapplication}
+ * ## A simple application
  *
  * [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/master/examples/bp/bloatpad.c)
+ * is available in the GTK source code repository
  *
- * GtkApplication optionally registers with a session manager
- * of the users session (if you set the #GtkApplication:register-session
+ * `GtkApplication` optionally registers with a session manager
+ * of the users session (if you set the [property@Gtk.Application:register-session]
  * property) and offers various functionality related to the session
  * life-cycle.
  *
  * An application can block various ways to end the session with
- * the gtk_application_inhibit() function. Typical use cases for
+ * the [method@Gtk.Application.inhibit] function. Typical use cases for
  * this kind of inhibiting are long-running, uninterruptible operations,
  * such as burning a CD or performing a disk backup. The session
  * manager may not honor the inhibitor, but it can be expected to
  * inform the user about the negative consequences of ending the
  * session while inhibitors are present.
  *
- * ## See Also ## {#seealso}
+ * ## See Also
+ *
  * [HowDoI: Using GtkApplication](https://wiki.gnome.org/HowDoI/GtkApplication),
- * [Getting Started with GTK: 
Basics](https://developer.gnome.org/gtk3/stable/gtk-getting-started.html#id-1.2.3.3)
+ * [Getting Started with GTK: Basics](getting_started.html#basics)
  */
 
 enum {
@@ -545,11 +539,11 @@ gtk_application_class_init (GtkApplicationClass *class)
 
   /**
    * GtkApplication::window-added:
-   * @application: the #GtkApplication which emitted the signal
-   * @window: the newly-added #GtkWindow
+   * @application: the `GtkApplication` which emitted the signal
+   * @window: the newly-added [class@Gtk.Window]
    *
-   * Emitted when a #GtkWindow is added to @application through
-   * gtk_application_add_window().
+   * Emitted when a [class@Gtk.Window] is added to `application` through
+   * [method@Gtk.Application.add_window].
    */
   gtk_application_signals[WINDOW_ADDED] =
     g_signal_new (I_("window-added"), GTK_TYPE_APPLICATION, G_SIGNAL_RUN_FIRST,
@@ -560,12 +554,12 @@ gtk_application_class_init (GtkApplicationClass *class)
 
   /**
    * GtkApplication::window-removed:
-   * @application: the #GtkApplication which emitted the signal
-   * @window: the #GtkWindow that is being removed
+   * @application: the `GtkApplication` which emitted the signal
+   * @window: the [class@Gtk.Window] that is being removed
    *
-   * Emitted when a #GtkWindow is removed from @application,
+   * Emitted when a [class@Gtk.Window] is removed from `application`,
    * either as a side-effect of being destroyed or explicitly
-   * through gtk_application_remove_window().
+   * through [method@Gtk.Application.remove_window].
    */
   gtk_application_signals[WINDOW_REMOVED] =
     g_signal_new (I_("window-removed"), GTK_TYPE_APPLICATION, G_SIGNAL_RUN_FIRST,
@@ -576,12 +570,12 @@ gtk_application_class_init (GtkApplicationClass *class)
 
   /**
    * GtkApplication::query-end:
-   * @application: the #GtkApplication which emitted the signal
+   * @application: the `GtkApplication` which emitted the signal
    *
    * Emitted when the session manager is about to end the session, only
-   * if #GtkApplication:register-session is %TRUE. Applications can
-   * connect to this signal and call gtk_application_inhibit() with
-   * %GTK_APPLICATION_INHIBIT_LOGOUT to delay the end of the session
+   * if [property@Gtk.Application:register-session] is `TRUE`. Applications can
+   * connect to this signal and call [method@Gtk.Application.inhibit] with
+   * `GTK_APPLICATION_INHIBIT_LOGOUT` to delay the end of the session
    * until state has been saved.
    */
   gtk_application_signals[QUERY_END] =
@@ -593,9 +587,9 @@ gtk_application_class_init (GtkApplicationClass *class)
   /**
    * GtkApplication:register-session:
    *
-   * Set this property to %TRUE to register with the session manager.
+   * Set this property to `TRUE` to register with the session manager.
    * This will make GTK track the session state (such as the
-   * #GtkApplication:screensaver-active property).
+   * [property@Gtk.Application:screensaver-active] property).
    */
   gtk_application_props[PROP_REGISTER_SESSION] =
     g_param_spec_boolean ("register-session",
@@ -607,11 +601,12 @@ gtk_application_class_init (GtkApplicationClass *class)
   /**
    * GtkApplication:screensaver-active:
    *
-   * This property is %TRUE if GTK believes that the screensaver is
+   * This property is `TRUE` if GTK believes that the screensaver is
    * currently active. GTK only tracks session state (including this)
-   * when #GtkApplication:register-session is set to %TRUE.
+   * when [property@Gtk.Application:register-session] is set to %TRUE.
    *
-   * Tracking the screensaver state is supported on Linux.
+   * Tracking the screensaver state is currently only supported on
+   * Linux.
    */
   gtk_application_props[PROP_SCREENSAVER_ACTIVE] =
     g_param_spec_boolean ("screensaver-active",
@@ -620,6 +615,11 @@ gtk_application_class_init (GtkApplicationClass *class)
                           FALSE,
                           G_PARAM_READABLE|G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GtkApplication:menubar:
+   *
+   * The `GMenuModel` to be used for the application's menu bar.
+   */
   gtk_application_props[PROP_MENUBAR] =
     g_param_spec_object ("menubar",
                          P_("Menubar"),
@@ -627,6 +627,11 @@ gtk_application_class_init (GtkApplicationClass *class)
                          G_TYPE_MENU_MODEL,
                          G_PARAM_READWRITE|G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GtkApplication:active-window:
+   *
+   * The currently focused window of the application.
+   */
   gtk_application_props[PROP_ACTIVE_WINDOW] =
     g_param_spec_object ("active-window",
                          P_("Active window"),
@@ -639,34 +644,29 @@ gtk_application_class_init (GtkApplicationClass *class)
 
 /**
  * gtk_application_new:
- * @application_id: (allow-none): The application ID.
+ * @application_id: (nullable): The application ID
  * @flags: the application flags
  *
- * Creates a new #GtkApplication instance.
+ * Creates a new `GtkApplication` instance.
  *
- * When using #GtkApplication, it is not necessary to call gtk_init()
+ * When using `GtkApplication`, it is not necessary to call [func Gtk init]
  * manually. It is called as soon as the application gets registered as
  * the primary instance.
  *
- * Concretely, gtk_init() is called in the default handler for the
- * #GApplication::startup signal. Therefore, #GtkApplication subclasses should
- * chain up in their #GApplication::startup handler before using any GTK API.
+ * Concretely, [func Gtk init] is called in the default handler for the
+ * `GApplication::startup` signal. Therefore, `GtkApplication` subclasses should
+ * always chain up in their `GApplication::startup` handler before using any GTK
+ * API.
  *
- * Note that commandline arguments are not passed to gtk_init().
- * All GTK functionality that is available via commandline arguments
- * can also be achieved by setting suitable environment variables
- * such as `G_DEBUG`, so this should not be a big
- * problem. If you absolutely must support GTK commandline arguments,
- * you can explicitly call gtk_init() before creating the application
- * instance.
+ * Note that commandline arguments are not passed to [func Gtk init].
  *
- * If non-%NULL, the application ID must be valid.  See
- * g_application_id_is_valid().
+ * If `application_id` is not %NULL, then it must be valid. See
+ * `g_application_id_is_valid()`.
  *
  * If no application ID is given then some features (most notably application 
  * uniqueness) will be disabled.
  *
- * Returns: a new #GtkApplication instance
+ * Returns: a new `GtkApplication` instance
  */
 GtkApplication *
 gtk_application_new (const char        *application_id,
@@ -682,23 +682,23 @@ gtk_application_new (const char        *application_id,
 
 /**
  * gtk_application_add_window:
- * @application: a #GtkApplication
- * @window: a #GtkWindow
+ * @application: a `GtkApplication`
+ * @window: a `GtkWindow`
  *
- * Adds a window to @application.
+ * Adds a window to `application`.
  *
- * This call can only happen after the @application has started;
+ * This call can only happen after the `application` has started;
  * typically, you should add new application windows in response
- * to the emission of the #GApplication::activate signal.
+ * to the emission of the `GApplication::activate` signal.
  *
- * This call is equivalent to setting the #GtkWindow:application
- * property of @window to @application.
+ * This call is equivalent to setting the [property@Gtk.Window:application]
+ * property of `window` to `application`.
  *
  * Normally, the connection between the application and the window
  * will remain until the window is destroyed, but you can explicitly
- * remove it with gtk_application_remove_window().
+ * remove it with [method@Gtk.Application.remove_window].
  *
- * GTK will keep the @application running as long as it has
+ * GTK will keep the `application` running as long as it has
  * any windows.
  **/
 void
@@ -724,17 +724,17 @@ gtk_application_add_window (GtkApplication *application,
 
 /**
  * gtk_application_remove_window:
- * @application: a #GtkApplication
- * @window: a #GtkWindow
+ * @application: a `GtkApplication`
+ * @window: a `GtkWindow`
  *
- * Remove a window from @application.
+ * Remove a window from `application`.
  *
- * If @window belongs to @application then this call is equivalent to
- * setting the #GtkWindow:application property of @window to
- * %NULL.
+ * If `window` belongs to `application` then this call is equivalent to
+ * setting the [property@Gtk.Window:application] property of `window` to
+ * `NULL`.
  *
  * The application may stop running as a result of a call to this
- * function.
+ * function, if `window` was the last window of the `application`.
  **/
 void
 gtk_application_remove_window (GtkApplication *application,
@@ -752,9 +752,9 @@ gtk_application_remove_window (GtkApplication *application,
 
 /**
  * gtk_application_get_windows:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  *
- * Gets a list of the #GtkWindows associated with @application.
+ * Gets a list of the [class@Gtk.Window] instances associated with `application`.
  *
  * The list is sorted by most recently focused window, such that the first
  * element is the currently focused window. (Useful for choosing a parent
@@ -764,7 +764,8 @@ gtk_application_remove_window (GtkApplication *application,
  * only remain valid until the next focus change or window creation or
  * deletion.
  *
- * Returns: (element-type GtkWindow) (transfer none): a #GList of #GtkWindow
+ * Returns: (element-type GtkWindow) (transfer none): a `GList` of `GtkWindow`
+ *   instances
  **/
 GList *
 gtk_application_get_windows (GtkApplication *application)
@@ -778,16 +779,15 @@ gtk_application_get_windows (GtkApplication *application)
 
 /**
  * gtk_application_get_window_by_id:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  * @id: an identifier number
  *
- * Returns the #GtkApplicationWindow with the given ID.
+ * Returns the [class@Gtk.ApplicationWindow] with the given ID.
  *
- * The ID of a #GtkApplicationWindow can be retrieved with
- * gtk_application_window_get_id().
+ * The ID of a `GtkApplicationWindow` can be retrieved with
+ * [method@Gtk.ApplicationWindow.get_id].
  *
- * Returns: (nullable) (transfer none): the window with ID @id, or
- *   %NULL if there is no window with this ID
+ * Returns: (nullable) (transfer none): the window for the given `id`
  */
 GtkWindow *
 gtk_application_get_window_by_id (GtkApplication *application,
@@ -810,7 +810,7 @@ gtk_application_get_window_by_id (GtkApplication *application,
 
 /**
  * gtk_application_get_active_window:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  *
  * Gets the “active” window for the application.
  *
@@ -819,8 +819,7 @@ gtk_application_get_window_by_id (GtkApplication *application,
  * if another application has it — this is just the most
  * recently-focused window within this application.
  *
- * Returns: (transfer none) (nullable): the active window, or %NULL if
- *   there isn't one.
+ * Returns: (transfer none) (nullable): the active window
  **/
 GtkWindow *
 gtk_application_get_active_window (GtkApplication *application)
@@ -844,15 +843,15 @@ gtk_application_update_accels (GtkApplication *application)
 
 /**
  * gtk_application_set_menubar:
- * @application: a #GtkApplication
- * @menubar: (allow-none): a #GMenuModel, or %NULL
+ * @application: a `GtkApplication`
+ * @menubar: (nullable): a `GMenuModel`
  *
- * Sets or unsets the menubar for windows of @application.
+ * Sets or unsets the menubar for windows of `application`.
  *
  * This is a menubar in the traditional sense.
  *
  * This can only be done in the primary instance of the application,
- * after it has been registered.  #GApplication::startup is a good place
+ * after it has been registered. `GApplication::startup` is a good place
  * to call this.
  *
  * Depending on the desktop environment, this may appear at the top of
@@ -863,7 +862,7 @@ gtk_application_update_accels (GtkApplication *application)
  * the application menu may be rendered by the desktop shell while the
  * menubar (if set) remains in each individual window.
  *
- * Use the base #GActionMap interface to add actions, to respond to the
+ * Use the base `GActionMap` interface to add actions, to respond to the
  * user selecting these menu items.
  */
 void
@@ -887,12 +886,12 @@ gtk_application_set_menubar (GtkApplication *application,
 
 /**
  * gtk_application_get_menubar:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  *
  * Returns the menu model that has been set with
- * gtk_application_set_menubar().
+ * [method@Gtk.Application.set_menubar].
  *
- * Returns: (nullable) (transfer none): the menubar for windows of @application
+ * Returns: (nullable) (transfer none): the menubar for windows of `application`
  */
 GMenuModel *
 gtk_application_get_menubar (GtkApplication *application)
@@ -914,16 +913,16 @@ gtk_application_get_menubar (GtkApplication *application)
  * @GTK_APPLICATION_INHIBIT_IDLE: Inhibit the session being
  *     marked as idle (and possibly locked)
  *
- * Types of user actions that may be blocked by gtk_application_inhibit().
+ * Types of user actions that may be blocked by [method@Gtk.Application.inhibit].
  */
 
 /**
  * gtk_application_inhibit:
- * @application: the #GtkApplication
- * @window: (allow-none): a #GtkWindow, or %NULL
+ * @application: the `GtkApplication`
+ * @window: (nullable): a `GtkWindow`
  * @flags: what types of actions should be inhibited
- * @reason: (allow-none): a short, human-readable string that explains
- *     why these operations are inhibited
+ * @reason: (nullable): a short, human-readable string that explains
+ *   why these operations are inhibited
  *
  * Inform the session manager that certain types of actions should be
  * inhibited. This is not guaranteed to work on all platforms and for
@@ -931,10 +930,10 @@ gtk_application_get_menubar (GtkApplication *application)
  *
  * Applications should invoke this method when they begin an operation
  * that should not be interrupted, such as creating a CD or DVD. The
- * types of actions that may be blocked are specified by the @flags
+ * types of actions that may be blocked are specified by the `flags`
  * parameter. When the application completes the operation it should
- * call gtk_application_uninhibit() to remove the inhibitor. Note that
- * an application can have multiple inhibitors, and all of them must
+ * call [method@Gtk.Application.uninhibit] to remove the inhibitor. Note
+ * that an application can have multiple inhibitors, and all of them must
  * be individually removed. Inhibitors are also cleared when the
  * application exits.
  *
@@ -942,15 +941,15 @@ gtk_application_get_menubar (GtkApplication *application)
  * the action. In most cases, users will be given the option to force
  * the action to take place.
  *
- * Reasons should be short and to the point.
+ * The `reason` message should be short and to the point.
  *
- * If @window is given, the session manager may point the user to
+ * If `window` is given, the session manager may point the user to
  * this window to find out more about why the action is inhibited.
  *
  * Returns: A non-zero cookie that is used to uniquely identify this
- *     request. It should be used as an argument to gtk_application_uninhibit()
- *     in order to remove the request. If the platform does not support
- *     inhibiting or the request failed for some reason, 0 is returned.
+ *   request. It should be used as an argument to [method@Gtk.Application.uninhibit]
+ *   in order to remove the request. If the platform does not support
+ *   inhibiting or the request failed for some reason, 0 is returned.
  */
 guint
 gtk_application_inhibit (GtkApplication             *application,
@@ -969,10 +968,11 @@ gtk_application_inhibit (GtkApplication             *application,
 
 /**
  * gtk_application_uninhibit:
- * @application: the #GtkApplication
- * @cookie: a cookie that was returned by gtk_application_inhibit()
+ * @application: the `GtkApplication`
+ * @cookie: a cookie that was returned by [method@Gtk.Application.inhibit]
+ *
+ * Removes an inhibitor that has been established with [method@Gtk.Application.inhibit].
  *
- * Removes an inhibitor that has been established with gtk_application_inhibit().
  * Inhibitors are also cleared when the application exits.
  */
 void
@@ -1010,13 +1010,12 @@ gtk_application_get_application_accels (GtkApplication *application)
 
 /**
  * gtk_application_list_action_descriptions:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  *
  * Lists the detailed action names which have associated accelerators.
- * See gtk_application_set_accels_for_action().
+ * See [method@Gtk.Application.set_accels_for_action].
  *
- * Returns: (transfer full): a %NULL-terminated array of strings,
- *     free with g_strfreev() when done
+ * Returns: (transfer full) (array zero-terminated=1): the detailed action names
  */
 char **
 gtk_application_list_action_descriptions (GtkApplication *application)
@@ -1030,21 +1029,23 @@ gtk_application_list_action_descriptions (GtkApplication *application)
 
 /**
  * gtk_application_set_accels_for_action:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  * @detailed_action_name: a detailed action name, specifying an action
  *     and target to associate accelerators with
  * @accels: (array zero-terminated=1): a list of accelerators in the format
- *     understood by gtk_accelerator_parse()
+ *     understood by [func@Gtk.accelerator_parse]
  *
  * Sets zero or more keyboard accelerators that will trigger the
- * given action. The first item in @accels will be the primary
- * accelerator, which may be displayed in the UI.
+ * given action.
+ *
+ * The first item in `accels` will be the primary accelerator, which may be
+ * displayed in the UI.
  *
  * To remove all accelerators for an action, use an empty, zero-terminated
- * array for @accels.
+ * array for `accels`.
  *
- * For the @detailed_action_name, see g_action_parse_detailed_name() and
- * g_action_print_detailed_name().
+ * For the `detailed_action_name`, see `g_action_parse_detailed_name()` and
+ * `g_action_print_detailed_name()`.
  */
 void
 gtk_application_set_accels_for_action (GtkApplication      *application,
@@ -1071,15 +1072,15 @@ gtk_application_set_accels_for_action (GtkApplication      *application,
 
 /**
  * gtk_application_get_accels_for_action:
- * @application: a #GtkApplication
+ * @application: a `GtkApplication`
  * @detailed_action_name: a detailed action name, specifying an action
- *     and target to obtain accelerators for
+ *   and target to obtain accelerators for
  *
  * Gets the accelerators that are currently associated with
  * the given action.
  *
- * Returns: (transfer full): accelerators for @detailed_action_name, as
- *     a %NULL-terminated array. Free with g_strfreev() when no longer needed
+ * Returns: (transfer full) (array zero-terminated=1) (element-type utf8):
+ *   accelerators for `detailed_action_name`
  */
 char **
 gtk_application_get_accels_for_action (GtkApplication *application,
@@ -1096,10 +1097,11 @@ gtk_application_get_accels_for_action (GtkApplication *application,
 
 /**
  * gtk_application_get_actions_for_accel:
- * @application: a #GtkApplication
- * @accel: an accelerator that can be parsed by gtk_accelerator_parse()
+ * @application: a `GtkApplication`
+ * @accel: an accelerator that can be parsed by [func@Gtk.accelerator_parse]
+ *
+ * Returns the list of actions (possibly empty) that `accel` maps to.
  *
- * Returns the list of actions (possibly empty) that @accel maps to.
  * Each item in the list is a detailed action name in the usual form.
  *
  * This might be useful to discover if an accel already exists in
@@ -1110,12 +1112,13 @@ gtk_application_get_accels_for_action (GtkApplication *application,
  * same context.
  *
  * In case there are no actions for a given accelerator, an empty array
- * is returned.  %NULL is never returned.
+ * is returned. `NULL` is never returned.
  *
  * It is a programmer error to pass an invalid accelerator string.
- * If you are unsure, check it with gtk_accelerator_parse() first.
  *
- * Returns: (transfer full): a %NULL-terminated array of actions for @accel
+ * If you are unsure, check it with [func@Gtk.accelerator_parse] first.
+ *
+ * Returns: (transfer full): a %NULL-terminated array of actions for `accel`
  */
 char **
 gtk_application_get_actions_for_accel (GtkApplication *application,
@@ -1175,7 +1178,8 @@ gtk_application_handle_window_map (GtkApplication *application,
  * @id: the id of the menu to look up
  *
  * Gets a menu from automatically loaded resources.
- * See [Automatic resources][automatic-resources]
+ *
+ * See [the section on Automatic resources](class.Application.html#automatic-resources)
  * for more information.
  *
  * Returns: (nullable) (transfer none): Gets the menu with the
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]