From 57d6b945f176f0ce58e66c2f28e48ab65ca21979 Mon Sep 17 00:00:00 2001 From: Sudhanshu Tiwari Date: Thu, 28 Mar 2024 17:08:25 +0530 Subject: [PATCH] Ported the remaining documentation comments in gio/gaction.c to GI-Docgen --- gio/gaction.c | 99 ++++++++++++++++++++++++++------------------------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/gio/gaction.c b/gio/gaction.c index bde7d3861..912e72f4f 100644 --- a/gio/gaction.c +++ b/gio/gaction.c @@ -39,7 +39,7 @@ G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT) * parameter type (which is given at construction time). * * An action may optionally have a state, in which case the state may be - * set with [method@Gio.Action.change_state]. This call takes a #GVariant. The + * set with [method@Gio.Action.change_state]. This call takes a [type@GLib.Variant]. The * correct type for the state is determined by a static state type * (which is given at construction time). * @@ -143,7 +143,7 @@ g_action_default_init (GActionInterface *iface) /** * GAction:state: * - * The state of the action, or %NULL if the action is stateless. + * The state of the action, or `NULL` if the action is stateless. * * Since: 2.28 **/ @@ -157,19 +157,19 @@ g_action_default_init (GActionInterface *iface) /** * g_action_change_state: - * @action: a #GAction + * @action: a [type@Gio.Action] * @value: the new state * * Request for the state of @action to be changed to @value. * * The action must be stateful and @value must be of the correct type. - * See g_action_get_state_type(). + * See [method@Gio.Action.get_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_get_state_hint(). + * See [method@Gio.Action.get_state_hint]. * - * If the @value GVariant is floating, it is consumed. + * If the @value [type@GLib.Variant] is floating, it is consumed. * * Since: 2.30 **/ @@ -195,16 +195,16 @@ g_action_change_state (GAction *action, /** * g_action_get_state: - * @action: a #GAction + * @action: a [type@Gio.Action] * * Queries the current state of @action. * - * 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_get_state_type(). + * given by [method@Gio.Action.get_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 * @@ -221,7 +221,7 @@ g_action_get_state (GAction *action) /** * g_action_get_name: - * @action: a #GAction + * @action: a [type@Gio.Action] * * Queries the name of @action. * @@ -240,16 +240,17 @@ g_action_get_name (GAction *action) /** * g_action_get_parameter_type: - * @action: a #GAction + * @action: a [type@Gio.Action] * * Queries the type of the parameter that must be given when activating * @action. * - * When activating the action using g_action_activate(), the #GVariant - * given to that function must be of the type returned by this function. + * When activating the action using [method@Gio.Action.activate], 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. * * Returns: (nullable): the parameter type * @@ -266,20 +267,20 @@ g_action_get_parameter_type (GAction *action) /** * g_action_get_state_type: - * @action: a #GAction + * @action: a [type@Gio.Action] * * Queries the type of the state of @action. * * If the action is stateful (e.g. created with - * g_simple_action_new_stateful()) then this function returns the - * #GVariantType of the state. This is the type of the initial value - * given as the state. All calls to g_action_change_state() must give a - * #GVariant of this type and g_action_get_state() will return a - * #GVariant of the same type. + * [ctor@Gio.SimpleAction.new_stateful]) then this function returns the + * [type@GLib.VariantType] of the state. This is the type of the initial value + * given as the state. All calls to [method@Gio.Action.change_state] must give a + * [type@GLib.Variant] of this type and [method@Gio.Action.get_state] will return a + * [type@GLib.Variant] of the same type. * - * If the action is not stateful (e.g. created with g_simple_action_new()) - * then this function will return %NULL. In that case, g_action_get_state() - * will return %NULL and you must not call g_action_change_state(). + * If the action is not stateful (e.g. created with [ctor@Gio.SimpleAction.new]) + * then this function will return `NULL`. In that case, [method@Gio.Action.get_state] + * will return `NULL` and you must not call [method@Gio.Action.change_state]. * * Returns: (nullable): the state type, if the action is stateful * @@ -296,17 +297,17 @@ g_action_get_state_type (GAction *action) /** * g_action_get_state_hint: - * @action: a #GAction + * @action: a [type@Gio.Action] * * Requests a hint about the valid range of values for the state of * @action. * - * 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. * @@ -314,8 +315,8 @@ g_action_get_state_type (GAction *action) * 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 * @@ -332,7 +333,7 @@ g_action_get_state_hint (GAction *action) /** * g_action_get_enabled: - * @action: a #GAction + * @action: a [type@Gio.Action] * * Checks if @action is currently enabled. * @@ -354,16 +355,16 @@ g_action_get_enabled (GAction *action) /** * g_action_activate: - * @action: a #GAction + * @action: a [type@Gio.Action] * @parameter: (nullable): the parameter to the activation * * Activates the action. * * @parameter must be the correct type of parameter for the action (ie: * the parameter type given at construction time). If the parameter - * type was %NULL then @parameter must also be %NULL. + * type was `NULL` then @parameter must also be `NULL`. * - * If the @parameter GVariant is floating, it is consumed. + * If the @parameter [type@GLib.Variant] is floating, it is consumed. * * Since: 2.28 **/ @@ -390,12 +391,12 @@ g_action_activate (GAction *action, * Checks if @action_name is valid. * * @action_name is valid if it consists only of alphanumeric characters, - * plus '-' and '.'. The empty string is not a valid action name. + * plus `-` and `.`. The empty string is not a valid action name. * - * It is an error to call this function with a non-utf8 @action_name. - * @action_name must not be %NULL. + * It is an error to call this function with a non-UTF-8 @action_name. + * @action_name must not be `NULL`. * - * Returns: %TRUE if @action_name is valid + * Returns: `TRUE` if @action_name is valid * * Since: 2.38 **/ @@ -419,8 +420,8 @@ g_action_name_is_valid (const gchar *action_name) * @detailed_name: a detailed action name * @action_name: (out) (optional) (not nullable) (transfer full): the action name * @target_value: (out) (optional) (nullable) (transfer full): the target value, - * or %NULL for no target - * @error: a pointer to a %NULL #GError, or %NULL + * or `NULL` for no target + * @error: a pointer to a `NULL` [type@GLib.Error], or `NULL` * * Parses a detailed action name into its separate name and target * components. @@ -440,20 +441,20 @@ g_action_name_is_valid (const gchar *action_name) * The third format is used to represent an action with any type of * target value, including strings. The target value follows the action * name, surrounded in parens. For example: `app.action(42)`. The - * target value is parsed using g_variant_parse(). If a tuple-typed + * target value is parsed using [func@GLib.Variant.parse]. If a tuple-typed * value is desired, it must be specified in the same way, resulting in * two sets of parens, for example: `app.action((1,2,3))`. A string * target can be specified this way as well: `app.action('target')`. * For strings, this third format must be used if target value is * empty or contains characters other than alphanumerics, `-` and `.`. * - * If this function returns %TRUE, a non-%NULL value is guaranteed to be returned - * in @action_name (if a pointer is passed in). A %NULL value may still be + * If this function returns `TRUE`, a non-`NULL` value is guaranteed to be returned + * in @action_name (if a pointer is passed in). A `NULL` value may still be * returned in @target_value, as the @detailed_name may not contain a target. * - * If returned, the #GVariant in @target_value is guaranteed to not be floating. + * If returned, the [type@GLib.Variant] in @target_value is guaranteed to not be floating. * - * Returns: %TRUE if successful, else %FALSE with @error set + * Returns: `TRUE` if successful, else `FALSE` with @error set * * Since: 2.38 **/ @@ -531,13 +532,13 @@ bad_fmt: /** * g_action_print_detailed_name: * @action_name: a valid action name - * @target_value: (nullable): a #GVariant target value, or %NULL + * @target_value: (nullable): a [type@GLib.Variant] target value, or `NULL` * * Formats a detailed action name from @action_name and @target_value. * * It is an error to call this function with an invalid action name. * - * This function is the opposite of g_action_parse_detailed_name(). + * This function is the opposite of [func@Gio.Action.parse_detailed_name]. * It will produce a string that can be parsed back to the @action_name * and @target_value by that function. *