diff --git a/gsk/gskenums.h b/gsk/gskenums.h
index ac2b1899a3..967dd426e0 100644
--- a/gsk/gskenums.h
+++ b/gsk/gskenums.h
@@ -187,16 +187,19 @@ typedef enum {
  *   filled.
  *
  * #GskFillRule is used to select how paths are filled, for example in
- * gsk_fill_node_new(). Whether or not a point is included in the fill is
- * determined by taking a ray from that point to infinity and looking
- * at intersections with the path. The ray can be in any direction,
- * as long as it doesn't pass through the end point of a segment
- * or have a tricky intersection such as intersecting tangent to the path.
+ * gsk_fill_node_new().
+ *
+ * Whether or not a point is included in the fill is determined by taking
+ * a ray from that point to infinity and looking at intersections with the
+ * path. The ray can be in any direction, as long as it doesn't pass through
+ * the end point of a segment or have a tricky intersection such as
+ * intersecting tangent to the path.
+ *
  * (Note that filling is not actually implemented in this way. This
  * is just a description of the rule that is applied.)
  *
  * New entries may be added in future versions.
- **/
+ */
 typedef enum {
   GSK_FILL_RULE_WINDING,
   GSK_FILL_RULE_EVEN_ODD
@@ -205,11 +208,11 @@ typedef enum {
 /**
  * GskLineCap:
  * @GSK_LINE_CAP_BUTT: Start and stop the line exactly at the start
- *     and end point
+ *   and end point
  * @GSK_LINE_CAP_ROUND: Use a round ending, the center of the circle
- *     is the start or end point.
+ *   is the start or end point.
  * @GSK_LINE_CAP_SQUARE: use squared ending, the center of the square
- *     is the start or end point.
+ *   is the start or end point.
  *
  * Specifies how to render the start and end points of contours or
  * dashes when stroking.
@@ -227,14 +230,14 @@ typedef enum {
  * @GSK_LINE_JOIN_MITER: Use a sharp, angled corner
  * @GSK_LINE_JOIN_MITER_CLIP: Use a sharp, angled corner, at a distance
  * @GSK_LINE_JOIN_ROUND: Use a round join, the center of the circle is
- *     the joint point
+ *   the joint point
  * @GSK_LINE_JOIN_BEVEL: Use a cut-off join, the join is cut off at half
- *     the line width from the joint point
+ *   the line width from the joint point
  *
  * Specifies how to render the junction of two lines when stroking.
  *
- * See gsk_stroke_set_miter_limit() for details on the difference between
- * @GSK_LINE_JOIN_MITER and @GSK_LINE_JOIN_MITER_CLIP.
+ * See [method@Gsk.Stroke.set_miter_limit] for details on the difference
+ * between @GSK_LINE_JOIN_MITER and @GSK_LINE_JOIN_MITER_CLIP.
  *
  * The default line join style is %GSK_LINE_JOIN_MITER.
  **/
@@ -248,18 +251,23 @@ typedef enum {
 /**
  * GskPathOperation:
  * @GSK_PATH_MOVE: A move-to operation, with 1 point describing the
- *     target point.
+ *   target point.
  * @GSK_PATH_LINE: A line-to operation, with 2 points describing the
- *     start and end point of a straight line.
+ *   start and end point of a straight line.
  * @GSK_PATH_CLOSE: A close operation ending the current contour with
- *     a line back to the starting point. Two points describe the start
- *     and end of the line.
+ *   a line back to the starting point. Two points describe the start
+ *   and end of the line.
+ * @GSK_PATH_CUBIC: A curve-to operation describing a cubic Bézier curve
+ *   with 4 points describing the start point, the two control points
+ *   and the end point of the curve.
+ *   a line back to the starting point. Two points describe the start
+ *   and end of the line.
  * @GSK_PATH_CURVE: A curve-to operation describing a cubic Bézier curve
- *     with 4 points describing the start point, the two control points
- *     and the end point of the curve.
- * @GSK_PATH_CONIC: A weighted quadratic bezier curve with 3 points
- *     describing the start point, control point and end point of the
- *     curve. A weight for the curve will be passed, too.
+ *   with 4 points describing the start point, the two control points
+ *   and the end point of the curve.
+ * @GSK_PATH_CONIC: A weighted quadratic Bézier curve with 3 points
+ *   describing the start point, control point and end point of the
+ *   curve. A weight for the curve will be passed, too.
  *
  * Path operations can be used to approximate a #GskPath.
  *
diff --git a/gsk/gskpath.c b/gsk/gskpath.c
index 00613eebcd..924570c516 100644
--- a/gsk/gskpath.c
+++ b/gsk/gskpath.c
@@ -25,17 +25,16 @@
 #include "gskpathbuilder.h"
 
 /**
- * SECTION:gskpath
- * @Title: Path
- * @Short_description: Lines and Curves
- * @See_also: #GskRenderNode, #GskPathBuilder
+ * GskPath:
  *
- * This section describes the #GskPath structure that is used to
- * describe lines and curves that are more complex than simple rectangles.
+ * A `GskPath` describes lines and curves that are more complex
+ * than simple rectangles.
  *
- * #GskPath is an immutable struct. After creation, you cannot change
- * the types it represents. Instead, new #GskPath have to be created.
- * The #GskPathBuilder structure is meant to help in this endeavor.
+ * `GskPath` is an immutable, opaque, reference-counted struct.
+ * After creation, you cannot change the types it represents.
+ * Instead, new `GskPath` objects have to be created.
+ *
+ * The `GskPathBuilder` structure is meant to help in this endeavor.
  */
 
 struct _GskPath
@@ -50,13 +49,6 @@ struct _GskPath
   /* followed by the contours data */
 };
 
-/**
- * GskPath:
- *
- * A #GskPath struct is a reference counted struct
- * and should be treated as opaque.
- */
-
 G_DEFINE_BOXED_TYPE (GskPath, gsk_path,
                      gsk_path_ref,
                      gsk_path_unref)
@@ -107,12 +99,12 @@ gsk_path_new_from_contours (const GSList *contours)
 
 /**
  * gsk_path_ref:
- * @self: a #GskPath
+ * @self: a `GskPath`
  *
- * Increases the reference count of a #GskPath by one.
+ * Increases the reference count of a `GskPath` by one.
  *
- * Returns: the passed in #GskPath.
- **/
+ * Returns: the passed in `GskPath`
+ */
 GskPath *
 gsk_path_ref (GskPath *self)
 {
@@ -125,11 +117,12 @@ gsk_path_ref (GskPath *self)
 
 /**
  * gsk_path_unref:
- * @self: a #GskPath
+ * @self: a `GskPath`
+ *
+ * Decreases the reference count of a `GskPath` by one.
  *
- * Decreases the reference count of a #GskPath by one.
  * If the resulting reference count is zero, frees the path.
- **/
+ */
 void
 gsk_path_unref (GskPath *self)
 {
@@ -152,7 +145,7 @@ gsk_path_get_contour (GskPath *path,
 
 /**
  * gsk_path_print:
- * @self: a #GskPath
+ * @self: a `GskPath`
  * @string:  The string to print into
  *
  * Converts @self into a human-readable string representation suitable
@@ -163,7 +156,7 @@ gsk_path_get_contour (GskPath *path,
  * with the exception that conic curves will generate a string of the
  * form "O x1 y1, x2 y2, w" where x1, y1 is the control point, x2, y2
  * is the end point, and w is the weight.
- **/
+ */
 void
 gsk_path_print (GskPath *self,
                 GString *string)
@@ -183,17 +176,18 @@ gsk_path_print (GskPath *self,
 
 /**
  * gsk_path_to_string:
- * @self: a #GskPath
+ * @self: a `GskPath`
  *
- * Converts the path into a string that is suitable for
- * printing. You can use this function in a debugger to get a quick overview
+ * Converts the path into a string that is suitable for printing.
+ *
+ * You can use this function in a debugger to get a quick overview
  * of the path.
  *
- * This is a wrapper around gsk_path_print(), see that function
- * for details.
+ * This is a wrapper around [method@Gsk.Path.print], see that
+ * function for details.
  *
  * Returns: A new string for @self
- **/
+ */
 char *
 gsk_path_to_string (GskPath *self)
 {
@@ -244,18 +238,18 @@ gsk_path_to_cairo_add_op (GskPathOperation        op,
 
 /**
  * gsk_path_to_cairo:
- * @self: a #GskPath
+ * @self: a `GskPath`
  * @cr: a cairo context
  *
  * Appends the given @path to the given cairo context for drawing
  * with Cairo.
  *
- * This may cause some suboptimal conversions to be performed as Cairo
- * may not support all features of #GskPath.
+ * This may cause some suboptimal conversions to be performed as
+ * Cairo does not support all features of `GskPath`.
  *
  * This function does not clear the existing Cairo path. Call
  * cairo_new_path() if you want this.
- **/
+ */
 void
 gsk_path_to_cairo (GskPath *self,
                    cairo_t *cr)
@@ -270,14 +264,14 @@ gsk_path_to_cairo (GskPath *self,
                                    cr);
 }
 
-/*
+/*< private >*
  * gsk_path_get_n_contours:
- * @path: a #GskPath
+ * @path: a `GskPath`
  *
  * Gets the number of contours @path is composed out of.
  *
  * Returns: the number of contours in @path
- **/
+ */
 gsize
 gsk_path_get_n_contours (GskPath *path)
 {
@@ -286,12 +280,12 @@ gsk_path_get_n_contours (GskPath *path)
 
 /**
  * gsk_path_is_empty:
- * @self: a #GskPath
+ * @self: a `GskPath`
  *
  * Checks if the path is empty, i.e. contains no lines or curves.
  *
- * Returns: %TRUE if the path is empty
- **/
+ * Returns: `TRUE` if the path is empty
+ */
 gboolean
 gsk_path_is_empty (GskPath *self)
 {
@@ -302,7 +296,7 @@ gsk_path_is_empty (GskPath *self)
 
 /**
  * gsk_path_get_bounds:
- * @self: a #GskPath
+ * @self: a `GskPath`
  * @bounds: (out caller-allocates): the bounds of the given path
  *
  * Computes the bounds of the given path.
@@ -320,9 +314,9 @@ gsk_path_is_empty (GskPath *self)
  * is a single point at the origin, where the @bounds will also be set to
  * the zero rectangle but 0 will be returned.
  *
- * Returns: %TRUE if the path has bounds, %FALSE if the path is known
- *     to be empty and have no bounds.
- **/
+ * Returns: `TRUE` if the path has bounds, `FALSE` if the path is known
+ *   to be empty and have no bounds.
+ */
 gboolean
 gsk_path_get_bounds (GskPath         *self,
                      graphene_rect_t *bounds)
@@ -357,17 +351,19 @@ gsk_path_get_bounds (GskPath         *self,
 
 /**
  * gsk_path_foreach:
- * @self: a #GskPath
- * @flags: flags to pass to the foreach function. See #GskPathForeachFlags for
- *     details about flags.
+ * @self: a `GskPath`
+ * @flags: flags to pass to the foreach function. See `GskPathForeachFlags`
+ *   for details about flags
  * @func: (scope call) (closure user_data): the function to call for operations
  * @user_data: (nullable): user data passed to @func
  *
- * Calls @func for every operation of the path. Note that this only approximates
- * @self, because paths can contain optimizations for various specialized contours.
+ * Calls @func for every operation of the path.
  *
- * Returns: %FALSE if @func returned %FALSE, %TRUE otherwise.
- **/
+ * Note that this only approximates @self, because paths can contain
+ * optimizations for various specialized contours.
+ *
+ * Returns: `FALSE` if @func returned FALSE`, `TRUE` otherwise.
+ */
 gboolean
 gsk_path_foreach (GskPath             *self,
                   GskPathForeachFlags  flags,
@@ -690,13 +686,16 @@ parse_circle (const char **p,
  * gsk_path_parse:
  * @string: a string
  *
- * This is a convenience function that constructs a #GskPath
- * from a serialized form. The string is expected to be in
- * [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData),
- * as e.g. produced by gsk_path_to_string().
+ * This is a convenience function that constructs a `GskPath`
+ * from a serialized form.
  *
- * Returns: (nullable): a new #GskPath, or %NULL if @string could not be parsed
- **/
+ * The string is expected to be in
+ * [SVG path syntax](https://www.w3.org/TR/SVG11/paths.html#PathData),
+ * as e.g. produced by [method@Gsk.Path.to_string].
+ *
+ * Returns: (nullable): a new `GskPath`, or `NULL`
+ *   if @string could not be parsed
+ */
 GskPath *
 gsk_path_parse (const char *string)
 {
@@ -1118,7 +1117,7 @@ error:
 
 /**
  * gsk_path_get_stroke_bounds:
- * @self: a #GtkPath
+ * @self: a `GtkPath`
  * @stroke: stroke parameters
  * @bounds: (out caller-allocates): the bounds to fill in
  *
@@ -1130,8 +1129,8 @@ error:
  * to contain the area affected by the stroke, including protrusions
  * like miters.
  *
- * Returns: %TRUE if the path has bounds, %FALSE if the path is known
- *     to be empty and have no bounds.
+ * Returns: `TRUE` if the path has bounds, `FALSE`
+ *   if the path is known to be empty and have no bounds.
  */
 gboolean
 gsk_path_get_stroke_bounds (GskPath         *self,
diff --git a/gsk/gskpathbuilder.c b/gsk/gskpathbuilder.c
index dfaacb6897..bd783a10f7 100644
--- a/gsk/gskpathbuilder.c
+++ b/gsk/gskpathbuilder.c
@@ -24,10 +24,11 @@
 #include "gskpathprivate.h"
 
 /**
- * SECTION:gskpathbuilder
- * @Title: Building paths
- * @Short_description: Building paths of lines and curves
- * @See_also: #GskPath, #GskPathMeasure
+ * GskPathBuilder:
+ *
+ * A #GskPathBuilder struct is an opaque struct. It is meant to
+ * not be kept around and only be used to create new #GskPath
+ * objects.
  *
  * This section describes how to construct #GskPath structures.
  *
@@ -46,30 +47,22 @@
  *   return gsk_path_builder_free_to_path (builder);
  * ]|
  *
- * Adding contours to the path can be done in two ways.  
+ * Adding contours to the path can be done in two ways.
  * The easiest option is to use the `gsk_path_builder_add_*` group
  * of functions that add predefined contours to the current path,
- * either common shapes like gsk_path_builder_add_circle()
- * or by adding from other paths like gsk_path_builder_add_path().
+ * either common shapes like [method@Gsk.PathBuilder.add_circle]
+ * or by adding from other paths like [method@Gsk.PathBuilder.add_path].
  *
  * The other option is to define each line and curve manually with
  * the `gsk_path_builder_*_to` group of functions. You start with
- * a call to gsk_path_builder_move_to() to set the starting point
+ * a call to [method@Gsk.PathBuilder.move_to] to set the starting point
  * and then use multiple calls to any of the drawing functions to
  * move the pen along the plane. Once you are done, you can call
- * gsk_path_builder_close() to close the path by connecting it
+ * [method@Gsk.PathBuilder.close] to close the path by connecting it
  * back with a line to the starting point.
  * This is similar for how paths are drawn in Cairo.
  */
 
-/**
- * GskPathBuilder:
- *
- * A #GskPathBuilder struct is an opaque struct. It is meant to
- * not be kept around and only be used to create new #GskPath
- * objects.
- */
-
 struct _GskPathBuilder
 {
   int ref_count;
@@ -91,11 +84,12 @@ G_DEFINE_BOXED_TYPE (GskPathBuilder,
 /**
  * gsk_path_builder_new:
  *
- * Create a new #GskPathBuilder object. The resulting builder
- * would create an empty #GskPath. Use addition functions to add
- * types to it.
+ * Create a new `GskPathBuilder` object.
  *
- * Returns: a new #GskPathBuilder
+ * The resulting builder would create an empty `GskPath`.
+ * Use addition functions to add types to it.
+ *
+ * Returns: a new `GskPathBuilder`
  **/
 GskPathBuilder *
 gsk_path_builder_new (void)
@@ -116,15 +110,15 @@ gsk_path_builder_new (void)
 
 /**
  * gsk_path_builder_ref:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
  * Acquires a reference on the given builder.
  *
- * This function is intended primarily for bindings. #GskPathBuilder objects
- * should not be kept around.
+ * This function is intended primarily for bindings.
+ * `GskPathBuilder` objects should not be kept around.
  *
- * Returns: (transfer none): the given #GskPathBuilder with
- *   its reference count increased
+ * Returns: (transfer none): the given `GskPathBuilder`
+ *   with its reference count increased
  */
 GskPathBuilder *
 gsk_path_builder_ref (GskPathBuilder *self)
@@ -208,7 +202,7 @@ gsk_path_builder_clear (GskPathBuilder *self)
 
 /**
  * gsk_path_builder_unref:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
  * Releases a reference on the given builder.
  */
@@ -231,12 +225,12 @@ gsk_path_builder_unref (GskPathBuilder *self)
 
 /**
  * gsk_path_builder_free_to_path: (skip)
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
- * Creates a new #GskPath from the current state of the
+ * Creates a new `GskPath` from the current state of the
  * given builder, and frees the @builder instance.
  *
- * Returns: (transfer full): the newly created #GskPath
+ * Returns: (transfer full): the newly created `GskPath`
  *   with all the contours added to the builder
  */
 GskPath *
@@ -255,17 +249,18 @@ gsk_path_builder_free_to_path (GskPathBuilder *self)
 
 /**
  * gsk_path_builder_to_path:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
  * Creates a new #GskPath from the given builder.
  *
- * The given #GskPathBuilder is reset once this function returns;
- * you cannot call this function multiple times on the same builder instance.
+ * The given `GskPathBuilder` 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_path_builder_free_to_path().
+ * This function is intended primarily for bindings. C code should
+ * use [method@Gsk.PathBuilder.free_to_path].
  *
- * Returns: (transfer full): the newly created #GskPath
+ * Returns: (transfer full): the newly created `GskPath`
  *   with all the contours added to the builder
  */
 GskPath *
@@ -297,7 +292,7 @@ gsk_path_builder_add_contour (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_get_current_point:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
  * Gets the current point. The current point is used for relative
  * drawing commands and updated after every operation.
@@ -316,7 +311,7 @@ gsk_path_builder_get_current_point (GskPathBuilder *self)
 
 /**
  * gsk_path_builder_add_path:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @path: (transfer none): the path to append
  *
  * Appends all of @path to the builder.
@@ -340,11 +335,12 @@ gsk_path_builder_add_path (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_add_cairo_path:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
  * Adds a Cairo path to the builder.
  *
- * You can use cairo_copy_path() to access the path from a Cairo context.
+ * You can use cairo_copy_path() to access the path
+ * from a Cairo context.
  **/
 void
 gsk_path_builder_add_cairo_path (GskPathBuilder     *self,
@@ -389,7 +385,7 @@ gsk_path_builder_add_cairo_path (GskPathBuilder     *self,
 
 /**
  * gsk_path_builder_add_rect:
- * @self: A #GskPathBuilder
+ * @self: A `GskPathBuilder`
  * @rect: The rectangle to create a path for
  *
  * Adds @rect as a new contour to the path built by the builder.
@@ -416,7 +412,7 @@ gsk_path_builder_add_rect (GskPathBuilder        *self,
 
 /**
  * gsk_path_builder_add_rounded_rect:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @rect: the rounded rect
  *
  * Adds @rect as a new contour to the path built in @self.
@@ -483,7 +479,7 @@ gsk_path_builder_add_rounded_rect (GskPathBuilder       *self,
 
 /**
  * gsk_path_builder_add_circle:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @center: the center of the circle
  * @radius: the radius of the circle
  *
@@ -506,7 +502,7 @@ gsk_path_builder_add_circle (GskPathBuilder         *self,
 
 /**
  * gsk_path_builder_add_ellipse:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @center: the center point of the ellipse
  * @radius: the radius of the ellipse in x/y direction
  *
@@ -552,16 +548,16 @@ gsk_path_builder_add_ellipse (GskPathBuilder         *self,
 
 /**
  * gsk_path_builder_move_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x: x coordinate
  * @y: y coordinate
  *
  * Starts a new contour by placing the pen at @x, @y.
  *
- * If gsk_path_builder_move_to() is called twice in succession, the first
- * call will result in a contour made up of a single point. The second call
- * will start a new contour.
- **/
+ * If gsk_path_builder_move_to() is called twice in succession,
+ * the first call will result in a contour made up of a single point.
+ * The second call will start a new contour.
+ */
 void
 gsk_path_builder_move_to (GskPathBuilder *self,
                           float           x,
@@ -578,15 +574,15 @@ gsk_path_builder_move_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_rel_move_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x: x offset
  * @y: y offset
  *
- * Starts a new contour by placing the pen at @x, @y relative to the current
- * point.
+ * Starts a new contour by placing the pen at @x, @y relative
+ * to the current point.
  *
- * This is the relative version of gsk_path_builder_move_to().
- **/
+ * This is the relative version of [method@Gsk.PathBuilder.move_to].
+ */
 void
 gsk_path_builder_rel_move_to (GskPathBuilder *self,
                               float           x,
@@ -601,13 +597,13 @@ gsk_path_builder_rel_move_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_line_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x: x coordinate
  * @y: y coordinate
  *
- * Draws a line from the current point to @x, @y and makes it the new current
- * point.
- **/
+ * Draws a line from the current point to @x, @y and
+ * makes it the new current point.
+ */
 void
 gsk_path_builder_line_to (GskPathBuilder *self,
                           float           x,
@@ -629,15 +625,15 @@ gsk_path_builder_line_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_rel_line_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x: x offset
  * @y: y offset
  *
- * Draws a line from the current point to a point offset to it by @x, @y
- * and makes it the new current point.
+ * Draws a line from the current point to a point offset to
+ * it by @x, @y and makes it the new current point.
  *
- * This is the relative version of gsk_path_builder_line_to().
- **/
+ * This is the relative version of [method@Gsk.PathBuilder.line_to].
+ */
 void
 gsk_path_builder_rel_line_to (GskPathBuilder *self,
                               float           x,
@@ -652,7 +648,7 @@ gsk_path_builder_rel_line_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_curve_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x1: x coordinate of first control point
  * @y1: y coordinate of first control point
  * @x2: x coordinate of second control point
@@ -689,7 +685,7 @@ gsk_path_builder_curve_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_rel_curve_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x1: x offset of first control point
  * @y1: y offset of first control point
  * @x2: x offset of second control point
@@ -701,8 +697,8 @@ gsk_path_builder_curve_to (GskPathBuilder *self,
  * from the current point to @x3, @y3 with @x1, @y1 and @x2, @y2 as the control
  * points. All coordinates are given relative to the current point.
  *
- * This is the relative version of gsk_path_builder_curve_to().
- **/
+ * This is the relative version of [method@Gsk.PathBuilder.curve_to].
+ */
 void
 gsk_path_builder_rel_curve_to (GskPathBuilder *self,
                                float           x1,
@@ -725,7 +721,7 @@ gsk_path_builder_rel_curve_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_conic_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x1: x coordinate of control point
  * @y1: y coordinate of control point
  * @x2: x coordinate of the end of the curve
@@ -739,7 +735,7 @@ gsk_path_builder_rel_curve_to (GskPathBuilder *self,
  * Conic curves can be used to draw ellipses and circles.
  *
  * After this, @x2, @y2 will be the new current point.
- **/
+ */
 void
 gsk_path_builder_conic_to (GskPathBuilder *self,
                            float           x1,
@@ -763,7 +759,7 @@ gsk_path_builder_conic_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_rel_conic_to:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @x1: x offset of control point
  * @y1: y offset of control point
  * @x2: x offset of the end of the curve
@@ -774,8 +770,8 @@ gsk_path_builder_conic_to (GskPathBuilder *self,
  * from the current point to @x2, @y2 with the given
  * @weight and @x1, @y1 as the single control point.
  *
- * This is the relative version of gsk_path_builder_conic_to().
- **/
+ * This is the relative version of [Gsk.PathBuilder.conic_to].
+ */
 void
 gsk_path_builder_rel_conic_to (GskPathBuilder *self,
                                float           x1,
@@ -797,16 +793,16 @@ gsk_path_builder_rel_conic_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_close:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  *
  * Ends the current contour with a line back to the start point.
  *
- * Note that this is different from calling gsk_path_builder_line_to()
+ * Note that this is different from calling [method@Gsk.PathBuilder.line_to]
  * with the start point in that the contour will be closed. A closed
  * contour behaves different from an open one when stroking its start
  * and end point are considered connected, so they will be joined
  * via the line join, and not ended with line caps.
- **/
+ */
 void
 gsk_path_builder_close (GskPathBuilder *self)
 {
@@ -1002,7 +998,7 @@ gsk_path_builder_svg_arc_to (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_add_layout:
- * @self: a #GskPathBuilder
+ * @self: a `GskPathBuilder`
  * @layout: the pango layout to add
  *
  * Adds the outlines for the glyphs in @layout to
diff --git a/gsk/gskpathmeasure.c b/gsk/gskpathmeasure.c
index f2cd2e93a4..8499f93d48 100644
--- a/gsk/gskpathmeasure.c
+++ b/gsk/gskpathmeasure.c
@@ -25,13 +25,14 @@
 #include "gskpathprivate.h"
 
 /**
- * SECTION:gskpathmeasure
- * @Title: PathMeasure
- * @Short_description: Measuring operations on paths
- * @See_also: #GskPath
+ * GskPathMeasure:
  *
- * #GskPathMeasure is an object that allows measuring operations on #GskPaths.
- * These operations are useful when implementing animations.
+ * A `GskPathMeasure` struct is a reference-counted struct
+ * and should be treated as opaque.
+ *
+ * `GskPathMeasure` is an object that allows measuring operations
+ * on `GskPath`. These operations are useful when implementing
+ * animations.
  */
 
 typedef struct _GskContourMeasure GskContourMeasure;
@@ -59,10 +60,6 @@ struct _GskPathMeasure
 };
 
 /**
- * GskPathMeasure:
- *
- * A #GskPathMeasure struct is a reference counted struct
- * and should be treated as opaque.
  */
 
 G_DEFINE_BOXED_TYPE (GskPathMeasure, gsk_path_measure,
@@ -75,8 +72,8 @@ G_DEFINE_BOXED_TYPE (GskPathMeasure, gsk_path_measure,
  *
  * Creates a measure object for the given @path.
  *
- * Returns: a new #GskPathMeasure representing @path
- **/
+ * Returns: a new `GskPathMeasure` representing @path
+ */
 GskPathMeasure *
 gsk_path_measure_new (GskPath *path)
 {
@@ -90,8 +87,8 @@ gsk_path_measure_new (GskPath *path)
  *
  * Creates a measure object for the given @path and @tolerance.
  *
- * Returns: a new #GskPathMeasure representing @path
- **/
+ * Returns: a new `GskPathMeasure` representing @path
+ */
 GskPathMeasure *
 gsk_path_measure_new_with_tolerance (GskPath *path,
                                      float    tolerance)
@@ -126,12 +123,12 @@ gsk_path_measure_new_with_tolerance (GskPath *path,
 
 /**
  * gsk_path_measure_ref:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  *
- * Increases the reference count of a #GskPathMeasure by one.
+ * Increases the reference count of a `GskPathMeasure` by one.
  *
- * Returns: the passed in #GskPathMeasure.
- **/
+ * Returns: the passed in `GskPathMeasure`.
+ */
 GskPathMeasure *
 gsk_path_measure_ref (GskPathMeasure *self)
 {
@@ -144,11 +141,12 @@ gsk_path_measure_ref (GskPathMeasure *self)
 
 /**
  * gsk_path_measure_unref:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
+ *
+ * Decreases the reference count of a `GskPathMeasure` by one.
  *
- * Decreases the reference count of a #GskPathMeasure by one.
  * If the resulting reference count is zero, frees the path_measure.
- **/
+ */
 void
 gsk_path_measure_unref (GskPathMeasure *self)
 {
@@ -173,7 +171,7 @@ gsk_path_measure_unref (GskPathMeasure *self)
 
 /**
  * gsk_path_measure_get_path:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  *
  * Returns the path that the measure was created for.
  *
@@ -189,7 +187,7 @@ gsk_path_measure_get_path (GskPathMeasure *self)
 
 /**
  * gsk_path_measure_get_tolerance:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  *
  * Returns the tolerance that the measure was created with.
  *
@@ -205,7 +203,7 @@ gsk_path_measure_get_tolerance (GskPathMeasure *self)
 
 /**
  * gsk_path_measure_get_n_contours:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  *
  * Returns the number of contours in the path being measured.
  *
@@ -213,7 +211,7 @@ gsk_path_measure_get_tolerance (GskPathMeasure *self)
  * or not.
  *
  * Returns: The number of contours
- **/
+ */
 gsize
 gsk_path_measure_get_n_contours (GskPathMeasure *self)
 {
@@ -224,7 +222,7 @@ gsk_path_measure_get_n_contours (GskPathMeasure *self)
 
 /**
  * gsk_path_measure_restrict_to_contour:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  * @contour: contour to restrict to or (gsize) -1 for using the
  *     whole path
  *
@@ -232,7 +230,7 @@ gsk_path_measure_get_n_contours (GskPathMeasure *self)
  *
  * If @contour >= gsk_path_measure_get_n_contours() - so in
  * particular when it is set to -1 - the whole path will be used.
- **/
+ */
 void
 gsk_path_measure_restrict_to_contour (GskPathMeasure *self,
                                       gsize           contour)
@@ -259,14 +257,14 @@ gsk_path_measure_restrict_to_contour (GskPathMeasure *self,
 
 /**
  * gsk_path_measure_get_length:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  *
  * Gets the length of the path being measured.
  *
  * The length is cached, so this function does not do any work.
  *
  * Returns: The length of the path measured by @self
- **/
+ */
 float
 gsk_path_measure_get_length (GskPathMeasure *self)
 {
@@ -277,13 +275,13 @@ gsk_path_measure_get_length (GskPathMeasure *self)
 
 /**
  * gsk_path_measure_is_closed:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  *
  * Returns if the path being measured represents a single closed
  * contour.
  *
- * Returns: %TRUE if the current path is closed
- **/
+ * Returns: `TRUE` if the current path is closed
+ */
 gboolean
 gsk_path_measure_is_closed (GskPathMeasure *self)
 {
@@ -311,12 +309,12 @@ gsk_path_measure_clamp_distance (GskPathMeasure *self,
 
 /**
  * gsk_path_measure_get_point:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  * @distance: distance into the path
  * @pos: (out caller-allocates) (optional): The coordinates
- *    of the position at @distance
+ *  of the position at @distance
  * @tangent: (out caller-allocates) (optional): The tangent
- *    to the position at @distance
+ *  to the position at @distance
  *
  * Calculates the coordinates and tangent of the point @distance
  * units into the path. The value will be clamped to the length
@@ -326,9 +324,9 @@ gsk_path_measure_clamp_distance (GskPathMeasure *self,
  * point and tangent will describe the line starting at that point
  * going forward.
  *
- * If @self describes an empty path, the returned point will be 
+ * If @self describes an empty path, the returned point will be
  * set to `(0, 0)` and the tangent will be the x axis or `(1, 0)`.
- **/
+ */
 void
 gsk_path_measure_get_point (GskPathMeasure   *self,
                             float             distance,
@@ -378,7 +376,7 @@ gsk_path_measure_get_point (GskPathMeasure   *self,
 
 /**
  * gsk_path_measure_get_closest_point:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  * @point: the point to fond the closest point to
  * @out_pos: (out caller-allocates) (optional): return location
  *    for the closest point
@@ -388,12 +386,12 @@ gsk_path_measure_get_point (GskPathMeasure   *self,
  * If the path being measured is empty, return 0 and set
  * @out_pos to (0, 0).
  *
- * This is a simpler and slower version of
- * gsk_path_measure_get_closest_point_full(). Use that one if you
- * need more control.
+ * This is a simpler version of
+ * [method@Gsk.PathMeasure.get_closest_point_full].
+ * Use that one if you need more control.
  *
  * Returns: The offset into the path of the closest point
- **/
+ */
 float
 gsk_path_measure_get_closest_point (GskPathMeasure         *self,
                                     const graphene_point_t *point,
@@ -421,25 +419,27 @@ gsk_path_measure_get_closest_point (GskPathMeasure         *self,
 
 /**
  * gsk_path_measure_get_closest_point_full:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  * @point: the point to fond the closest point to
  * @threshold: The maximum allowed distance between the path and @point.
- *     Use INFINITY to look for any point.
+ *   Use `INFINITY` to look for any point.
  * @out_distance: (out caller-allocates) (optional): The 
- *     distance between the found closest point on the path and the given
- *     @point.
+ *   distance between the found closest point on the path and the given
+ *   @point.
  * @out_pos: (out caller-allocates) (optional): return location
- *     for the closest point
+ *   for the closest point
  * @out_offset: (out caller-allocates) (optional): The offset into
- *     the path of the found point
+ *   the path of the found point
  * @out_tangent: (out caller-allocates) (optional): return location for
- *     the tangent at the closest point
+ *   the tangent at the closest point
  *
- * Gets the point on the path that is closest to @point. If no point on
- * path is closer to @point than @threshold, return %FALSE.
+ * Gets the point on the path that is closest to @point.
  *
- * Returns: %TRUE if a point was found, %FALSE otherwise.
- **/
+ * If no point on path is closer to @point than @threshold,
+ * return `FALSE`.
+ *
+ * Returns: `TRUE` if a point was found, `FALSE` otherwise.
+ */
 gboolean
 gsk_path_measure_get_closest_point_full (GskPathMeasure         *self,
                                          const graphene_point_t *point,
@@ -491,14 +491,14 @@ gsk_path_measure_get_closest_point_full (GskPathMeasure         *self,
 
 /**
  * gsk_path_measure_in_fill:
- * @self: a #GskPathMeasure
+ * @self: a `GskPathMeasure`
  * @point: the point to test
  * @fill_rule: the fill rule to follow
  *
  * Returns whether the given point is inside the area that would be
  * affected if the path of @self was filled according to @fill_rule.
  *
- * Returns: %TRUE if @point is inside
+ * Returns: `TRUE` if @point is inside
  */
 gboolean
 gsk_path_measure_in_fill (GskPathMeasure         *self,
@@ -571,23 +571,22 @@ gsk_path_builder_add_segment_chunk (GskPathBuilder *self,
 
 /**
  * gsk_path_builder_add_segment:
- * @self: a #GskPathBuilder 
- * @measure: the #GskPathMeasure to take the segment to
+ * @self: a `GskPathBuilder`
+ * @measure: the `GskPathMeasure` to take the segment to
  * @start: start distance into the path
  * @end: end distance into the path
  *
  * Adds to @self the segment of @measure from @start to @end.
  *
  * The distances are given relative to the length of @measure's path,
- * from 0 for the beginning of the path to
- * gsk_path_measure_get_length() for the end of the path. The values
- * will be clamped to that range.
+ * from 0 for the beginning of the path to [method@Gsk.PathMeasure.get_length]
+ * for the end of the path. The values will be clamped to that range.
  *
  * If @start >= @end after clamping, the path will first add the segment
  * from @start to the end of the path, and then add the segment from
  * the beginning to @end. If the path is closed, these segments will
  * be connected.
- **/
+ */
 void
 gsk_path_builder_add_segment (GskPathBuilder *self,
                               GskPathMeasure *measure,
diff --git a/gsk/gskrendernodeimpl.c b/gsk/gskrendernodeimpl.c
index 9e5b939e4c..ff343fba17 100644
--- a/gsk/gskrendernodeimpl.c
+++ b/gsk/gskrendernodeimpl.c
@@ -4701,7 +4701,7 @@ gsk_stroke_node_get_child (GskRenderNode *node)
  * gsk_stroke_node_get_path:
  * @node: (type GskStrokeNode): a stroke #GskRenderNode
  *
- * Retrievs the path that will be stroked with the contents of
+ * Retrieves the path that will be stroked with the contents of
  * the @node.
  *
  * Returns: (transfer none): a #GskPath
diff --git a/gsk/gskstroke.c b/gsk/gskstroke.c
index ac89d91a9d..a22a58c3df 100644
--- a/gsk/gskstroke.c
+++ b/gsk/gskstroke.c
@@ -22,24 +22,8 @@
 #include "gskstrokeprivate.h"
 
 /**
- * SECTION:gskstroke
- * @Title: Stroke
- * @Short_description: Properties of a stroke operation
- * @See_also: #GskPath, gsk_stroke_node_new()
- *
- * This section describes the #GskStroke structure that is used to
- * describe lines and curves that are more complex than simple rectangles.
- *
- * #GskStroke is an immutable struct. After creation, you cannot change
- * the types it represents. Instead, new #GskStroke have to be created.
- * The #GskStrokeBuilder structure is meant to help in this endeavor.
- */
-
-/**
- * GskStroke:
- *
- * A #GskStroke struct is an opaque struct that should be copied
- * on use.
+ * A `GskStroke` struct collects the parameters that influence
+ * the operation of stroking a path.
  */
 
 G_DEFINE_BOXED_TYPE (GskStroke, gsk_stroke,
@@ -53,8 +37,8 @@ G_DEFINE_BOXED_TYPE (GskStroke, gsk_stroke,
  *
  * Creates a new #GskStroke with the given @line_width.
  *
- * Returns: a new #GskStroke
- **/
+ * Returns: a new `GskStroke`
+ */
 GskStroke *
 gsk_stroke_new (float line_width)
 {
@@ -74,12 +58,12 @@ gsk_stroke_new (float line_width)
 
 /**
  * gsk_stroke_copy:
- * @other: #GskStroke to copy
+ * @other: `GskStroke` to copy
  *
  * Creates a copy of the given @other stroke.
  *
- * Returns: a new #GskStroke. Use gsk_stroke_free() to free it.
- **/
+ * Returns: a new `GskStroke`. Use [method@Gsk.Stroke.free] to free it
+ */
 GskStroke *
 gsk_stroke_copy (const GskStroke *other)
 {
@@ -96,10 +80,10 @@ gsk_stroke_copy (const GskStroke *other)
 
 /**
  * gsk_stroke_free:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  *
- * Frees a #GskStroke.
- **/
+ * Frees a `GskStroke`.
+ */
 void
 gsk_stroke_free (GskStroke *self)
 {
@@ -176,8 +160,9 @@ gsk_stroke_to_cairo (const GskStroke *self,
  *
  * Checks if 2 strokes are identical.
  *
- * Returns: %TRUE if the 2 strokes are equal, %FALSE otherwise
- **/
+ * Returns: `TRUE` if the 2 strokes are equal,
+ *   `FALSE` otherwise
+ */
 gboolean
 gsk_stroke_equal (gconstpointer stroke1,
                   gconstpointer stroke2)
@@ -190,12 +175,12 @@ gsk_stroke_equal (gconstpointer stroke1,
 
 /**
  * gsk_stroke_set_line_width:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  * @line_width: width of the line in pixels
  *
  * Sets the line width to be used when stroking. The line width
  * must be > 0.
- **/
+ */
 void
 gsk_stroke_set_line_width (GskStroke *self,
                            float      line_width)
@@ -208,12 +193,12 @@ gsk_stroke_set_line_width (GskStroke *self,
 
 /**
  * gsk_stroke_get_line_width:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  *
  * Gets the line width used.
  *
  * Returns: The line width
- **/
+ */
 float
 gsk_stroke_get_line_width (const GskStroke *self)
 {
@@ -224,12 +209,13 @@ gsk_stroke_get_line_width (const GskStroke *self)
 
 /**
  * gsk_stroke_set_line_cap:
- * @self: a #GskStroke
- * @line_cap: the #GskLineCap
+ * @self: a`GskStroke`
+ * @line_cap: the `GskLineCap`
  *
  * Sets the line cap to be used when stroking.
- * See #GskLineCap for details.
- **/
+ *
+ * See [enum@Gsk.LineCap] for details.
+ */
 void
 gsk_stroke_set_line_cap (GskStroke  *self,
                          GskLineCap  line_cap)
@@ -241,12 +227,14 @@ gsk_stroke_set_line_cap (GskStroke  *self,
 
 /**
  * gsk_stroke_get_line_cap:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  *
- * Gets the line cap used. See #GskLineCap for details.
+ * Gets the line cap used.
+ *
+ * See [enum@Gsk.LineCap] for details.
  *
  * Returns: The line cap
- **/
+ */
 GskLineCap
 gsk_stroke_get_line_cap (const GskStroke *self)
 {
@@ -257,12 +245,13 @@ gsk_stroke_get_line_cap (const GskStroke *self)
 
 /**
  * gsk_stroke_set_line_join:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  * @line_join: The line join to use
  *
  * Sets the line join to be used when stroking.
- * See #GskLineJoin for details.
- **/
+ *
+ * See [enum@Gsk.LineJoin] for details.
+ */
 void
 gsk_stroke_set_line_join (GskStroke   *self,
                           GskLineJoin  line_join)
@@ -274,12 +263,14 @@ gsk_stroke_set_line_join (GskStroke   *self,
 
 /**
  * gsk_stroke_get_line_join:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  *
- * Gets the line join used. See #GskLineJoin for details.
+ * Gets the line join used.
+ *
+ * See [enum@Gsk.LineJoin] for details.
  *
  * Returns: The line join
- **/
+ */
 GskLineJoin
 gsk_stroke_get_line_join (const GskStroke *self)
 {
@@ -290,16 +281,16 @@ gsk_stroke_get_line_join (const GskStroke *self)
 
 /**
  * gsk_stroke_set_miter_limit:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  * @limit: the miter limit, must be non-negative
  *
  * Sets the limit for the distance from the corner where sharp
  * turns of joins get cut off. The miter limit is in units of
  * line width.
  *
- * For joins of type %GSK_LINE_JOIN_MITER that exceed the miter
+ * For joins of type `GSK_LINE_JOIN_MITER` that exceed the miter
  * limit, the join gets rendered as if it was of type
- * %GSK_LINE_JOIN_BEVEL. For joins of type %GSK_LINE_JOIN_MITER_CLIP,
+ * `GSK_LINE_JOIN_BEVEL`. For joins of type `GSK_LINE_JOIN_MITER_CLIP`,
  * the miter is clipped at a distance of half the miter limit.
  */
 void
@@ -314,9 +305,9 @@ gsk_stroke_set_miter_limit (GskStroke  *self,
 
 /**
  * gsk_stroke_get_miter_limit:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  *
- * Returns the miter limit of a #GskStroke.
+ * Returns the miter limit of a `GskStroke`.
  */
 float
 gsk_stroke_get_miter_limit (const GskStroke *self)
@@ -328,32 +319,35 @@ gsk_stroke_get_miter_limit (const GskStroke *self)
 
 /**
  * gsk_stroke_set_dash:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  * @dash: (array length=n_dash) (transfer none) (nullable):
- *     the array of dashes 
+ *     the array of dashes
  * @n_dash: number of elements in @dash
  *
- * Sets the dash pattern to use by this stroke. A dash pattern is specified by
- * an array of alternating non-negative values. Each value provides the length
- * of alternate "on" and "off" portions of the stroke.  
- * 
- * Each "on" segment will have caps applied as if the segment were a separate
- * contour. In particular, it is valid to use an "on" length of 0 with
- * @GSK_LINE_CAP_ROUND or @GSK_LINE_CAP_SQUARE to draw dots or squares along
- * a path.
+ * Sets the dash pattern to use by this stroke.
  *
- * If @n_dash is 0, if all elements in @dash are 0, or if there are negative
- * values in @dash, then dashing is disabled.
+ * A dash pattern is specified by an array of alternating non-negative
+ * values. Each value provides the length of alternate "on" and "off"
+ * portions of the stroke.
  *
- * If @n_dash is 1, an alternating "on" and "off" pattern with the single
- * dash length provided is assumed.
+ * Each "on" segment will have caps applied as if the segment were a
+ * separate contour. In particular, it is valid to use an "on" length
+ * of 0 with `GSK_LINE_CAP_ROUND` or `GSK_LINE_CAP_SQUARE` to draw dots
+ * or squares along a path.
  *
- * If @n_dash is uneven, the dash array will be used with the first element
- * in @dash defining an "on" or "off" in alternating passes through the array.
+ * If @n_dash is 0, if all elements in @dash are 0, or if there are
+ * negative values in @dash, then dashing is disabled.
+ *
+ * If @n_dash is 1, an alternating "on" and "off" pattern with the
+ * single dash length provided is assumed.
+ *
+ * If @n_dash is uneven, the dash array will be used with the first
+ * element in @dash defining an "on" or "off" in alternating passes
+ * through the array.
  *
  * You can specify a starting offset into the dash with
- * @gsk_stroke_set_dash_offset().
- **/
+ * [method@Gsk.Stroke.set_dash_offset].
+ */
 void
 gsk_stroke_set_dash (GskStroke   *self,
                      const float *dash,
@@ -385,15 +379,15 @@ gsk_stroke_set_dash (GskStroke   *self,
 
 /**
  * gsk_stroke_get_dash:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  * @n_dash: (out caller-allocates): number of elements
  *     in the array returned
  *
- * Gets the dash array in use or %NULL if dashing is disabled.
+ * Gets the dash array in use or `NULL` if dashing is disabled.
  *
  * Returns: (array length=n_dash) (transfer none) (nullable):
- *     The dash array or %NULL if the dash array is empty.
- **/
+ *   The dash array or `NULL` if the dash array is empty.
+ */
 const float *
 gsk_stroke_get_dash (const GskStroke *self,
                      gsize           *n_dash)
@@ -408,15 +402,16 @@ gsk_stroke_get_dash (const GskStroke *self,
 
 /**
  * gsk_stroke_set_dash_offset:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  * @offset: offset into the dash pattern
  *
- * Sets the offset into the dash pattern set via gsk_stroke_set_dash() where
- * dashing should begin.
+ * Sets the offset into the dash pattern where dashing should begin.
  *
- * This is an offset into the length of the path, not an index into the array values of
- * the dash array.
- **/
+ * This is an offset into the length of the path, not an index into
+ * the array values of the dash array.
+ *
+ * See [method@Gsk.Stroke.set_dash] for more details on dashing.
+ */
 void
 gsk_stroke_set_dash_offset (GskStroke *self,
                             float      offset)
@@ -428,9 +423,9 @@ gsk_stroke_set_dash_offset (GskStroke *self,
 
 /**
  * gsk_stroke_get_dash_offset:
- * @self: a #GskStroke
+ * @self: a `GskStroke`
  *
- * Returns the dash_offset of a #GskStroke.
+ * Returns the dash_offset of a `GskStroke`.
  */
 float
 gsk_stroke_get_dash_offset (const GskStroke *self)