diff --git a/gsk/gl/gskglrenderer.h b/gsk/gl/gskglrenderer.h
index 64cf11e31c..13466fc56d 100644
--- a/gsk/gl/gskglrenderer.h
+++ b/gsk/gl/gskglrenderer.h
@@ -33,6 +33,11 @@ G_BEGIN_DECLS
 #define GSK_IS_GL_RENDERER_CLASS(klass)         (G_TYPE_CHECK_CLASS_TYPE ((klass), GSK_TYPE_GL_RENDERER))
 #define GSK_GL_RENDERER_GET_CLASS(obj)          (G_TYPE_INSTANCE_GET_CLASS ((obj), GSK_TYPE_GL_RENDERER, GskGLRendererClass))
 
+/**
+ * GskGLRenderer:
+ *
+ * A GSK renderer that is using OpenGL.
+ */
 typedef struct _GskGLRenderer                   GskGLRenderer;
 typedef struct _GskGLRendererClass              GskGLRendererClass;
 
diff --git a/gsk/gskcairorenderer.h b/gsk/gskcairorenderer.h
index 047bd69555..249b5a7b96 100644
--- a/gsk/gskcairorenderer.h
+++ b/gsk/gskcairorenderer.h
@@ -34,6 +34,14 @@ G_BEGIN_DECLS
 #define GSK_IS_CAIRO_RENDERER_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GSK_TYPE_CAIRO_RENDERER))
 #define GSK_CAIRO_RENDERER_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GSK_TYPE_CAIRO_RENDERER, GskCairoRendererClass))
 
+/**
+ * GskCairoRenderer:
+ *
+ * A GSK renderer that is using cairo.
+ *
+ * Since it is using cairo, this renderer cannot support
+ * 3D transformations.
+ */
 typedef struct _GskCairoRenderer                GskCairoRenderer;
 typedef struct _GskCairoRendererClass           GskCairoRendererClass;
 
