From 658bb30f061e46612cd36bccd049e15f2d32637c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:55:38 +0100 Subject: [PATCH] docs: Move the GPropertyAction SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gpropertyaction.c | 53 +++++++++++++++++-------------------------- 1 file changed, 21 insertions(+), 32 deletions(-) diff --git a/gio/gpropertyaction.c b/gio/gpropertyaction.c index 52eae84e5..ae8903c04 100644 --- a/gio/gpropertyaction.c +++ b/gio/gpropertyaction.c @@ -28,17 +28,14 @@ #include "glibintl.h" /** - * SECTION:gpropertyaction - * @title: GPropertyAction - * @short_description: A GAction reflecting a GObject property - * @include: gio/gio.h + * GPropertyAction: * - * A #GPropertyAction is a way to get a #GAction with a state value - * reflecting and controlling the value of a #GObject property. + * A `GPropertyAction` is a way to get a [iface@Gio.Action] with a state value + * reflecting and controlling the value of a [class@GObject.Object] property. * * The state of the action will correspond to the value of the property. * Changing it will change the property (assuming the requested value - * matches the requirements as specified in the #GParamSpec). + * matches the requirements as specified in the [type@GObject.ParamSpec]). * * Only the most common types are presently supported. Booleans are * mapped to booleans, strings to strings, signed/unsigned integers to @@ -46,16 +43,16 @@ * * If the property is an enum then the state will be string-typed and * conversion will automatically be performed between the enum value and - * "nick" string as per the #GEnumValue table. + * ‘nick’ string as per the [type@GObject.EnumValue] table. * * Flags types are not currently supported. * * Properties of object types, boxed types and pointer types are not * supported and probably never will be. * - * Properties of #GVariant types are not currently supported. + * Properties of [type@GLib.Variant] types are not currently supported. * - * If the property is boolean-valued then the action will have a NULL + * If the property is boolean-valued then the action will have a `NULL` * parameter type, and activating the action (with no parameter) will * toggle the value of the property. * @@ -64,26 +61,26 @@ * * The general idea here is to reduce the number of locations where a * particular piece of state is kept (and therefore has to be synchronised - * between). #GPropertyAction does not have a separate state that is kept - * in sync with the property value -- its state is the property value. + * between). `GPropertyAction` does not have a separate state that is kept + * in sync with the property value — its state is the property value. * - * For example, it might be useful to create a #GAction corresponding to - * the "visible-child-name" property of a #GtkStack so that the current - * page can be switched from a menu. The active radio indication in the + * For example, it might be useful to create a [iface@Gio.Action] corresponding + * to the `visible-child-name` property of a [class@Gtk.Stack] so that the + * current page can be switched from a menu. The active radio indication in the * menu is then directly determined from the active page of the - * #GtkStack. + * [class@Gtk.Stack]. * - * An anti-example would be binding the "active-id" property on a - * #GtkComboBox. This is because the state of the combobox itself is + * An anti-example would be binding the `active-id` property on a + * [class@Gtk.ComboBox]. This is because the state of the combobox itself is * probably uninteresting and is actually being used to control * something else. * - * Another anti-example would be to bind to the "visible-child-name" - * property of a #GtkStack if this value is actually stored in - * #GSettings. In that case, the real source of the value is - * #GSettings. If you want a #GAction to control a setting stored in - * #GSettings, see g_settings_create_action() instead, and possibly - * combine its use with g_settings_bind(). + * Another anti-example would be to bind to the `visible-child-name` + * property of a [class@Gtk.Stack] if this value is actually stored in + * [class@Gio.Settings]. In that case, the real source of the value is + * [class@Gio.Settings]. If you want a [iface@Gio.Action] to control a setting + * stored in [class@Gio.Settings], see [method@Gio.Settings.create_action] + * instead, and possibly combine its use with [method@Gio.Settings.bind]. * * Since: 2.38 **/ @@ -98,14 +95,6 @@ struct _GPropertyAction gboolean invert_boolean; }; -/** - * GPropertyAction: - * - * This type is opaque. - * - * Since: 2.38 - **/ - typedef GObjectClass GPropertyActionClass; static void g_property_action_iface_init (GActionInterface *iface);