[gtk: 3/6] docs: Improve docs for gtksnapshot.c

[Matthias Clasen <matthiasc src gnome org>]

commit 6d80135342692c6a26ff964a89ead01a2bfdd32f
Author: Maximiliano Sandoval R <msandova gnome org>
Date:   Wed Jan 5 12:36:55 2022 +0100

    docs: Improve docs for gtksnapshot.c

 gtk/gtksnapshot.c | 63 +++++++++++++++++++++++++------------------------------
 1 file changed, 29 insertions(+), 34 deletions(-)
---
diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c
index 1b917ce384..0c05ecad0e 100644
--- a/gtk/gtksnapshot.c
+++ b/gtk/gtksnapshot.c
@@ -46,14 +46,14 @@
 /**
  * GtkSnapshot:
  *
- * `GtkSnapshot` assists in creating `GskRenderNodes` for widgets.
+ * `GtkSnapshot` assists in creating [class@Gsk.RenderNode]s for widgets.
  *
  * It functions in a similar way to a cairo context, and maintains a stack
  * of render nodes and their associated transformations.
  *
- * The node at the top of the stack is the one that gtk_snapshot_append_…
- * functions operate on. Use the gtk_snapshot_push_… functions and
- * gtk_snapshot_pop() to change the current node.
+ * The node at the top of the stack is the one that `gtk_snapshot_append_…()`
+ * functions operate on. Use the `gtk_snapshot_push_…()` functions and
+ * [method Snapshot pop] to change the current node.
  *
  * The typical way to obtain a `GtkSnapshot` object is as an argument to
  * the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own
@@ -302,7 +302,7 @@ gtk_snapshot_new (void)
  * Returns the node that was constructed by @snapshot
  * and frees @snapshot.
  *
- * Returns: (transfer full): a newly-created `GskRenderNode`
+ * Returns: (transfer full): a newly-created [class@Gsk.RenderNode]
  */
 GskRenderNode *
 gtk_snapshot_free_to_node (GtkSnapshot *snapshot)
@@ -324,7 +324,7 @@ gtk_snapshot_free_to_node (GtkSnapshot *snapshot)
  * Returns a paintable for the node that was
  * constructed by @snapshot and frees @snapshot.
  *
