[gtk/ebassi/gidocgen] expression: Update docs format

[Emmanuele Bassi <ebassi src gnome org>]

commit 45e62e61df92fef84632a2f4b43a99e9d072c7e8
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Feb 22 17:35:39 2021 +0000

    expression: Update docs format
    
    And add documentation stanzas for GtkExpression sub-types.

 gtk/gtkexpression.c | 389 ++++++++++++++++++++++++++++------------------------
 1 file changed, 210 insertions(+), 179 deletions(-)
---
diff --git a/gtk/gtkexpression.c b/gtk/gtkexpression.c
index bbe19ad301..f565746529 100644
--- a/gtk/gtkexpression.c
+++ b/gtk/gtkexpression.c
@@ -36,9 +36,9 @@
  *
  * An important aspect of expressions is that the value can be obtained
  * from a source that is several steps away. For example, an expression
- * may describe ‘the value of property A of @object1, which is itself the
- * value of a property of @object2’. And @object1 may not even exist yet
- * at the time that the expression is created. This is contrast to GObject
+ * may describe ‘the value of property A of `object1`, which is itself the
+ * value of a property of `object2`’. And `object1` may not even exist yet
+ * at the time that the expression is created. This is contrast to `GObject`
  * property bindings, which can only create direct connections between
  * the properties of two objects that must both exist for the duration
  * of the binding.
@@ -47,53 +47,56 @@
  * refers to. An evaluation always happens in the context of a current object
  * called `this` (it mirrors the behavior of object-oriented languages),
  * which may or may not influence the result of the evaluation. Use
- * gtk_expression_evaluate() for evaluating an expression.
+ * [method@Gtk.Expression.evaluate] for evaluating an expression.
  *
  * Various methods for defining expressions exist, from simple constants via
- * gtk_constant_expression_new() to looking up properties in a #GObject (even
- * recursively) via gtk_property_expression_new() or providing custom functions
- * to transform and combine expressions via gtk_closure_expression_new().
+ * [ctor Gtk ConstantExpression new] to looking up properties in a `GObject`
+ * (even recursively) via [ctor Gtk PropertyExpression new] or providing
+ * custom functions to transform and combine expressions via
+ * [ctor Gtk ClosureExpression new].
  *
  * Here is an example of a complex expression:
