shortcutswindow: Convert docs

9104420c · Matthias Clasen · Emmanuele Bassi · 0d238f4c · 9104420c · 9104420c
Commit 9104420c authored Feb 26, 2021 by Matthias Clasen Committed by Emmanuele Bassi Mar 11, 2021
--- a/gtk/gtkshortcutsgroup.c
+++ b/gtk/gtkshortcutsgroup.c
@@ -30,16 +30,16 @@
 #include "gtksizegroup.h"

 /**
- * SECTION:gtkshortcutsgroup
- * @Title: GtkShortcutsGroup
- * @Short_description: Represents a group of shortcuts in a GtkShortcutsWindow
+ * GtkShortcutsGroup:
 *
- * A GtkShortcutsGroup represents a group of related keyboard shortcuts
- * or gestures. The group has a title. It may optionally be associated with
- * a view of the application, which can be used to show only relevant shortcuts
+ * A `GtkShortcutsGroup` represents a group of related keyboard shortcuts
+ * or gestures.
+ *
+ * The group has a title. It may optionally be associated with a view
+ * of the application, which can be used to show only relevant shortcuts
 * depending on the application context.
 *
- * This widget is only meant to be used with #GtkShortcutsWindow.
+ * This widget is only meant to be used with [class@Gtk.ShortcutsWindow].
 */

 struct _GtkShortcutsGroup
@@ -284,8 +284,9 @@ gtk_shortcuts_group_class_init (GtkShortcutsGroupClass *klass)
   * GtkShortcutsGroup:view:
   *
   * An optional view that the shortcuts in this group are relevant for.
-   * The group will be hidden if the #GtkShortcutsWindow:view-name property
-   * does not match the view of this group.
+   *
+   * The group will be hidden if the [property@Gtk.ShortcutsWindow:view-name]
+   * property does not match the view of this group.
   *
   * Set this to %NULL to make the group always visible.
   */

--- a/gtk/gtkshortcutssection.c
+++ b/gtk/gtkshortcutssection.c
@@ -38,20 +38,21 @@
 #include "gtkintl.h"

 /**
- * SECTION:gtkshortcutssection
- * @Title: GtkShortcutsSection
- * @Short_description: Represents an application mode in a GtkShortcutsWindow
+ * GtkShortcutsSection:
 *
- * A GtkShortcutsSection collects all the keyboard shortcuts and gestures
- * for a major application mode. If your application needs multiple sections,
- * you should give each section a unique #GtkShortcutsSection:section-name and
- * a #GtkShortcutsSection:title that can be shown in the section selector of
- * the GtkShortcutsWindow.
+ * A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures
+ * for a major application mode.
 *
- * The #GtkShortcutsSection:max-height property can be used to influence how
- * the groups in the section are distributed over pages and columns.
+ * If your application needs multiple sections, you should give each
+ * section a unique [property@Gtk.ShortcutsSection:section-name] and
+ * a [property@Gtk.ShortcutsSection:title] that can be shown in the
+ * section selector of the [class@Gtk.ShortcutsWindow].
 *
- * This widget is only meant to be used with #GtkShortcutsWindow.
+ * The [property@Gtk.ShortcutsSection:max-height] property can be used
+ * to influence how the groups in the section are distributed over pages
+ * and columns.
+ *
+ * This widget is only meant to be used with [class@Gtk.ShortcutsWindow].
 */

 struct _GtkShortcutsSection
@@ -286,9 +287,10 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
   * GtkShortcutsSection:section-name:
   *
   * A unique name to identify this section among the sections