- * Returns: (transfer full): a newly-created `GdkPaintable`
+ * Returns: (transfer full): a newly-created [iface@Gdk.Paintable]
  */
 GdkPaintable *
 gtk_snapshot_free_to_paintable (GtkSnapshot           *snapshot,
@@ -955,11 +955,11 @@ gtk_snapshot_collect_gl_shader_texture (GtkSnapshot      *snapshot,
  * @bounds: the rectangle to render into
  * @take_args: (transfer full): Data block with arguments for the shader.
  *
- * Push a `GskGLShaderNode`.
+ * Push a [class@Gsk.GLShaderNode].
  *
  * The node uses the given [class@Gsk.GLShader] and uniform values
  * Additionally this takes a list of @n_children other nodes
- * which will be passed to the `GskGLShaderNode`.
+ * which will be passed to the [class@Gsk.GLShaderNode].
  *
  * The @take_args argument is a block of data to use for uniform
  * arguments, as per types and offsets defined by the @shader.
@@ -1495,7 +1495,7 @@ gtk_snapshot_pop_collect (GtkSnapshot *snapshot)
  *
  * After calling this function, it is no longer possible to
  * add more nodes to @snapshot. The only function that should
- * be called after this is g_object_unref().
+ * be called after this is [method@GObject.Object.unref].
  *
  * Returns: (transfer full): the constructed `GskRenderNode`
  */
@@ -1530,7 +1530,7 @@ gtk_snapshot_to_node (GtkSnapshot *snapshot)
  *
  * After calling this function, it is no longer possible to
  * add more nodes to @snapshot. The only function that should
- * be called after this is g_object_unref().
+ * be called after this is [method@GObject.Object.unref].
  *
  * Returns: (transfer full): a new `GdkPaintable`
  */
@@ -1585,7 +1585,7 @@ gtk_snapshot_pop (GtkSnapshot *snapshot)
  * @snapshot: a `GtkSnapshot`
  *
  * Removes the top element from the stack of render nodes and
- * adds it to the nearest `GskGLShaderNode` below it.
+ * adds it to the nearest [class@Gsk.GLShaderNode] below it.
  *
  * This must be called the same number of times as the number
  * of textures is needed for the shader in
@@ -1610,12 +1610,12 @@ gtk_snapshot_gl_shader_pop_texture (GtkSnapshot *snapshot)
  *
  * When [method@Gtk.Snapshot.restore] is called, @snapshot will
  * be restored to the saved state. Multiple calls to
- * gtk_snapshot_save() and gtk_snapshot_restore() can be nested;
- * each call to gtk_snapshot_restore() restores the state from
- * the matching paired gtk_snapshot_save().
+ * [method Snapshot save] and [class@Snapshot.restore] can be nested;
+ * each call to `gtk_snapshot_restore()` restores the state from
+ * the matching paired `gtk_snapshot_save()`.
  *
  * It is necessary to clear all saved states with corresponding
- * calls to gtk_snapshot_restore().
+ * calls to `gtk_snapshot_restore()`.
  */
 void
 gtk_snapshot_save (GtkSnapshot *snapshot)
@@ -1633,7 +1633,7 @@ gtk_snapshot_save (GtkSnapshot *snapshot)
  * @snapshot: a `GtkSnapshot`
  *
  * Restores @snapshot to the state saved by a preceding call to
- * gtk_snapshot_save() and removes that state from the stack of
+ * [method Snapshot save] and removes that state from the stack of
  * saved states.
  */
 void
@@ -1882,7 +1882,7 @@ gtk_snapshot_append_node (GtkSnapshot   *snapshot,
  * @snapshot: a `GtkSnapshot`
  * @bounds: the bounds for the new node
  *
- * Creates a new `GskCairoNode` and appends it to the current
+ * Creates a new [class@Gsk.CairoNode] and appends it to the current
  * render node of @snapshot, without changing the current node.
  *
  * Returns: a `cairo_t` suitable for drawing the contents of
@@ -1918,7 +1918,7 @@ gtk_snapshot_append_cairo (GtkSnapshot           *snapshot,
 /**
  * gtk_snapshot_append_texture:
  * @snapshot: a `GtkSnapshot`
- * @texture: the `GdkTexture` to render
+ * @texture: the texture to render
  * @bounds: the bounds for the new node
  *
  * Creates a new render node drawing the @texture
@@ -1948,7 +1948,7 @@ gtk_snapshot_append_texture (GtkSnapshot           *snapshot,
 /**
  * gtk_snapshot_append_color:
  * @snapshot: a `GtkSnapshot`
- * @color: the `GdkRGBA` to draw
+ * @color: the color to draw
  * @bounds: the bounds for the new node
  *
  * Creates a new render node drawing the @color into the
@@ -1982,7 +1982,7 @@ gtk_snapshot_append_color (GtkSnapshot           *snapshot,
 /**
  * gtk_snapshot_render_background:
  * @snapshot: a `GtkSnapshot`
- * @context: the `GtkStyleContext` to use
+ * @context: the style context that defines the background
  * @x: X origin of the rectangle
  * @y: Y origin of the rectangle
  * @width: rectangle width
@@ -2014,7 +2014,7 @@ gtk_snapshot_render_background (GtkSnapshot     *snapshot,
 /**
  * gtk_snapshot_render_frame:
  * @snapshot: a `GtkSnapshot`
- * @context: the `GtkStyleContext` to use
+ * @context: the style context that defines the frame
  * @x: X origin of the rectangle
  * @y: Y origin of the rectangle
  * @width: rectangle width
@@ -2046,7 +2046,7 @@ gtk_snapshot_render_frame (GtkSnapshot     *snapshot,
 /**
  * gtk_snapshot_render_focus:
  * @snapshot: a `GtkSnapshot`
- * @context: the `GtkStyleContext` to use
+ * @context: the style context that defines the focus ring
  * @x: X origin of the rectangle
  * @y: Y origin of the rectangle
  * @width: rectangle width
@@ -2078,7 +2078,7 @@ gtk_snapshot_render_focus (GtkSnapshot     *snapshot,
 /**
  * gtk_snapshot_render_layout:
  * @snapshot: a `GtkSnapshot`
- * @context: the `GtkStyleContext` to use
+ * @context: the style context that defines the text
  * @x: X origin of the rectangle
  * @y: Y origin of the rectangle
  * @layout: the `PangoLayout` to render
@@ -2152,8 +2152,7 @@ gtk_snapshot_append_text (GtkSnapshot           *snapshot,
  * @bounds: the rectangle to render the linear gradient into
  * @start_point: the point at which the linear gradient will begin
  * @end_point: the point at which the linear gradient will finish
- * @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
- *   defining the gradient
+ * @stops: (array length=n_stops): the color stops defining the gradient
  * @n_stops: the number of elements in @stops
  *
  * Appends a linear gradient node with the given stops to @snapshot.
@@ -2220,8 +2219,7 @@ gtk_snapshot_append_linear_gradient (GtkSnapshot            *snapshot,
  * @bounds: the rectangle to render the linear gradient into
  * @start_point: the point at which the linear gradient will begin
  * @end_point: the point at which the linear gradient will finish
- * @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
- *   defining the gradient
+ * @stops: (array length=n_stops): the color stops defining the gradient
  * @n_stops: the number of elements in @stops
  *
  * Appends a repeating linear gradient node with the given stops to @snapshot.
@@ -2289,8 +2287,7 @@ gtk_snapshot_append_repeating_linear_gradient (GtkSnapshot            *snapshot,
  * @center: the center point of the conic gradient
  * @rotation: the clockwise rotation in degrees of the starting angle.
  *   0 means the starting angle is the top.
- * @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
- *   defining the gradient
+ * @stops: (array length=n_stops): the color stops defining the gradient
  * @n_stops: the number of elements in @stops
  *
  * Appends a conic gradient node with the given stops to @snapshot.
@@ -2352,8 +2349,7 @@ gtk_snapshot_append_conic_gradient (GtkSnapshot            *snapshot,
  * @vradius: the vertical radius
  * @start: the start position (on the horizontal axis)
  * @end: the end position (on the horizontal axis)
- * @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
- *   defining the gradient
+ * @stops: (array length=n_stops): the color stops defining the gradient
  * @n_stops: the number of elements in @stops
  *
  * Appends a radial gradient node with the given stops to @snapshot.
@@ -2426,8 +2422,7 @@ gtk_snapshot_append_radial_gradient (GtkSnapshot            *snapshot,
  * @vradius: the vertical radius
  * @start: the start position (on the horizontal axis)
  * @end: the end position (on the horizontal axis)
- * @stops: (array length=n_stops): a pointer to an array of `GskColorStop`
- *   defining the gradient
+ * @stops: (array length=n_stops): the color stops defining the gradient
  * @n_stops: the number of elements in @stops
  *
  * Appends a repeating radial gradient node with the given stops to @snapshot.
@@ -2493,7 +2488,7 @@ gtk_snapshot_append_repeating_radial_gradient (GtkSnapshot            *snapshot,
 /**
  * gtk_snapshot_append_border:
  * @snapshot: a `GtkSnapshot`
- * @outline: a `GskRoundedRect` describing the outline of the border
+ * @outline: the outline of the border
  * @border_width: (array fixed-size=4): the stroke width of the border on
  *   the top, right, bottom and left side respectively.
  * @border_color: (array fixed-size=4): the color used on the top, right,