[gtk/ebassi/gidocgen: 141/501] constraint: Port to the new docs format

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 141/501] constraint: Port to the new docs format
Date: Fri, 5 Mar 2021 15:53:30 +0000 (UTC)

commit f7d7c08a9fd3e1f4437373a479ed73f51c4887b4
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Feb 23 15:12:45 2021 +0000

    constraint: Port to the new docs format
    
     - Drop the "SECTION".
     - Add attributes annotations for properties and getter methods.
     - Remove excessive linking and redundant types

 gtk/gtkconstraint.c | 152 +++++++++++++++++++++++++++-------------------------
 gtk/gtkconstraint.h |  13 -----
 2 files changed, 78 insertions(+), 87 deletions(-)
---
diff --git a/gtk/gtkconstraint.c b/gtk/gtkconstraint.c
index 90008d3dfe..a707465a32 100644
--- a/gtk/gtkconstraint.c
+++ b/gtk/gtkconstraint.c
@@ -18,17 +18,15 @@
  */
 
 /**
- * SECTION:gtkconstraint
- * @Title: GtkConstraint
- * @Short_description: The description of a constraint
+ * GtkConstraint:
  *
  * `GtkConstraint` describes a constraint between an attribute on a widget
  * and another attribute on another widget, expressed as a linear equation.
  *
- * For instance:
+ * The typical equation for a constraint is:
  *
  * ```
- *   target.attr1 = source.attr2 × multiplier + constant
+ *   target.target_attr = source.source_attr × multiplier + constant
  * ```
  *
  * Each `GtkConstraint` is part of a system that will be solved by a
@@ -180,13 +178,15 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
   gobject_class->finalize = gtk_constraint_finalize;
 
   /**
-   * GtkConstraint:target:
+   * GtkConstraint:target: (attributes org.gtk.Property.get=gtk_constraint_get_target)
    *
    * The target of the constraint.
    *
    * The constraint will set the #GtkConstraint:target-attribute of the
    * target using the #GtkConstraint:source-attribute of the source
    * widget.
+   *
+   *
    */
   obj_props[PROP_TARGET] =
     g_param_spec_object ("target",
@@ -197,7 +197,7 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                          G_PARAM_STATIC_STRINGS |
                          G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:target-attribute:
+   * GtkConstraint:target-attribute: (attributes org.gtk.Property.get=gtk_constraint_get_target_attribute)
    *
    * The attribute of the #GtkConstraint:target set by the constraint.
    */
@@ -211,7 +211,7 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                        G_PARAM_STATIC_STRINGS |
                        G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:relation:
+   * GtkConstraint:relation: (attributes org.gtk.Property.get=gtk_constraint_get_relation)
    *
    * The order relation between the terms of the constraint.
    */
@@ -225,12 +225,13 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                        G_PARAM_STATIC_STRINGS |
                        G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:source:
+   * GtkConstraint:source: (attributes org.gtk.Property.get=gtk_constraint_get_source)
    *
    * The source of the constraint.
    *
-   * The constraint will set the #GtkConstraint:target-attribute of the
-   * target using the #GtkConstraint:source-attribute of the source.
+   * The constraint will set the [property@Gtk.Constraint:target-attribute]
+   * of the target using the [property@Gtk.Constraint:source-attribute]
+   * of the source.
    */
   obj_props[PROP_SOURCE] =
     g_param_spec_object ("source",
@@ -241,9 +242,10 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                          G_PARAM_STATIC_STRINGS |
                          G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:source-attribute:
+   * GtkConstraint:source-attribute: (attributes org.gtk.Property.get=gtk_constraint_get_source_attribute)
    *
-   * The attribute of the #GtkConstraint:source read by the constraint.
+   * The attribute of the [property@Gtk.Constraint:source] read by the
+   * constraint.
    */
   obj_props[PROP_SOURCE_ATTRIBUTE] =
     g_param_spec_enum ("source-attribute",
@@ -255,10 +257,10 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                        G_PARAM_STATIC_STRINGS |
                        G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:multiplier:
+   * GtkConstraint:multiplier: (attributes org.gtk.Property.get=gtk_constraint_get_multiplier)
    *
-   * The multiplication factor to be applied to the
-   * #GtkConstraint:source-attribute.
+   * The multiplication factor to be applied to
+   * the [property@Gtk.Constraint:source-attribute].
    */
   obj_props[PROP_MULTIPLIER] =
     g_param_spec_double ("multiplier",
@@ -269,9 +271,9 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                          G_PARAM_STATIC_STRINGS |
                          G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:constant:
+   * GtkConstraint:constant: (attributes org.gtk.Property.get=gtk_constraint_get_constant)
    *
-   * The constant value to be added to the #GtkConstraint:source-attribute.
+   * The constant value to be added to the [property@Gtk.Constraint:source-attribute].
    */
   obj_props[PROP_CONSTANT] =
     g_param_spec_double ("constant",
@@ -282,12 +284,12 @@ gtk_constraint_class_init (GtkConstraintClass *klass)
                          G_PARAM_STATIC_STRINGS |
                          G_PARAM_CONSTRUCT_ONLY);
   /**
-   * GtkConstraint:strength:
+   * GtkConstraint:strength: (attributes org.gtk.Property.get=gtk_constraint_get_strength)
    *
    * The strength of the constraint.
    *
    * The strength can be expressed either using one of the symbolic values
-   * of the #GtkConstraintStrength enumeration, or any positive integer
+   * of the [enum@Gtk.ConstraintStrength] enumeration, or any positive integer
    * value.
    */
   obj_props[PROP_STRENGTH] =
@@ -316,20 +318,20 @@ gtk_constraint_init (GtkConstraint *self)
 }
 
 /**
- * gtk_constraint_new:
- * @target: (nullable) (type GtkConstraintTarget): a #GtkConstraintTarget
- * @target_attribute: the attribute of @target to be set
- * @relation: the relation equivalence between @target_attribute and @source_attribute
- * @source: (nullable) (type GtkConstraintTarget): a #GtkConstraintTarget
- * @source_attribute: the attribute of @source to be read
- * @multiplier: a multiplication factor to be applied to @source_attribute
- * @constant: a constant factor to be added to @source_attribute
+ * gtk_constraint_new: (constructor)
+ * @target: (nullable) (type GtkConstraintTarget): the target of the constraint
+ * @target_attribute: the attribute of `target` to be set
+ * @relation: the relation equivalence between `target_attribute` and `source_attribute`
+ * @source: (nullable) (type GtkConstraintTarget): the source of the constraint
+ * @source_attribute: the attribute of `source` to be read
+ * @multiplier: a multiplication factor to be applied to `source_attribute`
+ * @constant: a constant factor to be added to `source_attribute`
  * @strength: the strength of the constraint
  *
- * Creates a new #GtkConstraint representing a relation between a layout
+ * Creates a new constraint representing a relation between a layout
  * attribute on a source and a layout attribute on a target.
  *
- * Returns: the newly created #GtkConstraint
+ * Returns: (transfer full): the newly created constraint
  */
 GtkConstraint *
 gtk_constraint_new (gpointer                target,
@@ -357,17 +359,17 @@ gtk_constraint_new (gpointer                target,
 }
 
 /**
- * gtk_constraint_new_constant:
- * @target: (nullable) (type GtkConstraintTarget): a #GtkConstraintTarget
- * @target_attribute: the attribute of @target to be set
- * @relation: the relation equivalence between @target_attribute and @constant
- * @constant: a constant factor to be set on @target_attribute
+ * gtk_constraint_new_constant: (constructor)
+ * @target: (nullable) (type GtkConstraintTarget): a the target of the constraint
+ * @target_attribute: the attribute of `target` to be set
+ * @relation: the relation equivalence between `target_attribute` and `constant`
+ * @constant: a constant factor to be set on `target_attribute`
  * @strength: the strength of the constraint
  *
- * Creates a new #GtkConstraint representing a relation between a layout
+ * Creates a new constraint representing a relation between a layout
  * attribute on a target and a constant value.
  *
- * Returns: the newly created #GtkConstraint
+ * Returns: (transfer full): the newly created constraint
  */
 GtkConstraint *
 gtk_constraint_new_constant (gpointer                target,
@@ -389,13 +391,14 @@ gtk_constraint_new_constant (gpointer                target,
 }
 
 /**
- * gtk_constraint_get_target:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_target: (attributes org.gtk.Method.get_property=target)
+ * @constraint: a `GtkConstraint`
  *
- * Retrieves the #GtkConstraintTarget used as the target for @constraint.
+ * Retrieves the [iface@Gtk.ConstraintTarget] used as the target for
+ * the constraint.
  *
- * If the #GtkConstraint:target property is set to %NULL, the @constraint
- * will use the #GtkConstraintLayout's widget.
+ * If the targe is set to `NULL` at creation, the constraint will use
+ * the widget using the [class@Gtk.ConstraintLayout] as the target.
  *
  * Returns: (transfer none) (nullable): a #GtkConstraintTarget
  */
@@ -408,10 +411,10 @@ gtk_constraint_get_target (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_target_attribute:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_target_attribute: (attributes org.gtk.Method.get_property=target-attribute)
+ * @constraint: a `GtkConstraint`
  *
- * Retrieves the attribute of the target to be set by the @constraint.
+ * Retrieves the attribute of the target to be set by the constraint.
  *
  * Returns: the target's attribute
  */
@@ -424,15 +427,16 @@ gtk_constraint_get_target_attribute (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_source:
+ * gtk_constraint_get_source: (attributes org.gtk.Method.get_property=source)
  * @constraint: a #GtkConstraint
  *
- * Retrieves the #GtkConstraintTarget used as the source for @constraint.
+ * Retrieves the [iface@Gtk.ConstraintTarget] used as the source for the
+ * constraint.
  *
- * If the #GtkConstraint:source property is set to %NULL, the @constraint
- * will use the #GtkConstraintLayout's widget.
+ * If the source is set to `NULL` at creation, the constraint will use
+ * the widget using the [class@Gtk.ConstraintLayout] as the source.
  *
- * Returns: (transfer none) (nullable): a #GtkConstraintTarget
+ * Returns: (transfer none) (nullable): the source of the constraint
  */
 GtkConstraintTarget *
 gtk_constraint_get_source (GtkConstraint *constraint)
@@ -443,12 +447,12 @@ gtk_constraint_get_source (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_source_attribute:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_source_attribute: (attributes org.gtk.Method.get_property=source-attribute)
+ * @constraint: a `GtkConstraint`
  *
- * Retrieves the attribute of the source to be read by the @constraint.
+ * Retrieves the attribute of the source to be read by the constraint.
  *
- * Returns: the target's attribute
+ * Returns: the source's attribute
  */
 GtkConstraintAttribute
 gtk_constraint_get_source_attribute (GtkConstraint *constraint)
@@ -459,12 +463,12 @@ gtk_constraint_get_source_attribute (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_relation:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_relation: (attributes org.gtk.Method.get_property=relation)
+ * @constraint: a `GtkConstraint`
  *
- * The order relation between the terms of the @constraint.
+ * The order relation between the terms of the constraint.
  *
- * Returns: a #GtkConstraintRelation value
+ * Returns: a relation type
  */
 GtkConstraintRelation
 gtk_constraint_get_relation (GtkConstraint *constraint)
@@ -475,8 +479,8 @@ gtk_constraint_get_relation (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_multiplier:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_multiplier: (attributes org.gtk.Method.get_property=multiplier)
+ * @constraint: a `GtkConstraint`
  *
  * Retrieves the multiplication factor applied to the source
  * attribute's value.
@@ -492,8 +496,8 @@ gtk_constraint_get_multiplier (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_constant:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_constant: (attributes org.gtk.Method.get_property=constant)
+ * @constraint: a `GtkConstraint`
  *
  * Retrieves the constant factor added to the source attributes' value.
  *
@@ -508,12 +512,12 @@ gtk_constraint_get_constant (GtkConstraint *constraint)
 }
 
 /**
- * gtk_constraint_get_strength:
- * @constraint: a #GtkConstraint
+ * gtk_constraint_get_strength: (attributes org.gtk.Method.get_property=strength)
+ * @constraint: a `GtkConstraint`
  *
  * Retrieves the strength of the constraint.
  *
- * Returns: the strength of the constraint
+ * Returns: the strength value
  */
 int
 gtk_constraint_get_strength (GtkConstraint *constraint)
@@ -525,9 +529,9 @@ gtk_constraint_get_strength (GtkConstraint *constraint)
 
 /**
  * gtk_constraint_is_required:
- * @constraint: a #GtkConstraint
+ * @constraint: a `GtkConstraint`
  *
- * Checks whether the @constraint is a required relation for solving the
+ * Checks whether the constraint is a required relation for solving the
  * constraint layout.
  *
  * Returns: %TRUE if the constraint is required
@@ -542,12 +546,12 @@ gtk_constraint_is_required (GtkConstraint *constraint)
 
 /**
  * gtk_constraint_is_attached:
- * @constraint: a #GtkConstraint
+ * @constraint: a `GtkConstraint`
  *
- * Checks whether the @constraint is attached to a #GtkConstraintLayout,
+ * Checks whether the constraint is attached to a [class@Gtk.ConstraintLayout],
  * and it is contributing to the layout.
  *
- * Returns: %TRUE if the constraint is attached
+ * Returns: `TRUE` if the constraint is attached
  */
 gboolean
 gtk_constraint_is_attached (GtkConstraint *constraint)
@@ -559,12 +563,12 @@ gtk_constraint_is_attached (GtkConstraint *constraint)
 
 /**
  * gtk_constraint_is_constant:
- * @constraint: a #GtkConstraint
+ * @constraint: a `GtkConstraint`
  *
- * Checks whether the @constraint describes a relation between an attribute
- * on the #GtkConstraint:target and a constant value.
+ * Checks whether the constraint describes a relation between an attribute
+ * on the [property@Gtk.Constraint:target] and a constant value.
  *
- * Returns: %TRUE if the constraint is a constant relation
+ * Returns: `TRUE` if the constraint is a constant relation
  */
 gboolean
 gtk_constraint_is_constant (GtkConstraint *constraint)
diff --git a/gtk/gtkconstraint.h b/gtk/gtkconstraint.h
index 33aecfbd68..6ffd081bfa 100644
--- a/gtk/gtkconstraint.h
+++ b/gtk/gtkconstraint.h
@@ -42,19 +42,6 @@ G_DECLARE_INTERFACE (GtkConstraintTarget, gtk_constraint_target, GTK, CONSTRAINT
 
 #define GTK_TYPE_CONSTRAINT (gtk_constraint_get_type ())
 
-/**
- * GtkConstraint:
- *
- * An object describing the relation between two widget attributes.
- *
- * All relations are in the form:
- *
- * |[<!-- language=plain -->
- *   target.attr_name = source.attr_name × multiplier + constant
- * ]|
- *
- * A #GtkConstraint is immutable once it's created.
- */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_FINAL_TYPE (GtkConstraint, gtk_constraint, GTK, CONSTRAINT, GObject)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]