From a43ee8991ef8a6d097625548ea8b37d48995ea94 Mon Sep 17 00:00:00 2001 From: Sudhanshu Tiwari Date: Thu, 11 Apr 2024 23:20:09 +0530 Subject: [PATCH] Ports the documentation comments in gio/gactiongroup.c to GI-Docgen --- gio/gactiongroup.c | 180 +++++++++++++++++++++++---------------------- 1 file changed, 91 insertions(+), 89 deletions(-) diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c index 7f7cb1c12..b608d2b36 100644 --- a/gio/gactiongroup.c +++ b/gio/gactiongroup.c @@ -32,17 +32,17 @@ * * Actions can be used to expose functionality in a structured way, either * from one part of a program to another, or to the outside world. Action - * groups are often used together with a `GMenuModel` that provides additional + * groups are often used together with a [type@Gio.MenuModel] that provides additional * representation data for displaying the actions to the user, e.g. in a menu. * * The main way to interact with the actions in a `GActionGroup` is to * activate them with [method@Gio.ActionGroup.activate_action]. Activating an - * action may require a `GVariant` parameter. The required type of the + * action may require a [type@GLib.Variant] parameter. The required type of the * parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type]. * Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled]. * Activating a disabled action has no effect. * - * Actions may optionally have a state in the form of a #GVariant. The current + * Actions may optionally have a state in the form of a [type@GLib.Variant]. The current * state of an action can be inquired with [method@Gio.ActionGroup.get_action_state]. * Activating a stateful action may change its state, but it is also possible to * set the state by calling [method@Gio.ActionGroup.change_action_state]. @@ -76,22 +76,22 @@ /** * GActionGroupInterface: - * @has_action: the virtual function pointer for g_action_group_has_action() - * @list_actions: the virtual function pointer for g_action_group_list_actions() - * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type() - * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type() - * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint() - * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled() - * @get_action_state: the virtual function pointer for g_action_group_get_action_state() - * @change_action_state: the virtual function pointer for g_action_group_change_action_state() - * @activate_action: the virtual function pointer for g_action_group_activate_action() - * @action_added: the class closure for the #GActionGroup::action-added signal - * @action_removed: the class closure for the #GActionGroup::action-removed signal - * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal - * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal - * @query_action: the virtual function pointer for g_action_group_query_action() + * @has_action: the virtual function pointer for [method@Gio.ActionGroup.has_action] + * @list_actions: the virtual function pointer for [method@Gio.ActionGroup.list_actions] + * @get_action_parameter_type: the virtual function pointer for [method@Gio.ActionGroup.get_action_parameter_type] + * @get_action_state_type: the virtual function pointer for [method@Gio.ActionGroup.get_action_state_type] + * @get_action_state_hint: the virtual function pointer for [method@Gio.ActionGroup.get_action_state_hint] + * @get_action_enabled: the virtual function pointer for [method@Gio.ActionGroup.get_action_enabled] + * @get_action_state: the virtual function pointer for [method@Gio.ActionGroup.get_action_state] + * @change_action_state: the virtual function pointer for [method@Gio.ActionGroup.change_action_state] + * @activate_action: the virtual function pointer for [method@Gio.ActionGroup.activate_action] + * @action_added: the class closure for the [signal@Gio.ActionGroup::action-added] signal + * @action_removed: the class closure for the [signal@Gio.ActionGroup::action-removed] signal + * @action_enabled_changed: the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal + * @action_state_changed: the class closure for the [signal@Gio.ActionGroup::action-enabled-changed] signal + * @query_action: the virtual function pointer for [method@Gio.ActionGroup.query_action] * - * The virtual function table for #GActionGroup. + * The virtual function table for [type@Gio.ActionGroup]. * * Since: 2.28 **/ @@ -240,10 +240,11 @@ g_action_group_default_init (GActionGroupInterface *iface) /** * GActionGroup::action-added: - * @action_group: the #GActionGroup that changed + * @action_group: the [type@Gio.ActionGroup] that changed * @action_name: the name of the action in @action_group * * Signals that a new action was just added to the group. + * * This signal is emitted after the action has been added * and is now visible. * @@ -261,10 +262,11 @@ g_action_group_default_init (GActionGroupInterface *iface) /** * GActionGroup::action-removed: - * @action_group: the #GActionGroup that changed + * @action_group: the [type@Gio.ActionGroup] that changed * @action_name: the name of the action in @action_group * * Signals that an action is just about to be removed from the group. + * * This signal is emitted before the action is removed, so the action * is still visible and can be queried from the signal handler. * @@ -283,7 +285,7 @@ g_action_group_default_init (GActionGroupInterface *iface) /** * GActionGroup::action-enabled-changed: - * @action_group: the #GActionGroup that changed + * @action_group: the [type@Gio.ActionGroup] that changed * @action_name: the name of the action in @action_group * @enabled: whether the action is enabled or not * @@ -308,7 +310,7 @@ g_action_group_default_init (GActionGroupInterface *iface) /** * GActionGroup::action-state-changed: - * @action_group: the #GActionGroup that changed + * @action_group: the [type@Gio.ActionGroup] that changed * @action_name: the name of the action in @action_group * @value: the new value of the state * @@ -336,14 +338,14 @@ g_action_group_default_init (GActionGroupInterface *iface) /** * g_action_group_list_actions: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * * Lists the actions contained within @action_group. * - * The caller is responsible for freeing the list with g_strfreev() when + * The caller is responsible for freeing the list with [func@GLib.strfreev] when * it is no longer required. * - * Returns: (transfer full): a %NULL-terminated array of the names of the + * Returns: (transfer full): a `NULL`-terminated array of the names of the * actions in the group * * Since: 2.28 @@ -359,7 +361,7 @@ g_action_group_list_actions (GActionGroup *action_group) /** * g_action_group_has_action: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to check for * * Checks if the named action exists within @action_group. @@ -380,18 +382,18 @@ g_action_group_has_action (GActionGroup *action_group, /** * g_action_group_get_action_parameter_type: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to query * * Queries the type of the parameter that must be given when activating * the named action within @action_group. * - * When activating the action using g_action_group_activate_action(), - * the #GVariant given to that function must be of the type returned + * When activating the action using [method@Gio.ActionGroup.activate_action], + * the [type@GLib.Variant] given to that function must be of the type returned * by this function. * - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. + * In the case that this function returns `NULL`, you must not give any + * [type@GLib.Variant], but `NULL` instead. * * The parameter type of a particular action will never change but it is * possible for an action to be removed and for a new action to be added @@ -413,21 +415,21 @@ g_action_group_get_action_parameter_type (GActionGroup *action_group, /** * g_action_group_get_action_state_type: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to query * * Queries the type of the state of the named action within * @action_group. * * If the action is stateful then this function returns the - * #GVariantType of the state. All calls to - * g_action_group_change_action_state() must give a #GVariant of this - * type and g_action_group_get_action_state() will return a #GVariant + * [type@GLib.VariantType] of the state. All calls to + * [method@Gio.ActionGroup.change_action_state] must give a [type@GLib.Variant] of this + * type and [method@Gio.ActionGroup.get_action_state] will return a [type@GLib.Variant] * of the same type. * - * If the action is not stateful then this function will return %NULL. - * In that case, g_action_group_get_action_state() will return %NULL - * and you must not call g_action_group_change_action_state(). + * If the action is not stateful then this function will return `NULL`. + * In that case, [method@Gio.ActionGroup.get_action_state] will return `NULL` + * and you must not call [method@Gio.ActionGroup.change_action_state]. * * The state type of a particular action will never change but it is * possible for an action to be removed and for a new action to be added @@ -449,18 +451,18 @@ g_action_group_get_action_state_type (GActionGroup *action_group, /** * g_action_group_get_action_state_hint: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to query * * Requests a hint about the valid range of values for the state of the * named action within @action_group. * - * If %NULL is returned it either means that the action is not stateful + * If `NULL` is returned it either means that the action is not stateful * or that there is no hint about the valid range of values for the * state of the action. * - * If a #GVariant array is returned then each item in the array is a - * possible value for the state. If a #GVariant pair (ie: two-tuple) is + * If a [type@GLib.Variant] array is returned then each item in the array is a + * possible value for the state. If a [type@GLib.Variant] pair (ie: two-tuple) is * returned then the tuple specifies the inclusive lower and upper bound * of valid values for the state. * @@ -468,8 +470,8 @@ g_action_group_get_action_state_type (GActionGroup *action_group, * have a state value outside of the hinted range and setting a value * within the range may fail. * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * The return value (if non-`NULL`) should be freed with + * [method@GLib.Variant.unref] when it is no longer required. * * Returns: (nullable) (transfer full): the state range hint * @@ -487,7 +489,7 @@ g_action_group_get_action_state_hint (GActionGroup *action_group, /** * g_action_group_get_action_enabled: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to query * * Checks if the named action within @action_group is currently enabled. @@ -511,17 +513,17 @@ g_action_group_get_action_enabled (GActionGroup *action_group, /** * g_action_group_get_action_state: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to query * * Queries the current state of the named action within @action_group. * - * If the action is not stateful then %NULL will be returned. If the + * If the action is not stateful then `NULL` will be returned. If the * action is stateful then the type of the return value is the type - * given by g_action_group_get_action_state_type(). + * given by [method@Gio.ActionGroup.get_action_state_type]. * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. + * The return value (if non-`NULL`) should be freed with + * [method@GLib.Variant.unref] when it is no longer required. * * Returns: (nullable) (transfer full): the current state of the action * @@ -539,7 +541,7 @@ g_action_group_get_action_state (GActionGroup *action_group, /** * g_action_group_change_action_state: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to request the change on * @value: the new state * @@ -547,11 +549,11 @@ g_action_group_get_action_state (GActionGroup *action_group, * changed to @value. * * The action must be stateful and @value must be of the correct type. - * See g_action_group_get_action_state_type(). + * See [method@Gio.ActionGroup.get_action_state_type]. * * This call merely requests a change. The action may refuse to change * its state or may change its state to something other than @value. - * See g_action_group_get_action_state_hint(). + * See [method@Gio.ActionGroup.get_action_state_hint]. * * If the @value GVariant is floating, it is consumed. * @@ -572,7 +574,7 @@ g_action_group_change_action_state (GActionGroup *action_group, /** * g_action_group_activate_action: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of the action to activate * @parameter: (nullable): parameters to the activation * @@ -580,25 +582,25 @@ g_action_group_change_action_state (GActionGroup *action_group, * * If the action is expecting a parameter, then the correct type of * parameter must be given as @parameter. If the action is expecting no - * parameters then @parameter must be %NULL. See - * g_action_group_get_action_parameter_type(). + * parameters then @parameter must be `NULL`. See + * [method@Gio.ActionGroup.get_action_parameter_type]. * - * If the #GActionGroup implementation supports asynchronous remote + * If the [type@Gio.ActionGroup] implementation supports asynchronous remote * activation over D-Bus, this call may return before the relevant * D-Bus traffic has been sent, or any replies have been received. In * order to block on such asynchronous activation calls, - * g_dbus_connection_flush() should be called prior to the code, which + * [method@Gio.DBusConnection.flush] should be called prior to the code, which * depends on the result of the action activation. Without flushing * the D-Bus connection, there is no guarantee that the action would * have been activated. * * The following code which runs in a remote app instance, shows an * example of a "quit" action being activated on the primary app - * instance over D-Bus. Here g_dbus_connection_flush() is called - * before `exit()`. Without g_dbus_connection_flush(), the "quit" action + * instance over D-Bus. Here [method@Gio.DBusConnection.flush] is called + * before `exit()`. Without `g_dbus_connection_flush()`, the "quit" action * may fail to be activated on the primary instance. * - * |[ + * ```c * // call "quit" action on primary instance * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); * @@ -608,7 +610,7 @@ g_action_group_change_action_state (GActionGroup *action_group, * g_debug ("application has been terminated. exiting."); * * exit (0); - * ]| + * ``` * * Since: 2.28 **/ @@ -626,12 +628,12 @@ g_action_group_activate_action (GActionGroup *action_group, /** * g_action_group_action_added: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of an action in the group * - * Emits the #GActionGroup::action-added signal on @action_group. + * Emits the [signal@Gio.ActionGroup::action-added] signal on @action_group. * - * This function should only be called by #GActionGroup implementations. + * This function should only be called by [type@Gio.ActionGroup] implementations. * * Since: 2.28 **/ @@ -650,12 +652,12 @@ g_action_group_action_added (GActionGroup *action_group, /** * g_action_group_action_removed: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of an action in the group * - * Emits the #GActionGroup::action-removed signal on @action_group. + * Emits the [signal@Gio.ActionGroup::action-removed] signal on @action_group. * - * This function should only be called by #GActionGroup implementations. + * This function should only be called by [type@Gio.ActionGroup] implementations. * * Since: 2.28 **/ @@ -674,13 +676,13 @@ g_action_group_action_removed (GActionGroup *action_group, /** * g_action_group_action_enabled_changed: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of an action in the group * @enabled: whether or not the action is now enabled * - * Emits the #GActionGroup::action-enabled-changed signal on @action_group. + * Emits the [signal@Gio.ActionGroup::action-enabled-changed] signal on @action_group. * - * This function should only be called by #GActionGroup implementations. + * This function should only be called by [type@Gio.ActionGroup] implementations. * * Since: 2.28 **/ @@ -703,13 +705,13 @@ g_action_group_action_enabled_changed (GActionGroup *action_group, /** * g_action_group_action_state_changed: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of an action in the group * @state: the new state of the named action * - * Emits the #GActionGroup::action-state-changed signal on @action_group. + * Emits the [signal@Gio.ActionGroup::action-state-changed] signal on @action_group. * - * This function should only be called by #GActionGroup implementations. + * This function should only be called by [type@Gio.ActionGroup] implementations. * * Since: 2.28 **/ @@ -730,29 +732,29 @@ g_action_group_action_state_changed (GActionGroup *action_group, /** * g_action_group_query_action: - * @action_group: a #GActionGroup + * @action_group: a [type@Gio.ActionGroup] * @action_name: the name of an action in the group * @enabled: (out): if the action is presently enabled - * @parameter_type: (out) (transfer none) (optional): the parameter type, or %NULL if none needed - * @state_type: (out) (transfer none) (optional): the state type, or %NULL if stateless - * @state_hint: (out) (optional): the state hint, or %NULL if none - * @state: (out) (optional): the current state, or %NULL if stateless + * @parameter_type: (out) (transfer none) (optional): the parameter type, or `NULL` if none needed + * @state_type: (out) (transfer none) (optional): the state type, or `NULL` if stateless + * @state_hint: (out) (optional): the state hint, or `NULL` if none + * @state: (out) (optional): the current state, or `NULL` if stateless * * Queries all aspects of the named action within an @action_group. * * This function acquires the information available from - * g_action_group_has_action(), g_action_group_get_action_enabled(), - * g_action_group_get_action_parameter_type(), - * g_action_group_get_action_state_type(), - * g_action_group_get_action_state_hint() and - * g_action_group_get_action_state() with a single function call. + * [method@Gio.ActionGroup.has_action], [method@Gio.ActionGroup.get_action_enabled], + * [method@Gio.ActionGroup.get_action_parameter_type], + * [method@Gio.ActionGroup.get_action_state_type], + * [method@Gio.ActionGroup.get_action_state_hint] and + * [method@Gio.ActionGroup.get_action_state] with a single function call. * * This provides two main benefits. * * The first is the improvement in efficiency that comes with not having * to perform repeated lookups of the action in order to discover * different things about it. The second is that implementing - * #GActionGroup can now be done by only overriding this one virtual + * [type@Gio.ActionGroup] can now be done by only overriding this one virtual * function. * * The interface provides a default implementation of this function that @@ -761,12 +763,12 @@ g_action_group_action_state_changed (GActionGroup *action_group, * those functions that call this function. All implementations, * therefore, must override either this function or all of the others. * - * If the action exists, %TRUE is returned and any of the requested - * fields (as indicated by having a non-%NULL reference passed in) are - * filled. If the action doesn't exist, %FALSE is returned and the + * If the action exists, `TRUE` is returned and any of the requested + * fields (as indicated by having a non-`NULL` reference passed in) are + * filled. If the action doesn't exist, `FALSE` is returned and the * fields may or may not have been modified. * - * Returns: %TRUE if the action exists, else %FALSE + * Returns: `TRUE` if the action exists, else `FALSE` * * Since: 2.32 **/