From 6d80135342692c6a26ff964a89ead01a2bfdd32f Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval R Date: Wed, 5 Jan 2022 12:36:55 +0100 Subject: 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, -- cgit v1.2.1