Merge branch 'gsktransform-improve-docs' into 'main'

gsktransform: Document consuming functions

See merge request GNOME/gtk!7342

gsk/gsktransform.c

@@ -489,6 +489,9 @@ gsk_transform_matrix_with_category (GskTransform            *next,
  *
  * Multiplies @next with the given @matrix.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: The new transform
  **/
 GskTransform *
@@ -643,6 +646,9 @@ static const GskTransformClass GSK_TRANSLATE_TRANSFORM_CLASS =
  *
  * Translates @next in 2-dimensional space by @point.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  **/
 GskTransform *
@@ -663,6 +669,9 @@ gsk_transform_translate (GskTransform           *next,
  *
  * Translates @next by @point.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  **/
 GskTransform *
@@ -880,6 +889,9 @@ normalize_angle (float angle)
  * Rotates @next @angle degrees in 2D - or in 3D-speak, around the Z axis.
  * The rotation happens around the origin point of (0, 0).
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  */
 GskTransform *
@@ -1008,6 +1020,9 @@ static const GskTransformClass GSK_ROTATE3D_TRANSFORM_CLASS =
  *
  * For a rotation in 2D space, use [method@Gsk.Transform.rotate]
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  */
 GskTransform *
@@ -1184,6 +1199,9 @@ static const GskTransformClass GSK_SKEW_TRANSFORM_CLASS =
  *
  * Applies a skew transform.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  *
  * Since: 4.6
@@ -1356,6 +1374,9 @@ static const GskTransformClass GSK_SCALE_TRANSFORM_CLASS =
  *
  * Use [method@Gsk.Transform.scale_3d] to scale in all 3 dimensions.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  **/
 GskTransform *
@@ -1375,6 +1396,9 @@ gsk_transform_scale (GskTransform *next,
  *
  * Scales @next by the given factors.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  **/
 GskTransform *
@@ -1510,6 +1534,9 @@ static const GskTransformClass GSK_PERSPECTIVE_TRANSFORM_CLASS =
  * those with negative Z values towards the origin. Points
  * on the z=0 plane are unchanged.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: The new transform
  */
 GskTransform *
@@ -1919,6 +1946,9 @@ gsk_transform_to_translate (GskTransform *self,
  *
  * Applies all the operations from @other to @next.
  *
+ * This function consumes @next. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The new transform
  */
 GskTransform *
@@ -1955,6 +1985,9 @@ gsk_transform_transform (GskTransform *next,
  * between those cases, you should check @self is not %NULL
  * before calling this function.
  *
+ * This function consumes @self. Use [method@Gsk.Transform.ref] first
+ * if you want to keep it around.
+ *
  * Returns: (nullable): The inverted transform
  */
 GskTransform *