diff --git a/gsk/gskenums.h b/gsk/gskenums.h
index 243ab67cc8..5b0afb78a3 100644
--- a/gsk/gskenums.h
+++ b/gsk/gskenums.h
@@ -201,9 +201,10 @@ typedef enum {
  * @GSK_TRANSFORM_CATEGORY_2D_TRANSLATE: The matrix is a 2D translation.
  * @GSK_TRANSFORM_CATEGORY_IDENTITY: The matrix is the identity matrix.
  *
- * The categories of matrices relevant for GSK and GTK. Note that any
- * category includes matrices of all later categories. So if you want
- * to for example check if a matrix is a 2D matrix,
+ * The categories of matrices relevant for GSK and GTK.
+ *
+ * Note that any category includes matrices of all later categories.
+ * So if you want to for example check if a matrix is a 2D matrix,
  * `category >= GSK_TRANSFORM_CATEGORY_2D` is the way to do this.
  *
  * Also keep in mind that rounding errors may cause matrices to not
@@ -233,8 +234,10 @@ typedef enum
  * @GSK_GL_UNIFORM_TYPE_VEC3: A GLSL vec3 / graphene_vec3_t uniform
  * @GSK_GL_UNIFORM_TYPE_VEC4: A GLSL vec4 / graphene_vec4_t uniform
  *
- * This defines the types of the uniforms that #GskGLShaders
- * declare. It defines both what the type is called in the GLSL shader
+ * This defines the types of the uniforms that `GskGLShaders`
+ * declare.
+ *
+ * It defines both what the type is called in the GLSL shader
  * code, and what the corresponding C type is on the Gtk side.
  */
 typedef enum
diff --git a/gsk/gskglshader.c b/gsk/gskglshader.c
index 081e8ac4a7..cbc9bff8ec 100644
--- a/gsk/gskglshader.c
+++ b/gsk/gskglshader.c
@@ -17,25 +17,26 @@
  */
 
 /**
- * SECTION:GskGLShader
+ * SECTION:gskglshader
  * @Title: GskGLShader
  * @Short_description: Fragment shaders for GSK
  *
- * A #GskGLShader is a snippet of GLSL that is meant to run in the
- * fragment shader of the rendering pipeline. A fragment shader
- * gets the coordinates being rendered as input and produces the
- * pixel values for that particular pixel. Additionally, the
- * shader can declare a set of other input arguments, called
+ * A `GskGLShader` is a snippet of GLSL that is meant to run in the
+ * fragment shader of the rendering pipeline.
+ *
+ * A fragment shader gets the coordinates being rendered as input and
+ * produces the pixel values for that particular pixel. Additionally,
+ * the shader can declare a set of other input arguments, called
  * uniforms (as they are uniform over all the calls to your shader in
  * each instance of use). A shader can also receive up to 4
  * textures that it can use as input when producing the pixel data.
  *
-  #GskGLShader is usually used with gtk_snapshot_push_gl_shader()
-* to produce a #GskGLShaderNode in the rendering hierarchy, and then
-* its input textures are constructed by rendering the child nodes to
-* textures before rendering the shader node itself. (You can pass
-* texture nodes as children if you want to directly use a texture
-* as input).
+ * `GskGLShader` is usually used with gtk_snapshot_push_gl_shader()
+ * to produce a [class@Gsk.GLShaderNode] in the rendering hierarchy,
+ * and then its input textures are constructed by rendering the child
+ * nodes to textures before rendering the shader node itself. (You can
+ * pass texture nodes as children if you want to directly use a texture
+ * as input).
  *
  * The actual shader code is GLSL code that gets combined with
  * some other code into the fragment shader. Since the exact
@@ -56,16 +57,16 @@
  *
  * The main function the shader must implement is:
  *
- * |[<!-- language="plain" -->
+ * ```glsl
  *  void mainImage(out vec4 fragColor,
  *                 in vec2 fragCoord,
  *                 in vec2 resolution,
  *                 in vec2 uv)
- * ]|
+ * ```
  *
  * Where the input @fragCoord is the coordinate of the pixel we're
  * currently rendering, relative to the boundary rectangle that was
- * specified in the #GskGLShaderNode, and @resolution is the width and
+ * specified in the `GskGLShaderNode`, and @resolution is the width and
  * height of that rectangle. This is in the typical GTK coordinate
  * system with the origin in the top left. @uv contains the u and v
  * coordinates that can be used to index a texture at the
@@ -90,26 +91,26 @@
  * Note that GTK parses the uniform declarations, so each uniform has to
  * be on a line by itself with no other code, like so:
  *
- * |[<!-- language="plain" -->
+ * ```glsl
  * uniform float u_time;
  * uniform vec3 u_color;
  * uniform sampler2D u_texture1;
  * uniform sampler2D u_texture2;
- * ]|
+ * ```
  *
  * GTK uses the the "gsk" namespace in the symbols it uses in the
  * shader, so your code should not use any symbols with the prefix gsk
  * or GSK. There are some helper functions declared that you can use:
  *
- * |[<!-- language="plain" -->
+ * ```glsl
  * vec4 GskTexture(sampler2D sampler, vec2 texCoords);
- * ]|
+ * ```
  *
  * This samples a texture (e.g. u_texture1) at the specified
  * coordinates, and containes some helper ifdefs to ensure that
  * it works on all OpenGL versions.
  *
- * You can compile the shader yourself using gsk_gl_shader_compile(),
+ * You can compile the shader yourself using [method@Gsk.GLShader.compile],
  * otherwise the GSK renderer will do it when it handling the glshader
  * node. If errors occurs, the returned @error will include the glsl
  * sources, so you can see what GSK was passing to the compiler. You
@@ -118,7 +119,7 @@
  *
  * # An example shader
  *
- * |[<!-- language="plain" -->
+ * ```glsl
  * uniform float position;
  * uniform sampler2D u_texture1;
  * uniform sampler2D u_texture2;
@@ -132,7 +133,7 @@
  *
  *   fragColor = position * source1 + (1.0 - position) * source2;
  * }
- * ]|
+ * ```
  */
 
 #include "config.h"
@@ -443,7 +444,7 @@ gsk_gl_shader_class_init (GskGLShaderClass *klass)
   /**
    * GskGLShader:sourcecode:
    *
-   * The source code for the shader, as a #GBytes.
+   * The source code for the shader, as a `GBytes`.
    */
   gsk_gl_shader_properties[GLSHADER_PROP_SOURCE] =
     g_param_spec_boxed ("source",
@@ -486,7 +487,7 @@ gsk_gl_shader_init (GskGLShader *shader)
  *
  * Creates a #GskGLShader that will render pixels using the specified code.
  *
- * Returns: (transfer full): A new #GskGLShader
+ * Returns: (transfer full): A new `GskGLShader`
  */
 GskGLShader *
 gsk_gl_shader_new_from_bytes (GBytes *sourcecode)
@@ -503,9 +504,9 @@ gsk_gl_shader_new_from_bytes (GBytes *sourcecode)
  * @resource_path: path to a resource that contains the GLSL sourcecode for
  *     the shader
  *
- * Creates a #GskGLShader that will render pixels using the specified code.
+ * Creates a `GskGLShader` that will render pixels using the specified code.
  *
- * Returns: (transfer full): A new #GskGLShader
+ * Returns: (transfer full): A new `GskGLShader`
  */
 GskGLShader *
 gsk_gl_shader_new_from_resource (const char *resource_path)
@@ -523,10 +524,12 @@ gsk_gl_shader_new_from_resource (const char *resource_path)
  * @renderer: a #GskRenderer
  * @error: location to store error in
  *
- * Tries to compile the @shader for the given @renderer, and reports
- * %FALSE with an error if there is a problem. You should use this
- * function before relying on the shader for rendering and use a
- * fallback with a simpler shader or without shaders if it fails.
+ * Tries to compile the @shader for the given @renderer.
+ *
+ * If there is a problem, this function returns %FALSE and reports
+ * an error. You should use this function before relying on the shader
+ * for rendering and use a fallback with a simpler shader or without
+ * shaders if it fails.
  *
  * Note that this will modify the rendering state (for example
  * change the current GL context) and requires the renderer to be
@@ -556,7 +559,7 @@ gsk_gl_shader_compile (GskGLShader  *shader,
 
 /**
  * gsk_gl_shader_get_source:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  *
  * Gets the GLSL sourcecode being used to render this shader.
  *
@@ -572,7 +575,7 @@ gsk_gl_shader_get_source (GskGLShader *shader)
 
 /**
  * gsk_gl_shader_get_resource:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  *
  * Gets the resource path for the GLSL sourcecode being used
  * to render this shader.
@@ -590,7 +593,7 @@ gsk_gl_shader_get_resource (GskGLShader *shader)
 
 /**
  * gsk_gl_shader_get_n_textures:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  *
  * Returns the number of textures that the shader requires.
  *
@@ -610,7 +613,7 @@ gsk_gl_shader_get_n_textures (GskGLShader *shader)
 
 /**
  * gsk_gl_shader_get_n_uniforms:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  *
  * Get the number of declared uniforms for this shader.
  *
@@ -626,7 +629,7 @@ gsk_gl_shader_get_n_uniforms (GskGLShader *shader)
 
 /**
  * gsk_gl_shader_get_uniform_name:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @idx: index of the uniform
  *
  * Get the name of the declared uniform for this shader at index @idx.
@@ -644,7 +647,7 @@ gsk_gl_shader_get_uniform_name (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_find_uniform_by_name:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @name: uniform name
  *
  * Looks for a uniform by the name @name, and returns the index
@@ -670,7 +673,7 @@ gsk_gl_shader_find_uniform_by_name (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_uniform_type:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @idx: index of the uniform
  *
  * Get the type of the declared uniform for this shader at index @idx.
@@ -688,7 +691,7 @@ gsk_gl_shader_get_uniform_type (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_uniform_offset:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @idx: index of the uniform
  *
  * Get the offset into the data block where data for this uniforms is stored.
@@ -714,7 +717,7 @@ gsk_gl_shader_get_uniforms (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_args_size:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  *
  * Get the size of the data block used to specify arguments for this shader.
  *
@@ -744,11 +747,12 @@ gsk_gl_shader_find_uniform (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_arg_float:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of float type.
  *
  * Returns: The value
@@ -776,11 +780,12 @@ gsk_gl_shader_get_arg_float (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_arg_int:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of int type.
  *
  * Returns: The value
@@ -808,11 +813,12 @@ gsk_gl_shader_get_arg_int (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_arg_uint:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of uint type.
  *
  * Returns: The value
@@ -840,11 +846,12 @@ gsk_gl_shader_get_arg_uint (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_arg_bool:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of bool type.
  *
  * Returns: The value
@@ -872,12 +879,13 @@ gsk_gl_shader_get_arg_bool (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_get_arg_vec2:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  * @out_value: location to store the uniform value in
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of vec2 type.
  */
 void
@@ -904,12 +912,13 @@ gsk_gl_shader_get_arg_vec2 (GskGLShader     *shader,
 
 /**
  * gsk_gl_shader_get_arg_vec3:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  * @out_value: location to store the uniform value in
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of vec3 type.
  */
 void
@@ -936,12 +945,13 @@ gsk_gl_shader_get_arg_vec3 (GskGLShader     *shader,
 
 /**
  * gsk_gl_shader_get_arg_vec4:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @args: uniform arguments
  * @idx: index of the uniform
  * @out_value: location to store set the uniform value in
  *
  * Gets the value of the uniform @idx in the @args block.
+ *
  * The uniform must be of vec4 type.
  */
 void
@@ -968,15 +978,16 @@ gsk_gl_shader_get_arg_vec4 (GskGLShader     *shader,
 
 /**
  * gsk_gl_shader_format_args_va:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @uniforms: name-Value pairs for the uniforms of @shader, ending
  *     with a %NULL name
  *
  * Formats the uniform data as needed for feeding the named uniforms
- * values into the shader. The argument list is a list of pairs of
- * names, and values for the types that match the declared uniforms
- * (i.e. double/int/guint/gboolean for primitive values and
- * `graphene_vecN_t *` for vecN uniforms).
+ * values into the shader.
+ *
+ * The argument list is a list of pairs of names, and values for the
+ * types that match the declared uniforms (i.e. double/int/guint/gboolean
+ * for primitive values and `graphene_vecN_t *` for vecN uniforms).
  *
  * It is an error to pass a uniform name that is not declared by the shader.
  *
@@ -984,7 +995,7 @@ gsk_gl_shader_get_arg_vec4 (GskGLShader     *shader,
  * are zero-initialized.
  *
  * Returns: (transfer full): A newly allocated block of data which can be
- *     passed to gsk_gl_shader_node_new().
+ *     passed to [ctor@Gsk.GLShaderNode.new].
  */
 GBytes *
 gsk_gl_shader_format_args_va (GskGLShader *shader,
@@ -1053,21 +1064,22 @@ gsk_gl_shader_format_args_va (GskGLShader *shader,
 
 /**
  * gsk_gl_shader_format_args:
- * @shader: a #GskGLShader
+ * @shader: a `GskGLShader`
  * @...: name-Value pairs for the uniforms of @shader, ending with
  *     a %NULL name
  *
  * Formats the uniform data as needed for feeding the named uniforms
- * values into the shader. The argument list is a list of pairs of
- * names, and values for the types that match the declared uniforms
- * (i.e. double/int/guint/gboolean for primitive values and
- * `graphene_vecN_t *` for vecN uniforms).
+ * values into the shader.
+ *
+ * The argument list is a list of pairs of names, and values for the types
+ * that match the declared uniforms (i.e. double/int/guint/gboolean for
+ * primitive values and `graphene_vecN_t *` for vecN uniforms).
  *
  * Any uniforms of the shader that are not included in the argument list
  * are zero-initialized.
  *
  * Returns: (transfer full): A newly allocated block of data which can be
- *     passed to gsk_gl_shader_node_new().
+ *     passed to [ctor@Gsk.GLShaderNode.new].
  */
 GBytes *
 gsk_gl_shader_format_args (GskGLShader *shader,
@@ -1096,14 +1108,14 @@ G_DEFINE_BOXED_TYPE (GskShaderArgsBuilder, gsk_shader_args_builder,
 
 /**
  * gsk_shader_args_builder_new:
- * @shader: a #GskGLShader
- * @initial_values: (nullable): optional #Bytes with initial values
+ * @shader: a `GskGLShader`
+ * @initial_values: (nullable): optional `GBytes` with initial values
  *
  * Allocates a builder that can be used to construct a new uniform data
  * chunk.
  *
  * Returns: (transfer full): The newly allocated builder, free with
- *     gsk_shader_args_builder_unref()
+ *     [method@Gsk.ShaderArgsBuilder.unref]
  */
 GskShaderArgsBuilder *
 gsk_shader_args_builder_new (GskGLShader *shader,
@@ -1128,21 +1140,23 @@ gsk_shader_args_builder_new (GskGLShader *shader,
 
 /**
  * gsk_shader_args_builder_to_args:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  *
- * Creates a new #GBytes args from the current state of the
- * given @builder. Any uniforms of the shader that have not
- * been explicitly set on the @builder are zero-initialized.
+ * Creates a new `GBytes` args from the current state of the
+ * given @builder.
  *
- * The given #GskShaderArgsBuilder is reset once this function returns;
+ * Any uniforms of the shader that have not been explicitly set on
+ * the @builder are zero-initialized.
+ *
+ * The given `GskShaderArgsBuilder` is reset once this function returns;
  * you cannot call this function multiple times on the same @builder instance.
  *
  * This function is intended primarily for bindings. C code should use
- * gsk_shader_args_builder_free_to_args().
+ * [method@Gsk.ShaderArgsBuilder.free_to_args].
  *
  *
- * Returns: (transfer full): the newly allocated builder, free with
- *     gsk_shader_args_builder_free()
+ * Returns: (transfer full): the newly allocated buffer with
+ *   all the args added to @builder
  */
 GBytes *
 gsk_shader_args_builder_to_args (GskShaderArgsBuilder *builder)
@@ -1153,15 +1167,16 @@ gsk_shader_args_builder_to_args (GskShaderArgsBuilder *builder)
 
 /**
  * gsk_shader_args_builder_free_to_args: (skip)
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  *
  * Creates a new #GBytes args from the current state of the
- * given @builder, and frees the @builder instance. Any uniforms
- * of the shader that have not been explicitly set on the @builder
- * are zero-initialized.
+ * given @builder, and frees the @builder instance.
  *
- * Returns: (transfer full): the newly created #GBytes
- *   with all the args added to @builder
+ * Any uniforms of the shader that have not been explicitly set
+ * on the @builder are zero-initialized.
+ *
+ * Returns: (transfer full): the newly allocated buffer with
+ *   all the args added to @builder
  */
 GBytes *
 gsk_shader_args_builder_free_to_args (GskShaderArgsBuilder *builder)
@@ -1180,9 +1195,10 @@ gsk_shader_args_builder_free_to_args (GskShaderArgsBuilder *builder)
 
 /**
  * gsk_shader_args_builder_unref:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
+ *
+ * Decreases the reference count of a `GskShaderArgBuilder` by one.
  *
- * Decreases the reference count of a #GskShaderArgBuilder by one.
  * If the resulting reference count is zero, frees the builder.
  */
 void
@@ -1203,11 +1219,11 @@ gsk_shader_args_builder_unref (GskShaderArgsBuilder *builder)
 
 /**
  * gsk_shader_args_builder_ref:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  *
- * Increases the reference count of a #GskShaderArgsBuilder by one.
+ * Increases the reference count of a `GskShaderArgsBuilder` by one.
  *
- * Returns: the passed in #GskShaderArgsBuilder
+ * Returns: the passed in `GskShaderArgsBuilder`
  */
 GskShaderArgsBuilder *
 gsk_shader_args_builder_ref (GskShaderArgsBuilder *builder)
@@ -1220,11 +1236,12 @@ gsk_shader_args_builder_ref (GskShaderArgsBuilder *builder)
 
 /**
  * gsk_shader_args_builder_set_float:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform to
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of float type.
  */
 void
@@ -1247,11 +1264,12 @@ gsk_shader_args_builder_set_float (GskShaderArgsBuilder *builder,
 
 /**
  * gsk_shader_args_builder_set_int:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform to
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of int type.
  */
 void
@@ -1274,11 +1292,12 @@ gsk_shader_args_builder_set_int (GskShaderArgsBuilder *builder,
 
 /**
  * gsk_shader_args_builder_set_uint:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform to
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of uint type.
  */
 void
@@ -1301,11 +1320,12 @@ gsk_shader_args_builder_set_uint (GskShaderArgsBuilder *builder,
 
 /**
  * gsk_shader_args_builder_set_bool:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform to
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of bool type.
  */
 void
@@ -1328,11 +1348,12 @@ gsk_shader_args_builder_set_bool (GskShaderArgsBuilder *builder,
 
 /**
  * gsk_shader_args_builder_set_vec2:
- * @builder: A #GskShaderArgsBuilder
+ * @builder: A `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform too
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of vec2 type.
  */
 void
@@ -1355,11 +1376,12 @@ gsk_shader_args_builder_set_vec2 (GskShaderArgsBuilder  *builder,
 
 /**
  * gsk_shader_args_builder_set_vec3:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform too
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of vec3 type.
  */
 void
@@ -1382,11 +1404,12 @@ gsk_shader_args_builder_set_vec3 (GskShaderArgsBuilder  *builder,
 
 /**
  * gsk_shader_args_builder_set_vec4:
- * @builder: a #GskShaderArgsBuilder
+ * @builder: a `GskShaderArgsBuilder`
  * @idx: index of the uniform
  * @value: value to set the uniform too
  *
  * Sets the value of the uniform @idx.
+ *
  * The uniform must be of vec4 type.
  */
 void
diff --git a/gsk/gskrendernode.h b/gsk/gskrendernode.h
index def26f97d6..536d98e2c4 100644
--- a/gsk/gskrendernode.h
+++ b/gsk/gskrendernode.h
@@ -98,8 +98,8 @@ struct _GskParseLocation
  * @error: the error
  * @user_data: user data
  *
- * The type of callback that is called when a parse error occurs
- * during deserialization of node data.
+ * Type of callback that is called when an error occurs
+ * during node deserialization.
  */
 typedef void           (* GskParseErrorFunc)                    (const GskParseLocation *start,
                                                                  const GskParseLocation *end,
diff --git a/gsk/gskrendernodeimpl.c b/gsk/gskrendernodeimpl.c
index 24f5abf1a5..1131df5125 100644
--- a/gsk/gskrendernodeimpl.c
+++ b/gsk/gskrendernodeimpl.c
@@ -94,7 +94,7 @@ gsk_color_node_diff (GskRenderNode  *node1,
 
 /**
  * gsk_color_node_get_color:
- * @node: (type GskColorNode): a #GskColorNode
+ * @node: (type GskColorNode): a `GskRenderNode`
  *
  * Retrieves the color of the given @node.
  *
@@ -112,13 +112,13 @@ gsk_color_node_get_color (const GskRenderNode *node)
 
 /**
  * gsk_color_node_new:
- * @rgba: a #GdkRGBA specifying a color
+ * @rgba: a `GdkRGBA` specifying a color
  * @bounds: the rectangle to render the color into
  *
- * Creates a #GskRenderNode that will render the color specified by @rgba into
+ * Creates a `GskRenderNode` that will render the color specified by @rgba into
  * the area given by @bounds.
  *
- * Returns: (transfer full) (type GskColorNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskColorNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_color_node_new (const GdkRGBA         *rgba,
@@ -243,15 +243,16 @@ gsk_linear_gradient_node_diff (GskRenderNode  *node1,
  * @bounds: the rectangle to render the linear gradient into
  * @start: the point at which the linear gradient will begin
  * @end: the point at which the linear gradient will finish
- * @color_stops: (array length=n_color_stops): a pointer to an array of #GskColorStop defining the gradient
- *   The offsets of all color steps must be increasing. The first stop's offset must be >= 0 and the last
+ * @color_stops: (array length=n_color_stops): a pointer to an array of
+ *   `GskColorStop` defining the gradient. The offsets of all color stops
+ *   must be increasing. The first stop's offset must be >= 0 and the last
  *   stop's offset must be <= 1.
  * @n_color_stops: the number of elements in @color_stops
  *
- * Creates a #GskRenderNode that will create a linear gradient from the given
+ * Creates a `GskRenderNode` that will create a linear gradient from the given
  * points and color stops, and render that into the area given by @bounds.
  *
- * Returns: (transfer full) (type GskLinearGradientNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskLinearGradientNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_linear_gradient_node_new (const graphene_rect_t  *bounds,
@@ -293,16 +294,17 @@ gsk_linear_gradient_node_new (const graphene_rect_t  *bounds,
  * @bounds: the rectangle to render the linear gradient into
  * @start: the point at which the linear gradient will begin
  * @end: the point at which the linear gradient will finish
- * @color_stops: (array length=n_color_stops): a pointer to an array of #GskColorStop defining the gradient
- *   The offsets of all color steps must be increasing. The first stop's offset must be >= 0 and the last
+ * @color_stops: (array length=n_color_stops): a pointer to an array of
+ * `GskColorStop` defining the gradient. The offsets of all color stops
+ *   must be increasing. The first stop's offset must be >= 0 and the last
  *   stop's offset must be <= 1.
  * @n_color_stops: the number of elements in @color_stops
  *
- * Creates a #GskRenderNode that will create a repeating linear gradient
+ * Creates a `GskRenderNode` that will create a repeating linear gradient
  * from the given points and color stops, and render that into the area
  * given by @bounds.
  *
- * Returns: (transfer full) (type GskRepeatingLinearGradientNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskRepeatingLinearGradientNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_repeating_linear_gradient_node_new (const graphene_rect_t  *bounds,
@@ -341,7 +343,7 @@ gsk_repeating_linear_gradient_node_new (const graphene_rect_t  *bounds,
 
 /**
  * gsk_linear_gradient_node_get_start:
- * @node: (type GskLinearGradientNode): a #GskRenderNode for a linear gradient
+ * @node: (type GskLinearGradientNode): a `GskRenderNode` for a linear gradient
  *
  * Retrieves the initial point of the linear gradient.
  *
@@ -357,7 +359,7 @@ gsk_linear_gradient_node_get_start (const GskRenderNode *node)
 
 /**
  * gsk_linear_gradient_node_get_end:
- * @node: (type GskLinearGradientNode): a #GskRenderNode for a linear gradient
+ * @node: (type GskLinearGradientNode): a `GskRenderNode` for a linear gradient
  *
  * Retrieves the final point of the linear gradient.
  *
@@ -373,7 +375,7 @@ gsk_linear_gradient_node_get_end (const GskRenderNode *node)
 
 /**
  * gsk_linear_gradient_node_get_n_color_stops:
- * @node: (type GskLinearGradientNode): a #GskRenderNode for a linear gradient
+ * @node: (type GskLinearGradientNode): a `GskRenderNode` for a linear gradient
  *
  * Retrieves the number of color stops in the gradient.
  *
@@ -389,7 +391,7 @@ gsk_linear_gradient_node_get_n_color_stops (const GskRenderNode *node)
 
 /**
  * gsk_linear_gradient_node_get_color_stops:
- * @node: (type GskLinearGradientNode): a #GskRenderNode for a linear gradient
+ * @node: (type GskLinearGradientNode): a `GskRenderNode` for a linear gradient
  * @n_stops: (out) (optional): the number of color stops in the returned array
  *
  * Retrieves the color stops in the gradient.
@@ -531,16 +533,19 @@ gsk_radial_gradient_node_diff (GskRenderNode  *node1,
  * @vradius: the vertical radius
  * @start: a percentage >= 0 that defines the start of the gradient around @center
  * @end: a percentage >= 0 that defines the end of the gradient around @center
- * @color_stops: (array length=n_color_stops): a pointer to an array of #GskColorStop defining the gradient
- *   The offsets of all color steps must be increasing. The first stop's offset must be >= 0 and the last
+ * @color_stops: (array length=n_color_stops): a pointer to an array of
+ *   `GskColorStop` defining the gradient. The offsets of all color stops
+ *   must be increasing. The first stop's offset must be >= 0 and the last
  *   stop's offset must be <= 1.
  * @n_color_stops: the number of elements in @color_stops
  *
- * Creates a #GskRenderNode that draws a radial gradient. The radial gradient
+ * Creates a `GskRenderNode` that draws a radial gradient.
+ *
+ * The radial gradient
  * starts around @center. The size of the gradient is dictated by @hradius
  * in horizontal orientation and by @vradius in vertial orientation.
  *
- * Returns: (transfer full) (type GskRadialGradientNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskRadialGradientNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_radial_gradient_node_new (const graphene_rect_t  *bounds,
@@ -596,16 +601,19 @@ gsk_radial_gradient_node_new (const graphene_rect_t  *bounds,
  * @vradius: the vertical radius
  * @start: a percentage >= 0 that defines the start of the gradient around @center
  * @end: a percentage >= 0 that defines the end of the gradient around @center
- * @color_stops: (array length=n_color_stops): a pointer to an array of #GskColorStop defining the gradient
- *   The offsets of all color steps must be increasing. The first stop's offset must be >= 0 and the last
+ * @color_stops: (array length=n_color_stops): a pointer to an array of
+ *   `GskColorStop` defining the gradient. The offsets of all color stops
+ *   must be increasing. The first stop's offset must be >= 0 and the last
  *   stop's offset must be <= 1.
  * @n_color_stops: the number of elements in @color_stops
  *
- * Creates a #GskRenderNode that draws a repeating radial gradient. The radial gradient
- * starts around @center. The size of the gradient is dictated by @hradius
- * in horizontal orientation and by @vradius in vertial orientation.
+ * Creates a `GskRenderNode` that draws a repeating radial gradient.
  *
- * Returns: (transfer full) (type GskRepeatingRadialGradientNode): A new #GskRenderNode
+ * The radial gradient starts around @center. The size of the gradient
+ * is dictated by @hradius in horizontal orientation and by @vradius
+ * in vertial orientation.
+ *
+ * Returns: (transfer full) (type GskRepeatingRadialGradientNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_repeating_radial_gradient_node_new (const graphene_rect_t  *bounds,
@@ -655,7 +663,7 @@ gsk_repeating_radial_gradient_node_new (const graphene_rect_t  *bounds,
 
 /**
  * gsk_radial_gradient_node_get_n_color_stops:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  *
  * Retrieves the number of color stops in the gradient.
  *
@@ -671,7 +679,7 @@ gsk_radial_gradient_node_get_n_color_stops (const GskRenderNode *node)
 
 /**
  * gsk_radial_gradient_node_get_color_stops:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  * @n_stops: (out) (optional): the number of color stops in the returned array
  *
  * Retrieves the color stops in the gradient.
@@ -692,7 +700,7 @@ gsk_radial_gradient_node_get_color_stops (const GskRenderNode *node,
 
 /**
  * gsk_radial_gradient_node_get_center:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  *
  * Retrieves the center pointer for the gradient.
  *
@@ -708,7 +716,7 @@ gsk_radial_gradient_node_get_center (const GskRenderNode *node)
 
 /**
  * gsk_radial_gradient_node_get_hradius:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  *
  * Retrieves the horizonal radius for the gradient.
  *
@@ -724,7 +732,7 @@ gsk_radial_gradient_node_get_hradius (const GskRenderNode *node)
 
 /**
  * gsk_radial_gradient_node_get_vradius:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  *
  * Retrieves the vertical radius for the gradient.
  *
@@ -740,7 +748,7 @@ gsk_radial_gradient_node_get_vradius (const GskRenderNode *node)
 
 /**
  * gsk_radial_gradient_node_get_start:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  *
  * Retrieves the start value for the gradient.
  *
@@ -756,7 +764,7 @@ gsk_radial_gradient_node_get_start (const GskRenderNode *node)
 
 /**
  * gsk_radial_gradient_node_get_end:
- * @node: (type GskRadialGradientNode): a #GskRenderNode for a radial gradient
+ * @node: (type GskRadialGradientNode): a `GskRenderNode` for a radial gradient
  *
  * Retrieves the end value for the gradient.
  *
@@ -983,16 +991,19 @@ gsk_conic_gradient_node_diff (GskRenderNode  *node1,
  * @bounds: the bounds of the node
  * @center: the center of the gradient
  * @rotation: the rotation of the gradient in degrees
- * @color_stops: (array length=n_color_stops): a pointer to an array of #GskColorStop defining the gradient
- *   The offsets of all color steps must be increasing. The first stop's offset must be >= 0 and the last
+ * @color_stops: (array length=n_color_stops): a pointer to an array of
+ *   `GskColorStop` defining the gradient. The offsets of all color stops
+ *   must be increasing. The first stop's offset must be >= 0 and the last
  *   stop's offset must be <= 1.
  * @n_color_stops: the number of elements in @color_stops
  *
- * Creates a #GskRenderNode that draws a conic gradient. The conic gradient
+ * Creates a `GskRenderNode` that draws a conic gradient.
+ *
+ * The conic gradient
  * starts around @center in the direction of @rotation. A rotation of 0 means
  * that the gradient points up. Color stops are then added clockwise.
  *
- * Returns: (transfer full) (type GskConicGradientNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskConicGradientNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_conic_gradient_node_new (const graphene_rect_t  *bounds,
@@ -1037,7 +1048,7 @@ gsk_conic_gradient_node_new (const graphene_rect_t  *bounds,
 
 /**
  * gsk_conic_gradient_node_get_n_color_stops:
- * @node: (type GskConicGradientNode): a #GskRenderNode for a conic gradient
+ * @node: (type GskConicGradientNode): a `GskRenderNode` for a conic gradient
  *
  * Retrieves the number of color stops in the gradient.
  *
@@ -1053,7 +1064,7 @@ gsk_conic_gradient_node_get_n_color_stops (const GskRenderNode *node)
 
 /**
  * gsk_conic_gradient_node_get_color_stops:
- * @node: (type GskConicGradientNode): a #GskRenderNode for a conic gradient
+ * @node: (type GskConicGradientNode): a `GskRenderNode` for a conic gradient
  * @n_stops: (out) (optional): the number of color stops in the returned array
  *
  * Retrieves the color stops in the gradient.
@@ -1074,7 +1085,7 @@ gsk_conic_gradient_node_get_color_stops (const GskRenderNode *node,
 
 /**
  * gsk_conic_gradient_node_get_center:
- * @node: (type GskConicGradientNode): a #GskRenderNode for a conic gradient
+ * @node: (type GskConicGradientNode): a `GskRenderNode` for a conic gradient
  *
  * Retrieves the center pointer for the gradient.
  *
@@ -1090,7 +1101,7 @@ gsk_conic_gradient_node_get_center (const GskRenderNode *node)
 
 /**
  * gsk_conic_gradient_node_get_rotation:
- * @node: (type GskConicGradientNode): a #GskRenderNode for a conic gradient
+ * @node: (type GskConicGradientNode): a `GskRenderNode` for a conic gradient
  *
  * Retrieves the rotation for the gradient in degrees.
  *
@@ -1106,13 +1117,14 @@ gsk_conic_gradient_node_get_rotation (const GskRenderNode *node)
 
 /**
  * gsk_conic_gradient_node_get_angle:
- * @node: (type GskConicGradientNode): a #GskRenderNode for a conic gradient
+ * @node: (type GskConicGradientNode): a `GskRenderNode` for a conic gradient
  *
- * Retrieves the angle for the gradient in radians, normalized in [0, 2 * PI]
+ * Retrieves the angle for the gradient in radians, normalized in [0, 2 * PI].
  *
  * The angle is starting at the top and going clockwise, as expressed
  * in the css specification:
- * angle = 90 - gsk_conic_gradient_node_get_rotation()
+ *
+ *     angle = 90 - gsk_conic_gradient_node_get_rotation()
  *
  * Returns: the angle for the gradient
  *
@@ -1320,7 +1332,7 @@ gsk_border_node_diff (GskRenderNode  *node1,
 
 /**
  * gsk_border_node_get_outline:
- * @node: (type GskBorderNode): a #GskRenderNode for a border
+ * @node: (type GskBorderNode): a `GskRenderNode` for a border
  *
  * Retrieves the outline of the border.
  *
@@ -1336,7 +1348,7 @@ gsk_border_node_get_outline (const GskRenderNode *node)
 
 /**
  * gsk_border_node_get_widths:
- * @node: (type GskBorderNode): a #GskRenderNode for a border
+ * @node: (type GskBorderNode): a `GskRenderNode` for a border
  *
  * Retrieves the stroke widths of the border.
  *
@@ -1354,7 +1366,7 @@ gsk_border_node_get_widths (const GskRenderNode *node)
 
 /**
  * gsk_border_node_get_colors:
- * @node: (type GskBorderNode): a #GskRenderNode for a border
+ * @node: (type GskBorderNode): a `GskRenderNode` for a border
  *
  * Retrieves the colors of the border.
  *
@@ -1377,11 +1389,12 @@ gsk_border_node_get_colors (const GskRenderNode *node)
  * @border_color: (array fixed-size=4): the color used on the top, right,
  *     bottom and left side.
  *
- * Creates a #GskRenderNode that will stroke a border rectangle inside the
- * given @outline. The 4 sides of the border can have different widths and
- * colors.
+ * Creates a `GskRenderNode` that will stroke a border rectangle inside the
+ * given @outline.
  *
- * Returns: (transfer full) (type GskBorderNode): A new #GskRenderNode
+ * The 4 sides of the border can have different widths and colors.
+ *
+ * Returns: (transfer full) (type GskBorderNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_border_node_new (const GskRoundedRect *outline,
@@ -1507,11 +1520,11 @@ gsk_texture_node_diff (GskRenderNode  *node1,
 
 /**
  * gsk_texture_node_get_texture:
- * @node: (type GskTextureNode): a #GskRenderNode of type %GSK_TEXTURE_NODE
+ * @node: (type GskTextureNode): a `GskRenderNode` of type %GSK_TEXTURE_NODE
  *
- * Retrieves the #GdkTexture used when creating this #GskRenderNode.
+ * Retrieves the `GdkTexture` used when creating this `GskRenderNode`.
  *
- * Returns: (transfer none): the #GdkTexture
+ * Returns: (transfer none): the `GdkTexture`
  */
 GdkTexture *
 gsk_texture_node_get_texture (const GskRenderNode *node)
@@ -1523,13 +1536,13 @@ gsk_texture_node_get_texture (const GskRenderNode *node)
 
 /**
  * gsk_texture_node_new:
- * @texture: the #GdkTexture
+ * @texture: the `GdkTexture`
  * @bounds: the rectangle to render the texture into
  *
- * Creates a #GskRenderNode that will render the given
+ * Creates a `GskRenderNode` that will render the given
  * @texture into the area given by @bounds.
  *
- * Returns: (transfer full) (type GskTextureNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskTextureNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_texture_node_new (GdkTexture            *texture,
@@ -1972,10 +1985,10 @@ gsk_inset_shadow_node_diff (GskRenderNode  *node1,
  * @spread: how far the shadow spreads towards the inside
  * @blur_radius: how much blur to apply to the shadow
  *
- * Creates a #GskRenderNode that will render an inset shadow
+ * Creates a `GskRenderNode` that will render an inset shadow
  * into the box given by @outline.
  *
- * Returns: (transfer full) (type GskInsetShadowNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskInsetShadowNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_inset_shadow_node_new (const GskRoundedRect *outline,
@@ -2008,7 +2021,7 @@ gsk_inset_shadow_node_new (const GskRoundedRect *outline,
 
 /**
  * gsk_inset_shadow_node_get_outline:
- * @node: (type GskInsetShadowNode): a #GskRenderNode for an inset shadow
+ * @node: (type GskInsetShadowNode): a `GskRenderNode` for an inset shadow
  *
  * Retrieves the outline rectangle of the inset shadow.
  *
@@ -2024,7 +2037,7 @@ gsk_inset_shadow_node_get_outline (const GskRenderNode *node)
 
 /**
  * gsk_inset_shadow_node_get_color:
- * @node: (type GskInsetShadowNode): a #GskRenderNode for an inset shadow
+ * @node: (type GskInsetShadowNode): a `GskRenderNode` for an inset shadow
  *
  * Retrieves the color of the inset shadow.
  *
@@ -2040,7 +2053,7 @@ gsk_inset_shadow_node_get_color (const GskRenderNode *node)
 
 /**
  * gsk_inset_shadow_node_get_dx:
- * @node: (type GskInsetShadowNode): a #GskRenderNode for an inset shadow
+ * @node: (type GskInsetShadowNode): a `GskRenderNode` for an inset shadow
  *
  * Retrieves the horizontal offset of the inset shadow.
  *
@@ -2056,7 +2069,7 @@ gsk_inset_shadow_node_get_dx (const GskRenderNode *node)
 
 /**
  * gsk_inset_shadow_node_get_dy:
- * @node: (type GskInsetShadowNode): a #GskRenderNode for an inset shadow
+ * @node: (type GskInsetShadowNode): a `GskRenderNode` for an inset shadow
  *
  * Retrieves the vertical offset of the inset shadow.
  *
@@ -2072,7 +2085,7 @@ gsk_inset_shadow_node_get_dy (const GskRenderNode *node)
 
 /**
  * gsk_inset_shadow_node_get_spread:
- * @node: (type GskInsetShadowNode): a #GskRenderNode for an inset shadow
+ * @node: (type GskInsetShadowNode): a `GskRenderNode` for an inset shadow
  *
  * Retrieves how much the shadow spreads inwards.
  *
@@ -2088,7 +2101,7 @@ gsk_inset_shadow_node_get_spread (const GskRenderNode *node)
 
 /**
  * gsk_inset_shadow_node_get_blur_radius:
- * @node: (type GskInsetShadowNode): a #GskRenderNode for an inset shadow
+ * @node: (type GskInsetShadowNode): a `GskRenderNode` for an inset shadow
  *
  * Retrieves the blur radius to apply to the shadow.
  *
@@ -2267,10 +2280,10 @@ gsk_outset_shadow_node_diff (GskRenderNode  *node1,
  * @spread: how far the shadow spreads towards the inside
  * @blur_radius: how much blur to apply to the shadow
  *
- * Creates a #GskRenderNode that will render an outset shadow
+ * Creates a `GskRenderNode` that will render an outset shadow
  * around the box given by @outline.
  *
- * Returns: (transfer full) (type GskOutsetShadowNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskOutsetShadowNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_outset_shadow_node_new (const GskRoundedRect *outline,
@@ -2310,7 +2323,7 @@ gsk_outset_shadow_node_new (const GskRoundedRect *outline,
 
 /**
  * gsk_outset_shadow_node_get_outline:
- * @node: (type GskOutsetShadowNode): a #GskRenderNode for an outset shadow
+ * @node: (type GskOutsetShadowNode): a `GskRenderNode` for an outset shadow
  *
  * Retrieves the outline rectangle of the outset shadow.
  *
@@ -2326,7 +2339,7 @@ gsk_outset_shadow_node_get_outline (const GskRenderNode *node)
 
 /**
  * gsk_outset_shadow_node_get_color:
- * @node: (type GskOutsetShadowNode): a #GskRenderNode for an outset shadow
+ * @node: (type GskOutsetShadowNode): a `GskRenderNode` for an outset shadow
  *
  * Retrieves the color of the outset shadow.
  *
@@ -2342,7 +2355,7 @@ gsk_outset_shadow_node_get_color (const GskRenderNode *node)
 
 /**
  * gsk_outset_shadow_node_get_dx:
- * @node: (type GskOutsetShadowNode): a #GskRenderNode for an outset shadow
+ * @node: (type GskOutsetShadowNode): a `GskRenderNode` for an outset shadow
  *
  * Retrieves the horizontal offset of the outset shadow.
  *
@@ -2358,7 +2371,7 @@ gsk_outset_shadow_node_get_dx (const GskRenderNode *node)
 
 /**
  * gsk_outset_shadow_node_get_dy:
- * @node: (type GskOutsetShadowNode): a #GskRenderNode for an outset shadow
+ * @node: (type GskOutsetShadowNode): a `GskRenderNode` for an outset shadow
  *
  * Retrieves the vertical offset of the outset shadow.
  *
@@ -2374,7 +2387,7 @@ gsk_outset_shadow_node_get_dy (const GskRenderNode *node)
 
 /**
  * gsk_outset_shadow_node_get_spread:
- * @node: (type GskOutsetShadowNode): a #GskRenderNode for an outset shadow
+ * @node: (type GskOutsetShadowNode): a `GskRenderNode` for an outset shadow
  *
  * Retrieves how much the shadow spreads outwards.
  *
@@ -2390,7 +2403,7 @@ gsk_outset_shadow_node_get_spread (const GskRenderNode *node)
 
 /**
  * gsk_outset_shadow_node_get_blur_radius:
- * @node: (type GskOutsetShadowNode): a #GskRenderNode for an outset shadow
+ * @node: (type GskOutsetShadowNode): a `GskRenderNode` for an outset shadow
  *
  * Retrieves the blur radius of the shadow.
  *
@@ -2445,7 +2458,7 @@ gsk_cairo_node_draw (GskRenderNode *node,
 
 /**
  * gsk_cairo_node_get_surface:
- * @node: (type GskCairoNode): a #GskRenderNode for a Cairo surface
+ * @node: (type GskCairoNode): a `GskRenderNode` for a Cairo surface
  *
  * Retrieves the Cairo surface used by the render node.
  *
@@ -2465,11 +2478,12 @@ gsk_cairo_node_get_surface (GskRenderNode *node)
  * gsk_cairo_node_new:
  * @bounds: the rectangle to render to
  *
- * Creates a #GskRenderNode that will render a cairo surface
- * into the area given by @bounds. You can draw to the cairo
- * surface using gsk_cairo_node_get_draw_context()
+ * Creates a `GskRenderNode` that will render a cairo surface
+ * into the area given by @bounds.
  *
- * Returns: (transfer full) (type GskCairoNode): A new #GskRenderNode
+ * You can draw to the cairo surface using [method@Gsk.CairoNode.get_draw_context].
+ *
+ * Returns: (transfer full) (type GskCairoNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_cairo_node_new (const graphene_rect_t *bounds)
@@ -2489,7 +2503,7 @@ gsk_cairo_node_new (const graphene_rect_t *bounds)
 
 /**
  * gsk_cairo_node_get_draw_context:
- * @node: (type GskCairoNode): a #GskRenderNode for a Cairo surface
+ * @node: (type GskCairoNode): a `GskRenderNode` for a Cairo surface
  *
  * Creates a Cairo context for drawing using the surface associated
  * to the render node.
@@ -2651,10 +2665,11 @@ gsk_container_node_diff (GskRenderNode  *node1,
  * @children: (array length=n_children) (transfer none): The children of the node
  * @n_children: Number of children in the @children array
  *
- * Creates a new #GskRenderNode instance for holding the given @children.
+ * Creates a new `GskRenderNode` instance for holding the given @children.
+ *
  * The new node will acquire a reference to each of the children.
  *
- * Returns: (transfer full) (type GskContainerNode): the new #GskRenderNode
+ * Returns: (transfer full) (type GskContainerNode): the new `GskRenderNode`
  */
 GskRenderNode *
 gsk_container_node_new (GskRenderNode **children,
@@ -2695,11 +2710,11 @@ gsk_container_node_new (GskRenderNode **children,
 
 /**
  * gsk_container_node_get_n_children:
- * @node: (type GskContainerNode): a container #GskRenderNode
+ * @node: (type GskContainerNode): a container `GskRenderNode`
  *
  * Retrieves the number of direct children of @node.
  *
- * Returns: the number of children of the #GskRenderNode
+ * Returns: the number of children of the `GskRenderNode`
  */
 guint
 gsk_container_node_get_n_children (const GskRenderNode *node)
@@ -2711,7 +2726,7 @@ gsk_container_node_get_n_children (const GskRenderNode *node)
 
 /**
  * gsk_container_node_get_child:
- * @node: (type GskContainerNode): a container #GskRenderNode
+ * @node: (type GskContainerNode): a container `GskRenderNode`
  * @idx: the position of the child to get
  *
  * Gets one of the children of @container.
@@ -2735,7 +2750,7 @@ gsk_container_node_get_child (const GskRenderNode *node,
 /**
  * GskTransformNode:
  *
- * A render node applying a #GskTransform to its single child node.
+ * A render node applying a `GskTransform` to its single child node.
  */
 struct _GskTransformNode
 {
@@ -2874,10 +2889,10 @@ gsk_transform_node_diff (GskRenderNode  *node1,
  * @child: The node to transform
  * @transform: (transfer none): The transform to apply
  *
- * Creates a #GskRenderNode that will transform the given @child
+ * Creates a `GskRenderNode` that will transform the given @child
  * with the given @transform.
  *
- * Returns: (transfer full) (type GskTransformNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskTransformNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_transform_node_new (GskRenderNode *child,
@@ -2904,7 +2919,7 @@ gsk_transform_node_new (GskRenderNode *child,
 
 /**
  * gsk_transform_node_get_child:
- * @node: (type GskTransformNode): a #GskRenderNode for a transform
+ * @node: (type GskTransformNode): a `GskRenderNode` for a transform
  *
  * Gets the child node that is getting transformed by the given @node.
  *
@@ -2920,11 +2935,11 @@ gsk_transform_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_transform_node_get_transform:
- * @node: (type GskTransformNode): a #GskRenderNode for a transform
+ * @node: (type GskTransformNode): a `GskRenderNode` for a transform
  *
- * Retrieves the #GskTransform used by the @node.
+ * Retrieves the `GskTransform` used by the @node.
  *
- * Returns: (transfer none): a #GskTransform
+ * Returns: (transfer none): a `GskTransform`
  */
 GskTransform *
 gsk_transform_node_get_transform (const GskRenderNode *node)
@@ -3001,10 +3016,10 @@ gsk_opacity_node_diff (GskRenderNode  *node1,
  * @child: The node to draw
  * @opacity: The opacity to apply
  *
- * Creates a #GskRenderNode that will drawn the @child with reduced
+ * Creates a `GskRenderNode` that will drawn the @child with reduced
  * @opacity.
  *
- * Returns: (transfer full) (type GskOpacityNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskOpacityNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_opacity_node_new (GskRenderNode *child,
@@ -3028,7 +3043,7 @@ gsk_opacity_node_new (GskRenderNode *child,
 
 /**
  * gsk_opacity_node_get_child:
- * @node: (type GskOpacityNode): a #GskRenderNode for an opacity
+ * @node: (type GskOpacityNode): a `GskRenderNode` for an opacity
  *
  * Gets the child node that is getting opacityed by the given @node.
  *
@@ -3044,7 +3059,7 @@ gsk_opacity_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_opacity_node_get_opacity:
- * @node: (type GskOpacityNode): a #GskRenderNode for an opacity
+ * @node: (type GskOpacityNode): a `GskRenderNode` for an opacity
  *
  * Gets the transparency factor for an opacity node.
  *
@@ -3195,18 +3210,16 @@ nope:
  * @color_matrix: The matrix to apply
  * @color_offset: Values to add to the color
  *
- * Creates a #GskRenderNode that will drawn the @child with reduced
+ * Creates a `GskRenderNode` that will drawn the @child with
  * @color_matrix.
  *
  * In particular, the node will transform the operation
  *
- * |[<!-- language="plain" -->
- *   pixel = color_matrix * pixel + color_offset
- * ]|
+ *     pixel = color_matrix * pixel + color_offset
  *
  * for every pixel.
  *
- * Returns: (transfer full) (type GskColorMatrixNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskColorMatrixNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_color_matrix_node_new (GskRenderNode           *child,
@@ -3232,7 +3245,7 @@ gsk_color_matrix_node_new (GskRenderNode           *child,
 
 /**
  * gsk_color_matrix_node_get_child:
- * @node: (type GskColorMatrixNode): a color matrix #GskRenderNode
+ * @node: (type GskColorMatrixNode): a color matrix `GskRenderNode`
  *
  * Gets the child node that is getting its colors modified by the given @node.
  *
@@ -3248,7 +3261,7 @@ gsk_color_matrix_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_color_matrix_node_get_color_matrix:
- * @node: (type GskColorMatrixNode): a color matrix #GskRenderNode
+ * @node: (type GskColorMatrixNode): a color matrix `GskRenderNode`
  *
  * Retrieves the color matrix used by the @node.
  *
@@ -3264,7 +3277,7 @@ gsk_color_matrix_node_get_color_matrix (const GskRenderNode *node)
 
 /**
  * gsk_color_matrix_node_get_color_offset:
- * @node: (type GskColorMatrixNode): a color matrix #GskRenderNode
+ * @node: (type GskColorMatrixNode): a color matrix `GskRenderNode`
  *
  * Retrieves the color offset used by the @node.
  *
@@ -3348,10 +3361,10 @@ gsk_repeat_node_draw (GskRenderNode *node,
  * @child_bounds: (allow-none): The area of the child to repeat or %NULL to
  *     use the child's bounds
  *
- * Creates a #GskRenderNode that will repeat the drawing of @child across
+ * Creates a `GskRenderNode` that will repeat the drawing of @child across
  * the given @bounds.
  *
- * Returns: (transfer full) (type GskRepeatNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskRepeatNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_repeat_node_new (const graphene_rect_t *bounds,
@@ -3381,11 +3394,11 @@ gsk_repeat_node_new (const graphene_rect_t *bounds,
 
 /**
  * gsk_repeat_node_get_child:
- * @node: (type GskRepeatNode): a repeat #GskRenderNode
+ * @node: (type GskRepeatNode): a repeat `GskRenderNode`
  *
  * Retrieves the child of @node.
  *
- * Returns: (transfer none): a #GskRenderNode
+ * Returns: (transfer none): a `GskRenderNode`
  */
 GskRenderNode *
 gsk_repeat_node_get_child (const GskRenderNode *node)
@@ -3397,7 +3410,7 @@ gsk_repeat_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_repeat_node_get_child_bounds:
- * @node: (type GskRepeatNode): a repeat #GskRenderNode
+ * @node: (type GskRepeatNode): a repeat `GskRenderNode`
  *
  * Retrieves the bounding rectangle of the child of @node.
  *
@@ -3484,10 +3497,10 @@ gsk_clip_node_diff (GskRenderNode  *node1,
  * @child: The node to draw
  * @clip: The clip to apply
  *
- * Creates a #GskRenderNode that will clip the @child to the area
+ * Creates a `GskRenderNode` that will clip the @child to the area
  * given by @clip.
  *
- * Returns: (transfer full) (type GskClipNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskClipNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_clip_node_new (GskRenderNode         *child,
@@ -3615,10 +3628,10 @@ gsk_rounded_clip_node_diff (GskRenderNode  *node1,
  * @child: The node to draw
  * @clip: The clip to apply
  *
- * Creates a #GskRenderNode that will clip the @child to the area
+ * Creates a `GskRenderNode` that will clip the @child to the area
  * given by @clip.
  *
- * Returns: (transfer none) (type GskRoundedClipNode): A new #GskRenderNode
+ * Returns: (transfer none) (type GskRoundedClipNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_rounded_clip_node_new (GskRenderNode         *child,
@@ -3643,7 +3656,7 @@ gsk_rounded_clip_node_new (GskRenderNode         *child,
 
 /**
  * gsk_rounded_clip_node_get_child:
- * @node: (type GskRoundedClipNode): a rounded clip #GskRenderNode
+ * @node: (type GskRoundedClipNode): a rounded clip `GskRenderNode`
  *
  * Gets the child node that is getting clipped by the given @node.
  *
@@ -3659,9 +3672,9 @@ gsk_rounded_clip_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_rounded_clip_node_get_clip:
- * @node: (type GskRoundedClipNode): a rounded clip #GskRenderNode
+ * @node: (type GskRoundedClipNode): a rounded clip `GskRenderNode`
  *
- * Retrievs the rounded rectangle used to clip the contents of the @node.
+ * Retrieves the rounded rectangle used to clip the contents of the @node.
  *
  * Returns: (transfer none): a rounded rectangle
  */
@@ -3830,10 +3843,10 @@ gsk_shadow_node_get_bounds (GskShadowNode *self,
  * @shadows: (array length=n_shadows): The shadows to apply
  * @n_shadows: number of entries in the @shadows array
  *
- * Creates a #GskRenderNode that will draw a @child with the given
+ * Creates a `GskRenderNode` that will draw a @child with the given
  * @shadows below it.
  *
- * Returns: (transfer full) (type GskShadowNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskShadowNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_shadow_node_new (GskRenderNode   *child,
@@ -3862,9 +3875,9 @@ gsk_shadow_node_new (GskRenderNode   *child,
 
 /**
  * gsk_shadow_node_get_child:
- * @node: (type GskShadowNode): a shadow #GskRenderNode
+ * @node: (type GskShadowNode): a shadow `GskRenderNode`
  *
- * Retrieves the child #GskRenderNode of the shadow @node.
+ * Retrieves the child `GskRenderNode` of the shadow @node.
  *
  * Returns: (transfer none): the child render node
  */
@@ -3878,7 +3891,7 @@ gsk_shadow_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_shadow_node_get_shadow:
- * @node: (type GskShadowNode): a shadow #GskRenderNode
+ * @node: (type GskShadowNode): a shadow `GskRenderNode`
  * @i: the given index
  *
  * Retrieves the shadow data at the given index @i.
@@ -3896,7 +3909,7 @@ gsk_shadow_node_get_shadow (const GskRenderNode *node,
 
 /**
  * gsk_shadow_node_get_n_shadows:
- * @node: (type GskShadowNode): a shadow #GskRenderNode
+ * @node: (type GskShadowNode): a shadow `GskRenderNode`
  *
  * Retrieves the number of shadows in the @node.
  *
@@ -4025,10 +4038,10 @@ gsk_blend_node_diff (GskRenderNode  *node1,
  * @top: The node to be blended onto the @bottom node
  * @blend_mode: The blend mode to use
  *
- * Creates a #GskRenderNode that will use @blend_mode to blend the @top
+ * Creates a `GskRenderNode` that will use @blend_mode to blend the @top
  * node onto the @bottom node.
  *
- * Returns: (transfer full) (type GskBlendNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskBlendNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_blend_node_new (GskRenderNode *bottom,
@@ -4055,9 +4068,9 @@ gsk_blend_node_new (GskRenderNode *bottom,
 
 /**
  * gsk_blend_node_get_bottom_child:
- * @node: (type GskBlendNode): a blending #GskRenderNode
+ * @node: (type GskBlendNode): a blending `GskRenderNode`
  *
- * Retrieves the bottom #GskRenderNode child of the @node.
+ * Retrieves the bottom `GskRenderNode` child of the @node.
  *
  * Returns: (transfer none): the bottom child node
  */
@@ -4071,9 +4084,9 @@ gsk_blend_node_get_bottom_child (const GskRenderNode *node)
 
 /**
  * gsk_blend_node_get_top_child:
- * @node: (type GskBlendNode): a blending #GskRenderNode
+ * @node: (type GskBlendNode): a blending `GskRenderNode`
  *
- * Retrieves the top #GskRenderNode child of the @node.
+ * Retrieves the top `GskRenderNode` child of the @node.
  *
  * Returns: (transfer none): the top child node
  */
@@ -4087,7 +4100,7 @@ gsk_blend_node_get_top_child (const GskRenderNode *node)
 
 /**
  * gsk_blend_node_get_blend_mode:
- * @node: (type GskBlendNode): a blending #GskRenderNode
+ * @node: (type GskBlendNode): a blending `GskRenderNode`
  *
  * Retrieves the blend mode used by @node.
  *
@@ -4174,9 +4187,9 @@ gsk_cross_fade_node_diff (GskRenderNode  *node1,
  * @progress: How far the fade has progressed from start to end. The value will
  *     be clamped to the range [0 ... 1]
  *
- * Creates a #GskRenderNode that will do a cross-fade between @start and @end.
+ * Creates a `GskRenderNode` that will do a cross-fade between @start and @end.
  *
- * Returns: (transfer full) (type GskCrossFadeNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskCrossFadeNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_cross_fade_node_new (GskRenderNode *start,
@@ -4203,11 +4216,11 @@ gsk_cross_fade_node_new (GskRenderNode *start,
 
 /**
  * gsk_cross_fade_node_get_start_child:
- * @node: (type GskCrossFadeNode): a cross-fading #GskRenderNode
+ * @node: (type GskCrossFadeNode): a cross-fading `GskRenderNode`
  *
- * Retrieves the child #GskRenderNode at the beginning of the cross-fade.
+ * Retrieves the child `GskRenderNode` at the beginning of the cross-fade.
  *
- * Returns: (transfer none): a #GskRenderNode
+ * Returns: (transfer none): a `GskRenderNode`
  */
 GskRenderNode *
 gsk_cross_fade_node_get_start_child (const GskRenderNode *node)
@@ -4219,11 +4232,11 @@ gsk_cross_fade_node_get_start_child (const GskRenderNode *node)
 
 /**
  * gsk_cross_fade_node_get_end_child:
- * @node: (type GskCrossFadeNode): a cross-fading #GskRenderNode
+ * @node: (type GskCrossFadeNode): a cross-fading `GskRenderNode`
  *
- * Retrieves the child #GskRenderNode at the end of the cross-fade.
+ * Retrieves the child `GskRenderNode` at the end of the cross-fade.
  *
- * Returns: (transfer none): a #GskRenderNode
+ * Returns: (transfer none): a `GskRenderNode`
  */
 GskRenderNode *
 gsk_cross_fade_node_get_end_child (const GskRenderNode *node)
@@ -4235,7 +4248,7 @@ gsk_cross_fade_node_get_end_child (const GskRenderNode *node)
 
 /**
  * gsk_cross_fade_node_get_progress:
- * @node: (type GskCrossFadeNode): a cross-fading #GskRenderNode
+ * @node: (type GskCrossFadeNode): a cross-fading `GskRenderNode`
  *
  * Retrieves the progress value of the cross fade.
  *
@@ -4363,11 +4376,12 @@ font_has_color_glyphs (const PangoFont *font)
  * @color: the foreground color to render with
  * @offset: offset of the baseline
  *
- * Creates a render node that renders the given glyphs,
+ * Creates a render node that renders the given glyphs.
+ *
  * Note that @color may not be used if the font contains
  * color glyphs.
  *
- * Returns: (nullable) (transfer full) (type GskTextNode): a new #GskRenderNode
+ * Returns: (nullable) (transfer full) (type GskTextNode): a new `GskRenderNode`
  */
 GskRenderNode *
 gsk_text_node_new (PangoFont              *font,
@@ -4408,7 +4422,7 @@ gsk_text_node_new (PangoFont              *font,
 
 /**
  * gsk_text_node_get_color:
- * @node: (type GskTextNode): a text #GskRenderNode
+ * @node: (type GskTextNode): a text `GskRenderNode`
  *
  * Retrieves the color used by the text @node.
  *
@@ -4424,7 +4438,7 @@ gsk_text_node_get_color (const GskRenderNode *node)
 
 /**
  * gsk_text_node_get_font:
- * @node: (type GskTextNode): The #GskRenderNode
+ * @node: (type GskTextNode): The `GskRenderNode`
  *
  * Returns the font used by the text @node.
  *
@@ -4440,7 +4454,7 @@ gsk_text_node_get_font (const GskRenderNode *node)
 
 /**
  * gsk_text_node_has_color_glyphs:
- * @node: (type GskTextNode): a text #GskRenderNode
+ * @node: (type GskTextNode): a text `GskRenderNode`
  *
  * Checks whether the text @node has color glyphs.
  *
@@ -4456,7 +4470,7 @@ gsk_text_node_has_color_glyphs (const GskRenderNode *node)
 
 /**
  * gsk_text_node_get_num_glyphs:
- * @node: (type GskTextNode): a text #GskRenderNode
+ * @node: (type GskTextNode): a text `GskRenderNode`
  *
  * Retrieves the number of glyphs in the text node.
  *
@@ -4472,7 +4486,7 @@ gsk_text_node_get_num_glyphs (const GskRenderNode *node)
 
 /**
  * gsk_text_node_get_glyphs:
- * @node: (type GskTextNode): a text #GskRenderNode
+ * @node: (type GskTextNode): a text `GskRenderNode`
  * @n_glyphs: (out) (optional): the number of glyphs returned
  *
  * Retrieves the glyph information in the @node.
@@ -4493,7 +4507,7 @@ gsk_text_node_get_glyphs (const GskRenderNode *node,
 
 /**
  * gsk_text_node_get_offset:
- * @node: (type GskTextNode): a text #GskRenderNode
+ * @node: (type GskTextNode): a text `GskRenderNode`
  *
  * Retrieves the offset applied to the text.
  *
@@ -4760,7 +4774,7 @@ gsk_blur_node_diff (GskRenderNode  *node1,
  *
  * Creates a render node that blurs the child.
  *
- * Returns: (transfer full) (type GskBlurNode): a new #GskRenderNode
+ * Returns: (transfer full) (type GskBlurNode): a new `GskRenderNode`
  */
 GskRenderNode *
 gsk_blur_node_new (GskRenderNode *child,
@@ -4790,9 +4804,9 @@ gsk_blur_node_new (GskRenderNode *child,
 
 /**
  * gsk_blur_node_get_child:
- * @node: (type GskBlurNode): a blur #GskRenderNode
+ * @node: (type GskBlurNode): a blur `GskRenderNode`
  *
- * Retrieves the child #GskRenderNode of the blur @node.
+ * Retrieves the child `GskRenderNode` of the blur @node.
  *
  * Returns: (transfer none): the blurred child node
  */
@@ -4806,7 +4820,7 @@ gsk_blur_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_blur_node_get_radius:
- * @node: (type GskBlurNode): a blur #GskRenderNode
+ * @node: (type GskBlurNode): a blur `GskRenderNode`
  *
  * Retrieves the blur radius of the @node.
  *
@@ -4883,12 +4897,12 @@ gsk_debug_node_diff (GskRenderNode  *node1,
  * @child: The child to add debug info for
  * @message: (transfer full): The debug message
  *
- * Creates a #GskRenderNode that will add debug information about
+ * Creates a `GskRenderNode` that will add debug information about
  * the given @child.
  *
  * Adding this node has no visual effect.
  *
- * Returns: (transfer full) (type GskDebugNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskDebugNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_debug_node_new (GskRenderNode *child,
@@ -4912,11 +4926,11 @@ gsk_debug_node_new (GskRenderNode *child,
 
 /**
  * gsk_debug_node_get_child:
- * @node: (type GskDebugNode): a debug #GskRenderNode
+ * @node: (type GskDebugNode): a debug `GskRenderNode`
  *
  * Gets the child node that is getting drawn by the given @node.
  *
- * Returns: (transfer none): the child #GskRenderNode
+ * Returns: (transfer none): the child `GskRenderNode`
  **/
 GskRenderNode *
 gsk_debug_node_get_child (const GskRenderNode *node)
@@ -4928,7 +4942,7 @@ gsk_debug_node_get_child (const GskRenderNode *node)
 
 /**
  * gsk_debug_node_get_message:
- * @node: (type GskDebugNode): a debug #GskRenderNode
+ * @node: (type GskDebugNode): a debug `GskRenderNode`
  *
  * Gets the debug message that was set on this node
  *
@@ -5021,23 +5035,25 @@ gsk_gl_shader_node_diff (GskRenderNode  *node1,
  * @n_children: Length of @children (currenly the GL backend supports
  *     up to 4 children)
  *
- * Creates a #GskRenderNode that will render the given @shader into the
- * area given by @bounds. The @args is a block of data to use for uniform
- * input, as per types and offsets defined by the @shader. Normally this
- * is generated by gsk_gl_shader_format_args() or #GskGLShaderArgBuilder.
+ * Creates a `GskRenderNode` that will render the given @shader into the
+ * area given by @bounds.
  *
- * See #GskGLShader for details about how the shader should be written.
+ * The @args is a block of data to use for uniform input, as per types and
+ * offsets defined by the @shader. Normally this is generated by
+ * [method@Gsk.GLShader.format_args] or [struct@Gsk.ShaderArgsBuilder].
+ *
+ * See [class@Gsk.GLShader] for details about how the shader should be written.
  *
  * All the children will be rendered into textures (if they aren't already
- * #GskTextureNodes, which will be used directly). These textures will be
+ * `GskTextureNodes`, which will be used directly). These textures will be
  * sent as input to the shader.
  *
  * If the renderer doesn't support GL shaders, or if there is any problem
  * when compiling the shader, then the node will draw pink. You should use
- * gsk_gl_shader_compile() to ensure the @shader will work for the
+ * [method@Gsk.GLShader.compile] to ensure the @shader will work for the
  * renderer before using it.
  *
- * Returns: (transfer full) (type GskGLShaderNode): A new #GskRenderNode
+ * Returns: (transfer full) (type GskGLShaderNode): A new `GskRenderNode`
  */
 GskRenderNode *
 gsk_gl_shader_node_new (GskGLShader           *shader,
@@ -5077,7 +5093,7 @@ gsk_gl_shader_node_new (GskGLShader           *shader,
 
 /**
  * gsk_gl_shader_node_get_n_children:
- * @node: (type GskGLShaderNode): a #GskRenderNode for a gl shader
+ * @node: (type GskGLShaderNode): a `GskRenderNode` for a gl shader
  *
  * Returns the number of children
  *
@@ -5093,7 +5109,7 @@ gsk_gl_shader_node_get_n_children (const GskRenderNode *node)
 
 /**
  * gsk_gl_shader_node_get_child:
- * @node: (type GskGLShaderNode): a #GskRenderNode for a gl shader
+ * @node: (type GskGLShaderNode): a `GskRenderNode` for a gl shader
  * @idx: the position of the child to get
  *
  * Gets one of the children.
@@ -5111,7 +5127,7 @@ gsk_gl_shader_node_get_child (const GskRenderNode *node,
 
 /**
  * gsk_gl_shader_node_get_shader:
- * @node: (type GskGLShaderNode): a #GskRenderNode for a gl shader
+ * @node: (type GskGLShaderNode): a `GskRenderNode` for a gl shader
  *
  * Gets shader code for the node.
  *
@@ -5127,7 +5143,7 @@ gsk_gl_shader_node_get_shader (const GskRenderNode *node)
 
 /**
  * gsk_gl_shader_node_get_args:
- * @node: (type GskGLShaderNode): a #GskRenderNode for a gl shader
+ * @node: (type GskGLShaderNode): a `GskRenderNode` for a gl shader
  *
  * Gets args for the node.
  *
@@ -5587,7 +5603,7 @@ gsk_render_node_init_types_once (void)
 /*< private >
  * gsk_render_node_init_types:
  *
- * Initialize all the #GskRenderNode types provided by GSK.
+ * Initialize all the `GskRenderNode` types provided by GSK.
  */
 void
 gsk_render_node_init_types (void)
diff --git a/gsk/gsktransform.c b/gsk/gsktransform.c
index ae8a25d904..46703bb898 100644
--- a/gsk/gsktransform.c
+++ b/gsk/gsktransform.c
@@ -2125,7 +2125,9 @@ fail:
  * @out_transform: (out): The location to put the transform in
  *
  * Parses the given @string into a transform and puts it in
- * @out_transform. Strings printed via gsk_transform_to_string()
+ * @out_transform.
+ *
+ * Strings printed via [method@Gsk.Transform.to_string]
  * can be read in again successfully using this function.
  *
  * If @string does not describe a valid transform, %FALSE is
diff --git a/gsk/vulkan/gskvulkanrenderer.h b/gsk/vulkan/gskvulkanrenderer.h
index ff3f361f49..7f9c642d79 100644
--- a/gsk/vulkan/gskvulkanrenderer.h
+++ b/gsk/vulkan/gskvulkanrenderer.h
@@ -35,6 +35,11 @@ G_BEGIN_DECLS
 #define GSK_IS_VULKAN_RENDERER_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GSK_TYPE_VULKAN_RENDERER))
 #define GSK_VULKAN_RENDERER_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GSK_TYPE_VULKAN_RENDERER, GskVulkanRendererClass))
 
+/**
+ * GskVulkanRenderer:
+ *
+ * A GSK renderer that is using Vulkan.
+ */
 typedef struct _GskVulkanRenderer                GskVulkanRenderer;
 typedef struct _GskVulkanRendererClass           GskVulkanRendererClass;