-   * added to the GtkShortcutsWindow. Setting the #GtkShortcutsWindow:section-name
-   * property to this string will make this section shown in the
-   * GtkShortcutsWindow.
+   * added to the `GtkShortcutsWindow`.
+   *
+   * Setting the [property@Gtk.ShortcutsWindow:section-name] property
+   * to this string will make this section shown in the `GtkShortcutsWindow`.
   */
  properties[PROP_SECTION_NAME] =
    g_param_spec_string ("section-name", P_("Section Name"), P_("Section Name"),
@@ -299,10 +301,12 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
   * GtkShortcutsSection:view-name:
   *
   * A view name to filter the groups in this section by.
-   * See #GtkShortcutsGroup:view.
   *
-   * Applications are expected to use the #GtkShortcutsWindow:view-name
-   * property for this purpose.
+   * See [property@Gtk.ShortcutsGroup:view].
+   *
+   * Applications are expected to use the
+   * [property@Gtk.ShortcutsWindow:view-name] property
+   * for this purpose.
   */
  properties[PROP_VIEW_NAME] =
    g_param_spec_string ("view-name", P_("View Name"), P_("View Name"),
@@ -312,9 +316,11 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
  /**
   * GtkShortcutsSection:title:
   *
-   * The string to show in the section selector of the GtkShortcutsWindow
-   * for this section. If there is only one section, you don't need to
-   * set a title, since the section selector will not be shown in this case.
+   * The string to show in the section selector of the `GtkShortcutsWindow`
+   * for this section.
+   *
+   * If there is only one section, you don't need to set a title,
+   * since the section selector will not be shown in this case.
   */
  properties[PROP_TITLE] =
    g_param_spec_string ("title", P_("Title"), P_("Title"),
@@ -324,10 +330,11 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
  /**
   * GtkShortcutsSection:max-height:
   *
-   * The maximum number of lines to allow per column. This property can
-   * be used to influence how the groups in this section are distributed
-   * across pages and columns. The default value of 15 should work in
-   * most cases.
+   * The maximum number of lines to allow per column.
+   *
+   * This property can be used to influence how the groups in this
+   * section are distributed across pages and columns. The default
+   * value of 15 should work in most cases.
   */
  properties[PROP_MAX_HEIGHT] =
    g_param_spec_uint ("max-height", P_("Maximum Height"), P_("Maximum Height"),

--- a/gtk/gtkshortcutsshortcut.c
+++ b/gtk/gtkshortcutsshortcut.c
@@ -32,12 +32,12 @@
 #include "gtktypebuiltins.h"

 /**
- * SECTION:gtkshortcutsshortcut
- * @Title: GtkShortcutsShortcut
- * @Short_description: Represents a keyboard shortcut in a GtkShortcutsWindow
+ * GtkShortcutsShortcut:
 *
- * A GtkShortcutsShortcut represents a single keyboard shortcut or gesture
- * with a short text. This widget is only meant to be used with #GtkShortcutsWindow.
+ * A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture
+ * with a short text.
+ *
+ * This widget is only meant to be used with `GtkShortcutsWindow`.
 */

 struct _GtkShortcutsShortcut
@@ -551,24 +551,30 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
  /**
   * GtkShortcutsShortcut:accelerator:
   *
-   * The accelerator(s) represented by this object. This property is used
-   * if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_ACCELERATOR.
+   * The accelerator(s) represented by this object.
+   *
+   * This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type]
+   * is set to %GTK_SHORTCUT_ACCELERATOR.
+   *
+   * The syntax of this property is (an extension of) the syntax understood
+   * by [func@Gtk.accelerator_parse]. Multiple accelerators can be specified
+   * by separating them with a space, but keep in mind that the available width
+   * is limited.
   *
-   * The syntax of this property is (an extension of) the syntax understood by
-   * gtk_accelerator_parse(). Multiple accelerators can be specified by separating
-   * them with a space, but keep in mind that the available width is limited.
-   * It is also possible to specify ranges of shortcuts, using ... between the keys.
-   * Sequences of keys can be specified using a + or & between the keys.
+   * It is also possible to specify ranges of shortcuts, using "..." between
+   * the keys. Sequences of keys can be specified using a "+" or "&" between
+   * the keys.
   *
   * Examples:
+   *
   * - A single shortcut: <ctl><alt>delete
   * - Two alternative shortcuts: <shift>a Home
   * - A range of shortcuts: <alt>1...<alt>9
   * - Several keys pressed together: Control_L&Control_R
   * - A sequence of shortcuts or keys: <ctl>c+<ctl>x
   *
-   * Use + instead of & when the keys may (or have to be) pressed sequentially (e.g
-   * use t+t for 'press the t key twice').
+   * Use "+" instead of "&" when the keys may (or have to be) pressed
+   * sequentially (e.g use "t+t" for 'press the t key twice').
   *
   * Note that <, > and & need to be escaped as &lt;, &gt; and &amp; when used
   * in .ui files.
@@ -583,8 +589,11 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
  /**
   * GtkShortcutsShortcut:icon:
   *
-   * An icon to represent the shortcut or gesture. This property is used if
-   * #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_GESTURE.
+   * An icon to represent the shortcut or gesture.
+   *
+   * This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type]
+   * is set to %GTK_SHORTCUT_GESTURE.
+   *
   * For the other predefined gesture types, GTK provides an icon on its own.
   */
  properties[PROP_ICON] =
@@ -610,7 +619,9 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
   * GtkShortcutsShortcut:title:
   *
   * The textual description for the shortcut or gesture represented by
-   * this object. This should be a short string that can fit in a single line.
+   * this object.
+   *
+   * This should be a short string that can fit in a single line.
   */
  properties[PROP_TITLE] =
    g_param_spec_string ("title",
@@ -678,9 +689,10 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
  /**
   * GtkShortcutsShortcut:direction:
   *
-   * The text direction for which this shortcut is active. If the shortcut
-   * is used regardless of the text direction, set this property to
-   * #GTK_TEXT_DIR_NONE.
+   * The text direction for which this shortcut is active.
+   *
+   * If the shortcut is used regardless of the text direction,
+   * set this property to %GTK_TEXT_DIR_NONE.
   */
  properties[PROP_DIRECTION] =
    g_param_spec_enum ("direction",
@@ -706,11 +718,12 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
  /**
   * GtkShortcutsShortcut:action-name:
   *
-   * A detailed action name. If this is set for a shortcut
-   * of type %GTK_SHORTCUT_ACCELERATOR, then GTK will use
-   * the accelerators that are associated with the action
-   * via gtk_application_set_accels_for_action(), and setting
-   * #GtkShortcutsShortcut:accelerator is not necessary.
+   * A detailed action name.
+   *
+   * If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR,
+   * then GTK will use the accelerators that are associated with the
+   * action via [method@Gtk.Application.set_accels_for_action], and
+   * setting [property@Gtk.ShortcutsShortcut:accelerator] is not necessary.
   */
  properties[PROP_ACTION_NAME] =
    g_param_spec_string ("action-name",

--- a/gtk/gtkshortcutsshortcut.h
+++ b/gtk/gtkshortcutsshortcut.h
@@ -38,7 +38,7 @@ typedef struct _GtkShortcutsShortcutClass GtkShortcutsShortcutClass;
 /**
 * GtkShortcutType:
 * @GTK_SHORTCUT_ACCELERATOR:
- *   The shortcut is a keyboard accelerator. The #GtkShortcutsShortcut:accelerator
+ *   The shortcut is a keyboard accelerator. The GtkShortcutsShortcut:accelerator
 *   property will be used.
 * @GTK_SHORTCUT_GESTURE_PINCH:
 *   The shortcut is a pinch gesture. GTK provides an icon and subtitle.
@@ -53,7 +53,7 @@ typedef struct _GtkShortcutsShortcutClass GtkShortcutsShortcutClass;
 * @GTK_SHORTCUT_GESTURE_TWO_FINGER_SWIPE_RIGHT:
 *   The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle.
 * @GTK_SHORTCUT_GESTURE:
- *   The shortcut is a gesture. The #GtkShortcutsShortcut:icon property will be
+ *   The shortcut is a gesture. The GtkShortcutsShortcut:icon property will be
 *   used.
 * @GTK_SHORTCUT_GESTURE_SWIPE_LEFT:
 *   The shortcut is a swipe gesture. GTK provides an icon and subtitle.

--- a/gtk/gtkshortcutswindow.c
+++ b/gtk/gtkshortcutswindow.c
@@ -44,22 +44,21 @@
 #include "gtkwidgetprivate.h"

 /**
- * SECTION:gtkshortcutswindow
- * @Title: GtkShortcutsWindow
- * @Short_description: Toplevel which shows help for shortcuts
+ * GtkShortcutsWindow:
 *
- * A GtkShortcutsWindow shows brief information about the keyboard shortcuts
- * and gestures of an application. The shortcuts can be grouped, and you can
- * have multiple sections in this window, corresponding to the major modes of
- * your application.
+ * A `GtkShortcutsWindow` shows information about the keyboard shortcuts
+ * and gestures of an application.
+ *
+ * The shortcuts can be grouped, and you can have multiple sections in this
+ * window, corresponding to the major modes of your application.
 *
 * Additionally, the shortcuts can be filtered by the current view, to avoid
 * showing information that is not relevant in the current application context.
 *
- * The recommended way to construct a GtkShortcutsWindow is with GtkBuilder,
- * by populating a #GtkShortcutsWindow with one or more #GtkShortcutsSection
- * objects, which contain #GtkShortcutsGroups that in turn contain objects of
- * class #GtkShortcutsShortcut.
+ * The recommended way to construct a `GtkShortcutsWindow` is with
+ * [class@Gtk.Builder], by populating a `GtkShortcutsWindow` with one or
+ * more `GtkShortcutsSection` objects, which contain `GtkShortcutsGroups`
+ * that in turn contain objects of class `GtkShortcutsShortcut`.
 *
 * # A simple example:
 *
@@ -75,7 +74,7 @@
 *
 * ![](clocks-shortcuts.png)
 *
- * This example shows a #GtkShortcutsWindow that has been configured to show only
+ * This example shows a `GtkShortcutsWindow` that has been configured to show only
 * the shortcuts relevant to the "stopwatch" view.
 *
 * The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/master/demos/gtk-demo/shortcuts-clocks.ui).
@@ -84,7 +83,7 @@
 *
 * ![](builder-shortcuts.png)
 *
- * This example shows a #GtkShortcutsWindow with two sections, "Editor Shortcuts"
+ * This example shows a `GtkShortcutsWindow` with two sections, "Editor Shortcuts"
 * and "Terminal Shortcuts".
 *
 * The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/master/demos/gtk-demo/shortcuts-builder.ui).
@@ -746,7 +745,7 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
   *
   * The name of the section to show.
   *
-   * This should be the section-name of one of the #GtkShortcutsSection
+   * This should be the section-name of one of the `GtkShortcutsSection`
   * objects that are in this shortcuts window.
   */
  properties[PROP_SECTION_NAME] =
@@ -759,8 +758,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
   *
   * The view name by which to filter the contents.
   *
-   * This should correspond to the #GtkShortcutsGroup:view property of some of
-   * the #GtkShortcutsGroup objects that are inside this shortcuts window.
+   * This should correspond to the [property@Gtk.ShortcutsGroup:view]
+   * property of some of the [class@Gtk.ShortcutsGroup] objects that
+   * are inside this shortcuts window.
   *
   * Set this to %NULL to show all groups.
   */
@@ -774,10 +774,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
  /**
   * GtkShortcutsWindow::close:
   *
-   * The ::close signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user uses a keybinding to close
-   * the window.
+   * Emitted when the user uses a keybinding to close the window.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
   *
   * The default binding for this signal is the Escape key.
   */
@@ -792,9 +791,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
  /**
   * GtkShortcutsWindow::search:
   *
-   * The ::search signal is a
-   * [keybinding signal][GtkSignalAction]
-   * which gets emitted when the user uses a keybinding to start a search.
+   * Emitted when the user uses a keybinding to start a search.
+   *
+   * This is a [keybinding signal](class.SignalAction.html).
   *
   * The default binding for this signal is Control-F.
   */