- * |[
+ *
+ * ```c
  *   color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM,
  *                                             NULL, "item");
  *   expression = gtk_property_expression_new (GTK_TYPE_COLOR,
  *                                             color_expr, "name");
- * ]|
+ * ```
  *
- * when evaluated with `this` being a GtkListItem, it will obtain the
- * "item" property from the GtkListItem, and then obtain the "name" property
- * from the resulting object (which is assumed to be of type GTK_TYPE_COLOR).
+ * when evaluated with `this` being a `GtkListItem`, it will obtain the
+ * "item" property from the `GtkListItem`, and then obtain the "name" property
+ * from the resulting object (which is assumed to be of type `GTK_TYPE_COLOR`).
  *
  * A more concise way to describe this would be
- * |[
+ *
+ * ```
  *   this->item->name
- * ]|
+ * ```
  *
  * The most likely place where you will encounter expressions is in the context
- * of list models and list widgets using them. For example, #GtkDropDown is
- * evaluating a GtkExpression to obtain strings from the items in its model
+ * of list models and list widgets using them. For example, `GtkDropDown` is
+ * evaluating a `GtkExpression` to obtain strings from the items in its model
  * that it can then use to match against the contents of its search entry.
- * #GtkStringFilter is using a GtkExpression for similar reasons.
+ * `GtkStringFilter` is using a `GtkExpression` for similar reasons.
  *
  * By default, expressions are not paying attention to changes and evaluation is
  * just a snapshot of the current state at a given time. To get informed about
- * changes, an expression needs to be "watched" via a #GtkExpressionWatch, which
- * will cause a callback to be called whenever the value of the expression may
- * have changed. gtk_expression_watch() starts watching an expression, and
- * gtk_expression_watch_unwatch() stops.
+ * changes, an expression needs to be "watched" via a [struct@Gtk.ExpressionWatch],
+ * which will cause a callback to be called whenever the value of the expression may
+ * have changed; [method@Gtk.Expression.watch] starts watching an expression, and
+ * [method@Gtk.ExpressionWatch.unwatch] stops.
  *
  * Watches can be created for automatically updating the property of an object,
- * similar to GObject's #GBinding mechanism, by using gtk_expression_bind().
+ * similar to GObject's `GBinding` mechanism, by using [method Gtk Expression bind].
  *
- * # GtkExpression in GObject properties
+ * ## GtkExpression in GObject properties
  *
- * In order to use a #GtkExpression as a #GObject property, you must use the
- * gtk_param_spec_expression() when creating a #GParamSpec to install in the
- * #GObject class being defined; for instance:
+ * In order to use a `GtkExpression` as a `GObject` property, you must use the
+ * [id@gtk_param_spec_expression] when creating a `GParamSpec` to install in the
+ * `GObject` class being defined; for instance:
  *
- * |[
+ * ```c
  *   obj_props[PROP_EXPRESSION] =
  *     gtk_param_spec_expression ("expression",
  *                                "Expression",
@@ -101,14 +104,14 @@
  *                                G_PARAM_READWRITE |
  *                                G_PARAM_STATIC_STRINGS |
  *                                G_PARAM_EXPLICIT_NOTIFY);
- * ]|
+ * ```
  *
- * When implementing the #GObjectClass.set_property() and #GObjectClass.get_property()
- * virtual functions, you must use gtk_value_get_expression(), to retrieve the
- * stored #GtkExpression from the #GValue container, and gtk_value_set_expression(),
- * to store the #GtkExpression into the #GValue; for instance:
+ * When implementing the `GObjectClass.set_property` and `GObjectClass.get_property`
+ * virtual functions, you must use [id@gtk_value_get_expression], to retrieve the
+ * stored `GtkExpression` from the `GValue` container, and [id@gtk_value_set_expression],
+ * to store the `GtkExpression` into the `GValue`; for instance:
  *
- * |[
+ * ```c
  *   // in set_property()...
  *   case PROP_EXPRESSION:
  *     foo_widget_set_expression (foo, gtk_value_get_expression (value));
@@ -118,45 +121,44 @@
  *   case PROP_EXPRESSION:
  *     gtk_value_set_expression (value, foo->expression);
  *     break;
- * ]|
+ * ```
  *
- * # GtkExpression in .ui files
+ * ## GtkExpression in .ui files
  *
- * GtkBuilder has support for creating expressions. The syntax here can be used where
- * a #GtkExpression object is needed like in a <property> tag for an expression
- * property, or in a <binding> tag to bind a property to an expression.
+ * `GtkBuilder` has support for creating expressions. The syntax here can be used where
+ * a `GtkExpression` object is needed like in a `<property>` tag for an expression
+ * property, or in a `<binding>` tag to bind a property to an expression.
  *
- * To create an property expression, use the <lookup> element. It can have a `type`
+ * To create an property expression, use the `<lookup>` element. It can have a `type`
  * attribute to specify the object type, and a `name` attribute to specify the property
- * to look up. The content of <lookup> can either be an element specfiying the expression
+ * to look up. The content of `<lookup>` can either be an element specfiying the expression
  * to use the object, or a string that specifies the name of the object to use.
  *
  * Example:
- * |[
+ *
+ * ```xml
  *   <lookup name='search'>string_filter</lookup>
- * ]|
+ * ```
  *
- * To create a constant expression, use the <constant> element. If the type attribute
+ * To create a constant expression, use the `<constant>` element. If the type attribute
  * is specified, the element content is interpreted as a value of that type. Otherwise,
- * it is assumed to be an object.
+ * it is assumed to be an object. For instance:
  *
- * Example:
- * |[
+ * ```xml
  *   <constant>string_filter</constant>
  *   <constant type='gchararray'>Hello, world</constant>
- * ]|
+ * ```
  *
- * To create a closure expression, use the <closure> element. The `type` and `function`
+ * To create a closure expression, use the `<closure>` element. The `type` and `function`
  * attributes specify what function to use for the closure, the content of the element
- * contains the expressions for the parameters.
+ * contains the expressions for the parameters. For instance:
  *
- * Example:
- * |[
+ * ```xml
  *   <closure type='gchararray' function='combine_args_somehow'>
  *     <constant type='gchararray'>File size:</constant>
  *     <lookup type='GFile' name='size'>myfile</lookup>
  *   </closure>
- * ]|
+ * ```
  */
 
 
@@ -222,6 +224,14 @@ struct _GtkExpressionTypeInfo
                                                  GtkExpressionSubWatch  *watch);
 };
 
+/**
+ * GtkExpressionWatch:
+ *
+ * An opaque structure representing a watched [class@Gtk.Expression].
+ *
+ * The contents of `GtkExpressionWatch` should only be accessed through the
+ * provided API.
+ */
 struct _GtkExpressionWatch
 {
   GtkExpression         *expression;
@@ -352,12 +362,12 @@ value_expression_lcopy_value (const GValue *value,
 
 /**
  * gtk_value_set_expression:
- * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
- * @expression: a #GtkExpression
+ * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
+ * @expression: a `GtkExpression`
  *
- * Stores the given #GtkExpression inside @value.
+ * Stores the given `GtkExpression` inside `value`.
  *
- * The #GValue will acquire a reference to the @expression.
+ * The `GValue` will acquire a reference to the `expression`.
  */
 void
 gtk_value_set_expression (GValue        *value,
@@ -384,12 +394,12 @@ gtk_value_set_expression (GValue        *value,
 
 /**
  * gtk_value_take_expression:
- * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
- * @expression: (transfer full) (nullable): a #GtkExpression
+ * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
+ * @expression: (transfer full) (nullable): a `GtkExpression`
  *
- * Stores the given #GtkExpression inside @value.
+ * Stores the given `GtkExpression` inside `value`.
  *
- * This function transfers the ownership of the @expression to the #GValue.
+ * This function transfers the ownership of the `expression` to the `GValue`.
  */
 void
 gtk_value_take_expression (GValue        *value,
@@ -416,11 +426,11 @@ gtk_value_take_expression (GValue        *value,
 
 /**
  * gtk_value_get_expression:
- * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
+ * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
  *
- * Retrieves the #GtkExpression stored inside the given @value.
+ * Retrieves the `GtkExpression` stored inside the given `value`.
  *
- * Returns: (transfer none) (nullable): a #GtkExpression
+ * Returns: (transfer none) (nullable): a `GtkExpression`
  */
 GtkExpression *
 gtk_value_get_expression (const GValue *value)
@@ -432,12 +442,12 @@ gtk_value_get_expression (const GValue *value)
 
 /**
  * gtk_value_dup_expression:
- * @value: a #GValue initialized with type %GTK_TYPE_EXPRESSION
+ * @value: a `GValue` initialized with type `GTK_TYPE_EXPRESSION`
  *
- * Retrieves the #GtkExpression stored inside the given @value, and acquires
+ * Retrieves the `GtkExpression` stored inside the given `value`, and acquires
  * a reference to it.
  *
- * Returns: (transfer full) (nullable): a #GtkExpression
+ * Returns: (transfer full) (nullable): a `GtkExpression`
  */
 GtkExpression *
 gtk_value_dup_expression (const GValue *value)
@@ -529,9 +539,9 @@ gtk_param_expression_get_type (void)
  * @blurb: a user-readable description of the property
  * @flags: flags for the property
  *
- * Creates a new #GParamSpec instance for a property holding a #GtkExpression.
+ * Creates a new `GParamSpec` instance for a property holding a `GtkExpression`.
  *
- * See g_param_spec_internal() for details on the property strings.
+ * See `g_param_spec_internal()` for details on the property strings.
  *
  * Returns: (transfer full): a newly created property specification
  */
@@ -707,7 +717,7 @@ gtk_expression_type_register_static (const char                  *type_name,
  * @expression_type: the type of expression to create
  * @value_type: the type of the value returned by this expression
  *
- * Returns: (transfer full): the newly created #GtkExpression
+ * Returns: (transfer full): the newly created `GtkExpression`
  */
 static gpointer
 gtk_expression_alloc (GType expression_type,
@@ -743,8 +753,11 @@ gtk_expression_subwatch_finish (GtkExpression         *self,
 
 /* {{{ GtkConstantExpression */
 
-typedef struct _GtkConstantExpression GtkConstantExpression;
-
+/**
+ * GtkConstantExpression:
+ *
+ * A constant value in a `GtkExpression`.
+ */
 struct _GtkConstantExpression
 {
   GtkExpression parent;
@@ -801,10 +814,10 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkConstantExpression,
  * @value_type: The type of the object
  * @...: arguments to create the object from
  *
- * Creates a GtkExpression that evaluates to the
+ * Creates a `GtkExpression` that evaluates to the
  * object given by the arguments.
  *
- * Returns: a new #GtkExpression
+ * Returns: (transfer full) (type GtkConstantExpression): a new `GtkExpression`
  */
 GtkExpression *
 gtk_constant_expression_new (GType value_type,
@@ -838,12 +851,12 @@ gtk_constant_expression_new (GType value_type,
 }
 
 /**
- * gtk_constant_expression_new_for_value:
- * @value: a #GValue
+ * gtk_constant_expression_new_for_value: (constructor)
+ * @value: a `GValue`
  *
- * Creates an expression that always evaluates to the given @value.
+ * Creates an expression that always evaluates to the given `value`.
  *
- * Returns: a new #GtkExpression
+ * Returns: (transfer full) (type GtkConstantExpression):  a new `GtkExpression`
  **/
 GtkExpression *
 gtk_constant_expression_new_for_value (const GValue *value)
@@ -864,7 +877,7 @@ gtk_constant_expression_new_for_value (const GValue *value)
 
 /**
  * gtk_constant_expression_get_value:
- * @expression: (type GtkConstantExpression): a constant #GtkExpression
+ * @expression: (type GtkConstantExpression): a constant `GtkExpression`
  *
  * Gets the value that a constant expression evaluates to.
  *
@@ -884,9 +897,13 @@ gtk_constant_expression_get_value (GtkExpression *expression)
 
 /* {{{ GtkObjectExpression */
 
-typedef struct _GtkObjectExpression GtkObjectExpression;
 typedef struct _GtkObjectExpressionWatch GtkObjectExpressionWatch;
 
+/**
+ * GtkObjectExpression:
+ *
+ * A `GObject` value in a `GtkExpression`.
+ */
 struct _GtkObjectExpression
 {
   GtkExpression parent;
@@ -999,16 +1016,18 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkObjectExpression,
                             &gtk_object_expression_info)
 
 /**
- * gtk_object_expression_new:
+ * gtk_object_expression_new: (constructor)
  * @object: (transfer none): object to watch
  *
- * Creates an expression evaluating to the given @object with a weak reference.
- * Once the @object is disposed, it will fail to evaluate.
+ * Creates an expression evaluating to the given `object` with a weak reference.
+ *
+ * Once the `object` is disposed, it will fail to evaluate.
+ *
  * This expression is meant to break reference cycles.
  *
- * If you want to keep a reference to @object, use gtk_constant_expression_new().
+ * If you want to keep a reference to `object`, use [ctor Gtk ConstantExpression new].
  *
- * Returns: a new #GtkExpression
+ * Returns: (type GtkObjectExpression) (transfer full): a new `GtkExpression`
  **/
 GtkExpression *
 gtk_object_expression_new (GObject *object)
@@ -1029,11 +1048,11 @@ gtk_object_expression_new (GObject *object)
 
 /**
  * gtk_object_expression_get_object:
- * @expression: (type GtkObjectExpression): an object #GtkExpression
+ * @expression: (type GtkObjectExpression): an object `GtkExpression`
  *
  * Gets the object that the expression evaluates to.
  *
- * Returns: (transfer none) (nullable): the object, or %NULL
+ * Returns: (transfer none) (nullable): the object, or `NULL`
  */
 GObject *
 gtk_object_expression_get_object (GtkExpression *expression)
@@ -1049,8 +1068,11 @@ gtk_object_expression_get_object (GtkExpression *expression)
 
 /* {{{ GtkPropertyExpression */
 
-typedef struct _GtkPropertyExpression GtkPropertyExpression;
-
+/**
+ * GtkPropertyExpression:
+ *
+ * A `GObject` property value in a `GtkExpression`.
+ */
 struct _GtkPropertyExpression
 {
   GtkExpression parent;
@@ -1264,24 +1286,24 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkPropertyExpression,
                             &gtk_property_expression_info)
 
 /**
- * gtk_property_expression_new:
+ * gtk_property_expression_new: (constructor)
  * @this_type: The type to expect for the this type
  * @expression: (nullable) (transfer full): Expression to
- *     evaluate to get the object to query or %NULL to
- *     query the `this` object
+ *   evaluate to get the object to query or `NULL` to
+ *   query the `this` object
  * @property_name: name of the property
  *
  * Creates an expression that looks up a property via the
- * given @expression or the `this` argument when @expression
- * is %NULL.
+ * given `expression` or the `this` argument when `expression`
+ * is `NULL`.
  *
- * If the resulting object conforms to @this_type, its property
- * named @property_name will be queried.
- * Otherwise, this expression's evaluation will fail.
+ * If the resulting object conforms to `this_type`, its property named
+ * `property_name` will be queried. Otherwise, this expression's
+ * evaluation will fail.
  *
- * The given @this_type must have a property with @property_name.
+ * The given `this_type` must have a property with `property_name`.
  *
- * Returns: a new #GtkExpression
+ * Returns: (type GtkPropertyExpression) (transfer full): a new `GtkExpression`
  **/
 GtkExpression *
 gtk_property_expression_new (GType          this_type,
@@ -1318,21 +1340,21 @@ gtk_property_expression_new (GType          this_type,
 }
 
 /**
- * gtk_property_expression_new_for_pspec:
+ * gtk_property_expression_new_for_pspec: (constructor)
  * @expression: (nullable) (transfer full): Expression to
- *     evaluate to get the object to query or %NULL to
- *     query the `this` object
- * @pspec: the #GParamSpec for the property to query
+ *   evaluate to get the object to query or `NULL` to
+ *   query the `this` object
+ * @pspec: the `GParamSpec` for the property to query
  *
  * Creates an expression that looks up a property via the
- * given @expression or the `this` argument when @expression
- * is %NULL.
+ * given `expression` or the `this` argument when `expression`
+ * is `NULL`.
  *
- * If the resulting object conforms to @this_type, its
- * property specified by @pspec will be queried.
+ * If the resulting object conforms to `this_type`, its
+ * property specified by `pspec` will be queried.
  * Otherwise, this expression's evaluation will fail.
  *
- * Returns: a new #GtkExpression
+ * Returns: (type GtkPropertyExpression) (transfer full): a new `GtkExpression`
  **/
 GtkExpression *
 gtk_property_expression_new_for_pspec (GtkExpression *expression,
@@ -1352,7 +1374,7 @@ gtk_property_expression_new_for_pspec (GtkExpression *expression,
 
 /**
  * gtk_property_expression_get_expression:
- * @expression: (type GtkPropertyExpression): a property #GtkExpression
+ * @expression: (type GtkPropertyExpression): a property `GtkExpression`
  *
  * Gets the expression specifying the object of
  * a property expression.
@@ -1371,12 +1393,12 @@ gtk_property_expression_get_expression (GtkExpression *expression)
 
 /**
  * gtk_property_expression_get_pspec:
- * @expression: (type GtkPropertyExpression): a property #GtkExpression
+ * @expression: (type GtkPropertyExpression): a property `GtkExpression`
  *
- * Gets the #GParamSpec specifying the property of
+ * Gets the `GParamSpec` specifying the property of
  * a property expression.
  *
- * Returns: (transfer none): the #GParamSpec
+ * Returns: (transfer none): the `GParamSpec` for the property
  */
 GParamSpec *
 gtk_property_expression_get_pspec (GtkExpression *expression)
@@ -1392,8 +1414,12 @@ gtk_property_expression_get_pspec (GtkExpression *expression)
 
 /* {{{ GtkClosureExpression */
 
-typedef struct _GtkClosureExpression GtkClosureExpression;
-
+/**
+ * GtkClosureExpression:
+ *
+ * An expression using a custom `GClosure` to compute the value from
+ * its parameters.
+ */
 struct _GtkClosureExpression
 {
   GtkExpression parent;
@@ -1580,17 +1606,17 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkClosureExpression,
                             &gtk_closure_expression_info)
 
 /**
- * gtk_closure_expression_new:
+ * gtk_closure_expression_new: (constructor)
  * @value_type: the type of the value that this expression evaluates to
  * @closure: closure to call when evaluating this expression. If closure is floating, it is adopted
- * @n_params: the number of params needed for evaluating @closure
+ * @n_params: the number of params needed for evaluating `closure`
  * @params: (nullable) (array length=n_params) (transfer full): expressions for each parameter
  *
- * Creates a GtkExpression that calls @closure when it is evaluated.
- * @closure is called with the @this object and the results of evaluating
- * the @params expressions.
+ * Creates a `GtkExpression` that calls `closure` when it is evaluated.
+ * `closure` is called with the `this` object and the results of evaluating
+ * the `params` expressions.
  *
- * Returns: a new #GtkExpression
+ * Returns: (transfer full) (type GtkClosureExpression): a new `GtkExpression`
  */
 GtkExpression *
 gtk_closure_expression_new (GType                value_type,
@@ -1625,8 +1651,11 @@ gtk_closure_expression_new (GType                value_type,
 
 /* {{{ GtkCClosureExpression */
 
-typedef struct _GtkCClosureExpression GtkCClosureExpression;
-
+/**
+ * GtkCClosureExpression:
+ *
+ * A variant of [class@Gtk.ClosureExpression] using a C closure.
+ */
 struct _GtkCClosureExpression
 {
   GtkClosureExpression parent;
@@ -1649,7 +1678,7 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression,
                             &gtk_cclosure_expression_info)
 
 /**
- * gtk_cclosure_expression_new:
+ * gtk_cclosure_expression_new: (constructor)
  * @value_type: the type of the value that this expression evaluates to
  * @marshal: (scope call) (nullable): marshaller used for creating a closure
  * @n_params: the number of params needed for evaluating @closure
@@ -1658,11 +1687,11 @@ GTK_DEFINE_EXPRESSION_TYPE (GtkCClosureExpression,
  * @user_data: (nullable): user data used for creating a closure
  * @user_destroy: (nullable): destroy notify for @user_data
  *
- * This function is a variant of gtk_closure_expression_new() that
- * creates a #GClosure by calling g_cclosure_new() with the given
- * @callback_func, @user_data and @user_destroy.
+ * This function is a variant of [ctor Gtk ClosureExpression new] that
+ * creates a `GClosure` by calling `g_cclosure_new()` with the given
+ * `callback_func`, `user_data` and `user_destroy`.
  *
- * Returns: a new #GtkExpression
+ * Returns: (transfer full) (type GtkCClosureExpression): a new `GtkExpression`
  */
 GtkExpression *
 gtk_cclosure_expression_new (GType                value_type,
@@ -1707,11 +1736,11 @@ gtk_cclosure_expression_new (GType                value_type,
 
 /**
  * gtk_expression_ref:
- * @self: (allow-none): a #GtkExpression
+ * @self: a `GtkExpression`
  *
- * Acquires a reference on the given #GtkExpression.
+ * Acquires a reference on the given `GtkExpression`.
  *
- * Returns: (transfer none): the #GtkExpression with an additional reference
+ * Returns: (transfer full): the `GtkExpression` with an additional reference
  */
 GtkExpression *
 gtk_expression_ref (GtkExpression *self)
@@ -1725,11 +1754,11 @@ gtk_expression_ref (GtkExpression *self)
 
 /**
  * gtk_expression_unref:
- * @self: (allow-none): a #GtkExpression
+ * @self: (transfer full): a `GtkExpression`
  *
- * Releases a reference on the given #GtkExpression.
+ * Releases a reference on the given `GtkExpression`.
  *
- * If the reference was the last, the resources associated to the @self are
+ * If the reference was the last, the resources associated to the `self` are
  * freed.
  */
 void
@@ -1743,12 +1772,12 @@ gtk_expression_unref (GtkExpression *self)
 
 /**
  * gtk_expression_get_value_type:
- * @self: a #GtkExpression
+ * @self: a `GtkExpression`
  *
- * Gets the #GType that this expression evaluates to. This type
+ * Gets the `GType` that this expression evaluates to. This type
  * is constant and will not change over the lifetime of this expression.
  *
- * Returns: The type returned from gtk_expression_evaluate()
+ * Returns: The type returned from [method@Gtk.Expression.evaluate]
  **/
 GType
 gtk_expression_get_value_type (GtkExpression *self)
@@ -1760,20 +1789,22 @@ gtk_expression_get_value_type (GtkExpression *self)
 
 /**
  * gtk_expression_evaluate:
- * @self: a #GtkExpression
+ * @self: a `GtkExpression`
  * @this_: (transfer none) (type GObject) (nullable): the this argument for the evaluation
- * @value: an empty #GValue
+ * @value: an empty `GValue`
  *
  * Evaluates the given expression and on success stores the result
- * in @value. The #GType of @value will be the type given by
- * gtk_expression_get_value_type().
+ * in @value.
+ *
+ * The `GType` of `value` will be the type given by
+ * [method@Gtk.Expression.get_value_type].
  *
  * It is possible that expressions cannot be evaluated - for example
  * when the expression references objects that have been destroyed or
- * set to %NULL. In that case @value will remain empty and %FALSE
+ * set to `NULL`. In that case `value` will remain empty and `FALSE`
  * will be returned.
  *
- * Returns: %TRUE if the expression could be evaluated
+ * Returns: `TRUE` if the expression could be evaluated
  **/
 gboolean
 gtk_expression_evaluate (GtkExpression *self,
@@ -1789,17 +1820,17 @@ gtk_expression_evaluate (GtkExpression *self,
 
 /**
  * gtk_expression_is_static:
- * @self: a #GtkExpression
+ * @self: a `GtkExpression`
  *
  * Checks if the expression is static.
  *
  * A static expression will never change its result when 
- * gtk_expression_evaluate() is called on it with the same arguments.
+ * [method@Gtk.Expression.evaluate] is called on it with the same arguments.
  *
- * That means a call to gtk_expression_watch() is not necessary because
+ * That means a call to [method@Gtk.Expression.watch] is not necessary because
  * it will never trigger a notify.
  *
- * Returns: %TRUE if the expression is static
+ * Returns: `TRUE` if the expression is static
  **/
 gboolean
 gtk_expression_is_static (GtkExpression *self)
@@ -1840,26 +1871,26 @@ gtk_expression_watch_cb (gpointer data)
 
 /**
  * gtk_expression_watch:
- * @self: a #GtkExpression
+ * @self: a `GtkExpression`
  * @this_: (transfer none) (type GObject) (nullable): the `this` argument to
  *     watch
  * @notify: (closure user_data): callback to invoke when the
  *     expression changes
- * @user_data: user data to pass to @notify callback
- * @user_destroy: destroy notify for @user_data
+ * @user_data: user data to pass to the `notify` callback
+ * @user_destroy: destroy notify for `user_data`
  *
- * Installs a watch for the given @expression that calls the @notify function
- * whenever the evaluation of @self may have changed.
+ * Installs a watch for the given `expression` that calls the `notify` function
+ * whenever the evaluation of `self` may have changed.
  *
  * GTK cannot guarantee that the evaluation did indeed change when the @notify
  * gets invoked, but it guarantees the opposite: When it did in fact change,
- * the @notify will be invoked.
+ * the `notify` will be invoked.
  *
  * Returns: (transfer none): The newly installed watch. Note that the only
- *     reference held to the watch will be released when the watch is unwatched
- *     which can happen automatically, and not just via
- *     gtk_expression_watch_unwatch(). You should call gtk_expression_watch_ref()
- *     if you want to keep the watch around.
+ *   reference held to the watch will be released when the watch is unwatched
+ *   which can happen automatically, and not just via
+ *   [method@Gtk.ExpressionWatch.unwatch]. You should call [method Gtk ExpressionWatch ref]
+ *   if you want to keep the watch around.
  **/
 GtkExpressionWatch *
 gtk_expression_watch (GtkExpression       *self,
@@ -1895,11 +1926,11 @@ gtk_expression_watch (GtkExpression       *self,
 
 /**
  * gtk_expression_watch_ref:
- * @watch: (allow-none): a #GtkExpressionWatch
+ * @watch: a `GtkExpressionWatch`
  *
- * Acquires a reference on the given #GtkExpressionWatch.
+ * Acquires a reference on the given `GtkExpressionWatch`.
  *
- * Returns: (transfer none): the #GtkExpression with an additional reference
+ * Returns: (transfer full): the `GtkExpressionWatch` with an additional reference
  */
 GtkExpressionWatch *
 gtk_expression_watch_ref (GtkExpressionWatch *watch)
@@ -1917,11 +1948,11 @@ gtk_expression_watch_finalize (gpointer data)
 
 /**
  * gtk_expression_watch_unref:
- * @watch: (allow-none): a #GtkExpressionWatch
+ * @watch: (transfer full): a `GtkExpressionWatch`
  *
- * Releases a reference on the given #GtkExpressionWatch.
+ * Releases a reference on the given `GtkExpressionWatch`.
  *
- * If the reference was the last, the resources associated to @self are
+ * If the reference was the last, the resources associated to `self` are
  * freed.
  */
 void
@@ -1934,7 +1965,7 @@ gtk_expression_watch_unref (GtkExpressionWatch *watch)
  * gtk_expression_watch_unwatch:
  * @watch: (transfer none): watch to release
  *
- * Stops watching an expression that was established via gtk_expression_watch().
+ * Stops watching an expression that was established via [method@Gtk.Expression.watch].
  **/
 void
 gtk_expression_watch_unwatch (GtkExpressionWatch *watch)
@@ -1957,16 +1988,16 @@ gtk_expression_watch_unwatch (GtkExpressionWatch *watch)
 
 /**
  * gtk_expression_watch_evaluate:
- * @watch: a #GtkExpressionWatch
- * @value: an empty #GValue to be set
+ * @watch: a `GtkExpressionWatch`
+ * @value: an empty `GValue` to be set
  *
  * Evaluates the watched expression and on success stores the result
- * in @value.
+ * in `value`.
  *
- * This is equivalent to calling gtk_expression_evaluate() with the
- * expression and this pointer originally used to create @watch.
+ * This is equivalent to calling [method@Gtk.Expression.evaluate] with the
+ * expression and this pointer originally used to create `watch`.
  *
- * Returns: %TRUE if the expression could be evaluated and @value was set
+ * Returns: `TRUE` if the expression could be evaluated and `value` was set
  **/
 gboolean
 gtk_expression_watch_evaluate (GtkExpressionWatch *watch,
@@ -2072,26 +2103,26 @@ gtk_expression_bind_notify (gpointer data)
 
 /**
  * gtk_expression_bind:
- * @self: (transfer full): a #GtkExpression
+ * @self: (transfer full): a `GtkExpression`
  * @target: (transfer none) (type GObject): the target object to bind to
- * @property: name of the property on @target to bind to
+ * @property: name of the property on `target` to bind to
  * @this_: (transfer none) (type GObject) (nullable): the this argument for
- *     the evaluation of @self
+ *     the evaluation of `self`
  *
- * Bind @target's property named @property to @self.
+ * Bind `target`'s property named `property` to `self`.
  *
- * The value that @self evaluates to is set via g_object_set() on
- * @target. This is repeated whenever @self changes to ensure that
- * the object's property stays synchronized with @self.
+ * The value that `self` evaluates to is set via `g_object_set()` on
+ * `target`. This is repeated whenever `self` changes to ensure that
+ * the object's property stays synchronized with `self`.
  *
- * If @self's evaluation fails, @target's @property is not updated.
+ * If `self`'s evaluation fails, `target`'s `property` is not updated.
  * You can ensure that this doesn't happen by using a fallback
  * expression.
  *
- * Note that this function takes ownership of @self. If you want
- * to keep it around, you should gtk_expression_ref() it beforehand.
+ * Note that this function takes ownership of `self`. If you want
+ * to keep it around, you should [method Gtk Expression ref] it beforehand.
  *
- * Returns: (transfer none): a #GtkExpressionWatch
+ * Returns: (transfer none): a `GtkExpressionWatch`
  **/
 GtkExpressionWatch *
 gtk_expression_bind (GtkExpression *self,