Merge branch 'docs-cleanup' into 'master'

introspection: Stop using allow-none

See merge request GNOME/pango!333

63 files changed, 1531 insertions, 1473 deletions

diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index 25929a78..aa183e5d 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -49,19 +49,19 @@ in the gtk-doc / gnome-doc style. For instance:
 
 /**
  * pango_layout_get_line:
- * @layout: a #PangoLayout
+ * @layout: a `PangoLayout`
  * @line: the index of a line, which must be between 0 and
- *        pango_layout_get_line_count(layout) - 1, inclusive.
+ *   `pango_layout_get_line_count(layout) - 1`, inclusive.
  * 
- * Retrieves a particular line from a #PangoLayout (or @layout.)
+ * Retrieves a particular line from a `PangoLayout` (or @layout.)
  * 
- * Return value: the requested #PangoLayoutLine, or %NULL if the
- *               index is out of range. This layout line can
- *               be ref'ed and retained, but will become invalid
- *               if changes are made to the #PangoLayout.
+ * Return value: the requested `PangoLayoutLine`, or %NULL
+ *   if the index is out of range. This layout line can
+ *   be ref'ed and retained, but will become invalid
+ *   if changes are made to the `PangoLayout`.
  *
  * Since: 1.6
- **/
+ */
 PangoLayoutLine *
 pango_layout_get_line (PangoLayout *layout,
 		       int          line)
diff --git a/pango/break.c b/pango/break.c
index c34d0512..7d204fa3 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -143,17 +143,18 @@ typedef enum
  * pango_default_break:
  * @text: text to break. Must be valid UTF-8
  * @length: length of text in bytes (may be -1 if @text is nul-terminated)
- * @analysis: (nullable): a #PangoAnalysis for the @text
+ * @analysis: (nullable): a `PangoAnalysis` structure for the @text
  * @attrs: logical attributes to fill in
  * @attrs_len: size of the array passed as @attrs
  *
  * This is the default break algorithm.
  *
- * It applies Unicode rules without language-specific tailoring, therefore
- * the @analyis argument is unused and can be %NULL.
+ * It applies Unicode rules without language-specific
+ * tailoring, therefore the @analyis argument is unused
+ * and can be %NULL.
  *
- * See pango_tailor_break() for language-specific breaks.
- **/
+ * See [func@Pango.tailor_break] for language-specific breaks.
+ */
 void
 pango_default_break (const gchar   *text,
 		     gint           length,
@@ -1617,19 +1618,20 @@ tailor_break (const char    *text,
 
 /**
  * pango_break:
- * @text:      the text to process. Must be valid UTF-8
- * @length:    length of @text in bytes (may be -1 if @text is nul-terminated)
- * @analysis:  #PangoAnalysis structure from pango_itemize()
- * @attrs:     (array length=attrs_len): an array to store character
- *             information in
+ * @text: the text to process. Must be valid UTF-8
+ * @length: length of @text in bytes (may be -1 if @text is nul-terminated)
+ * @analysis: `PangoAnalysis` structure for @text
+ * @attrs: (array length=attrs_len): an array to store character information in
  * @attrs_len: size of the array passed as @attrs
  *
- * Determines possible line, word, and character breaks for a string of
- * Unicode text with a single analysis.
+ * Determines possible line, word, and character breaks
+ * for a string of Unicode text with a single analysis.
  *
- * For most purposes you may want to use pango_get_log_attrs().
+ * For most purposes you may want to use
+ * [func@Pango.get_log_attrs].
  *
- * Deprecated: 1.44: Use pango_default_break() and pango_tailor_break()
+ * Deprecated: 1.44: Use [func@Pango.default_break] and
+ *   [func@Pango.tailor_break]
  */
 void
 pango_break (const gchar   *text,
@@ -1656,15 +1658,18 @@ pango_break (const gchar   *text,
  *
  * Locates a paragraph boundary in @text.
  *
- * A boundary is caused by delimiter characters, such as a newline, carriage
- * return, carriage return-newline pair, or Unicode paragraph separator character.
- * The index of the run of delimiters is returned in @paragraph_delimiter_index.
- * The index of the start of the paragrap (index after all delimiters) is stored
+ * A boundary is caused by delimiter characters, such as
+ * a newline, carriage return, carriage return-newline pair,
+ * or Unicode paragraph separator character.
+ *
+ * The index of the run of delimiters is returned in
+ * @paragraph_delimiter_index. The index of the start
+ * of the paragrap (index after all delimiters) is stored
  * in @next_paragraph_start.
  *
- * If no delimiters are found, both @paragraph_delimiter_index and
- * @next_paragraph_start are filled with the length of @text (an index one
- * off the end).
+ * If no delimiters are found, both @paragraph_delimiter_index
+ * and @next_paragraph_start are filled with the length of @text
+ * (an index one off the end).
  */
 void
 pango_find_paragraph_boundary (const gchar *text,
@@ -1750,16 +1755,18 @@ pango_find_paragraph_boundary (const gchar *text,
  * pango_tailor_break:
  * @text: text to process. Must be valid UTF-8
  * @length: length in bytes of @text
- * @analysis: `PangoAnalysis` structure from [func@itemize] for @text
+ * @analysis: `PangoAnalysis` for @text
  * @offset: Byte offset of @text from the beginning of the
- *     paragraph, or -1 to ignore attributes from @analysis
+ *   paragraph, or -1 to ignore attributes from @analysis
  * @log_attrs: (array length=log_attrs_len): array with one `PangoLogAttr`
  *   per character in @text, plus one extra, to be filled in
  * @log_attrs_len: length of @log_attrs array
  *
- * Apply language-specific tailoring to the breaks in @log_attrs.
+ * Apply language-specific tailoring to the breaks
+ * in @log_attrs.
  *
- * The line breaks are assumed to have been produced by [func@default_break].
+ * The line breaks are assumed to have been produced
+ * by [func@Pango.default_break].
  *
  * If @offset is not -1, it is used to apply attributes
  * from @analysis that are relevant to line breaking.
@@ -1825,11 +1832,13 @@ tailor_segment (const char      *range_start,
  *
  * Computes a `PangoLogAttr` for each character in @text.
  *
- * The @log_attrs array must have one `PangoLogAttr` for each position in @text;
- * if @text contains N characters, it has N+1 positions, including the last
- * position at the end of the text. @text should be an entire paragraph; logical
- * attributes can't be computed without context (for example you need to see
- * spaces on either side of a word to know the word is a word).
+ * The @log_attrs array must have one `PangoLogAttr` for
+ * each position in @text; if @text contains N characters,
+ * it has N+1 positions, including the last position at the
+ * end of the text. @text should be an entire paragraph;
+ * logical attributes can't be computed without context
+ * (for example you need to see spaces on either side of
+ * a word to know the word is a word).
  */
 void
 pango_get_log_attrs (const char    *text,
diff --git a/pango/ellipsize.c b/pango/ellipsize.c
index 0d54483e..e05277f6 100644
--- a/pango/ellipsize.c
+++ b/pango/ellipsize.c
@@ -243,7 +243,7 @@ line_iter_prev_cluster (EllipsizeState *state,
  * - Starts a grapheme - checked here
  *
  * In the future we'd also like to add a check for cursive connectivity here.
- * This should be an addition to #PangoGlyphVisAttr
+ * This should be an addition to `PangoGlyphVisAttr`
  *
  */
 
@@ -735,11 +735,11 @@ current_width (EllipsizeState *state)
 
 /**
  * _pango_layout_line_ellipsize:
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  * @attrs: Attributes being used for itemization/shaping
  * @shape_flags: Flags to use when shaping
  *
- * Given a #PangoLayoutLine with the runs still in logical order, ellipsize
+ * Given a `PangoLayoutLine` with the runs still in logical order, ellipsize
  * it according the layout's policy to fit within the set width of the layout.
  *
  * Return value: whether the line had to be ellipsized
diff --git a/pango/fonts.c b/pango/fonts.c
index b199e785..8f08698c 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -183,7 +183,7 @@ pango_font_description_get_family (const PangoFontDescription *desc)
  *
  * The [enum@Pango.Style] enumeration describes whether the font is
  * slanted and the manner in which it is slanted; it can be either
- * #PANGO_STYLE_NORMAL, #PANGO_STYLE_ITALIC, or #PANGO_STYLE_OBLIQUE.
+ * %PANGO_STYLE_NORMAL, %PANGO_STYLE_ITALIC, or %PANGO_STYLE_OBLIQUE.
  *
  * Most fonts will either have a italic style or an oblique style,
  * but not both, and font matching in Pango will match italic
@@ -644,7 +644,7 @@ pango_font_description_unset_fields (PangoFontDescription *desc,
 /**
  * pango_font_description_merge:
  * @desc: a `PangoFontDescription`
- * @desc_to_merge: (allow-none): the `PangoFontDescription` to merge from,
+ * @desc_to_merge: (nullable): the `PangoFontDescription` to merge from,
  *   or %NULL
  * @replace_existing: if %TRUE, replace fields in @desc with the
  *   corresponding values from @desc_to_merge, even if they
@@ -766,7 +766,7 @@ compute_distance (const PangoFontDescription *a,
 /**
  * pango_font_description_better_match:
  * @desc: a `PangoFontDescription`
- * @old_match: (allow-none): a `PangoFontDescription`, or %NULL
+ * @old_match: (nullable): a `PangoFontDescription`, or %NULL
  * @new_match: a `PangoFontDescription`
  *
  * Determines if the style attributes of @new_match are a closer match
@@ -984,7 +984,7 @@ pango_font_description_free (PangoFontDescription *desc)
 
 /**
  * pango_font_descriptions_free:
- * @descs: (allow-none) (array length=n_descs) (transfer full): a pointer
+ * @descs: (nullable) (array length=n_descs) (transfer full): a pointer
  *   to an array of `PangoFontDescription`, may be %NULL
  * @n_descs: number of font descriptions in @descs
  *
@@ -1803,10 +1803,8 @@ pango_font_find_shaper (PangoFont     *font,
  * pango_font_get_glyph_extents:
  * @font: (nullable): a `PangoFont`
  * @glyph: the glyph index
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph
- *            as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of
- *            the glyph or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the glyph as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical extents of the glyph
  *
  * Gets the logical and ink extents of a glyph within a font.
  *
@@ -1851,7 +1849,7 @@ pango_font_get_glyph_extents  (PangoFont      *font,
 /**
  * pango_font_get_metrics:
  * @font: (nullable): a `PangoFont`
- * @language: (allow-none): language tag used to determine which script
+ * @language: (nullable): language tag used to determine which script
  *   to get the metrics for, or %NULL to indicate to get the metrics for
  *   the entire font.
  *
@@ -1893,21 +1891,22 @@ pango_font_get_metrics (PangoFont     *font,
 
 /**
  * pango_font_get_font_map:
- * @font: (nullable): a `PangoFont`, or %NULL
+ * @font: (nullable): a `PangoFont`
  *
  * Gets the font map for which the font was created.
  *
- * Note that the font maintains a *weak* reference to the font map, so if
- * all references to font map are dropped, the font map will be finalized
- * even if there are fonts created with the font map that are still alive.
+ * Note that the font maintains a *weak* reference to
+ * the font map, so if all references to font map are
+ * dropped, the font map will be finalized even if there
+ * are fonts created with the font map that are still alive.
  * In that case this function will return %NULL.
  *
- * It is the responsibility of the user to ensure that the font map is kept
- * alive. In most uses this is not an issue as a #PangoContext holds
- * a reference to the font map.
+ * It is the responsibility of the user to ensure that the
+ * font map is kept alive. In most uses this is not an issue
+ * as a `PangoContext` holds a reference to the font map.
  *
- * Return value: (transfer none) (nullable): the `PangoFontMap` for the
- *   font, or %NULL if @font is %NULL.
+ * Return value: (transfer none) (nullable): the `PangoFontMap`
+ *   for the font
  *
  * Since: 1.10
  */
@@ -1947,11 +1946,12 @@ pango_font_get_face (PangoFont *font)
  *
  * Get a `hb_font_t` object backing this font.
  *
- * Note that the objects returned by this function are cached and immutable.
- * If you need to make changes to the `hb_font_t`, use hb_font_create_sub_font().
+ * Note that the objects returned by this function are cached
+ * and immutable. If you need to make changes to the `hb_font_t`,
+ * use hb_font_create_sub_font().
  *
- * Returns: (transfer none) (nullable): the `hb_font_t` object backing the
- *   font, or %NULL if the font does not have one
+ * Returns: (transfer none) (nullable): the `hb_font_t` object
+ *   backing the font
  *
  * Since: 1.44
  */
@@ -2311,7 +2311,7 @@ pango_font_family_get_name (PangoFontFamily  *family)
 /**
  * pango_font_family_list_faces:
  * @family: a `PangoFontFamily`
- * @faces: (out) (allow-none) (array length=n_faces) (transfer container):
+ * @faces: (out) (optional) (array length=n_faces) (transfer container):
  *   location to store an array of pointers to `PangoFontFace` objects,
  *   or %NULL. This array should be freed with g_free() when it is no
  *   longer needed.
@@ -2369,13 +2369,13 @@ pango_font_family_real_get_face (PangoFontFamily *family,
  * pango_font_family_get_face:
  * @family: a `PangoFontFamily`
  * @name: (nullable): the name of a face. If the name is %NULL,
- *     the family's default face (fontconfig calls it "Regular")
- *     will be returned.
+ *   the family's default face (fontconfig calls it "Regular")
+ *   will be returned.
  *
  * Gets the `PangoFontFace` of @family with the given name.
  *
  * Returns: (transfer none) (nullable): the `PangoFontFace`,
- *     or %NULL if no face with the given name exists.
+ *   or %NULL if no face with the given name exists.
  *
  * Since: 1.46
  */
@@ -2526,8 +2526,8 @@ pango_font_face_get_face_name (PangoFontFace *face)
  * pango_font_face_list_sizes:
  * @face: a `PangoFontFace`.
  * @sizes: (out) (array length=n_sizes) (nullable) (optional):
- *         location to store a pointer to an array of int. This array
- *         should be freed with g_free().
+ *   location to store a pointer to an array of int. This array
+ *   should be freed with g_free().
  * @n_sizes: location to store the number of elements in @sizes
  *
  * List the available sizes for a font.
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index 6c2338f1..f6e59016 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -31,7 +31,7 @@
  * Create a new `PangoGlyphString`.
  *
  * Return value: the newly allocated `PangoGlyphString`, which
- *               should be freed with [method@Pango.GlyphString.free].
+ *   should be freed with [method@Pango.GlyphString.free].
  */
 PangoGlyphString *
 pango_glyph_string_new (void)
@@ -48,8 +48,8 @@ pango_glyph_string_new (void)
 
 /**
  * pango_glyph_string_set_size:
- * @string:    a `PangoGlyphString`.
- * @new_len:   the new length of the string.
+ * @string: a `PangoGlyphString`.
+ * @new_len: the new length of the string
  *
  * Resize a glyph string to the given length.
  */
@@ -97,13 +97,13 @@ G_DEFINE_BOXED_TYPE (PangoGlyphString, pango_glyph_string,
 
 /**
  * pango_glyph_string_copy:
- * @string: (nullable): a `PangoGlyphString`, may be %NULL
+ * @string: (nullable): a `PangoGlyphString`
  *
  * Copy a glyph string and associated storage.
  *
- * Return value: (nullable): the newly allocated `PangoGlyphString`,
- *               which should be freed with [method@Pango.GlyphString.free],
- *               or %NULL if @string was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphString`
+ *   which should be freed with [method@Pango.GlyphString.free],
+ *   or %NULL if @string was %NULL.
  */
 PangoGlyphString *
 pango_glyph_string_copy (PangoGlyphString *string)
@@ -144,17 +144,15 @@ pango_glyph_string_free (PangoGlyphString *string)
 
 /**
  * pango_glyph_string_extents_range:
- * @glyphs:   a `PangoGlyphString`
- * @start:    start index
- * @end:      end index (the range is the set of bytes with
-	      indices such that start <= index < end)
- * @font:     a `PangoFont`
+ * @glyphs: a `PangoGlyphString`
+ * @start: start index
+ * @end: end index (the range is the set of bytes with
+ *   indices such that start <= index < end)
+ * @font: a `PangoFont`
  * @ink_rect: (out caller-allocates) (optional): rectangle used to
- *            store the extents of the glyph string range as drawn or
- *            %NULL to indicate that the result is not needed.
+ *   store the extents of the glyph string range as drawn
  * @logical_rect: (out caller-allocates) (optional): rectangle used to
- *            store the logical extents of the glyph string range or
- *            %NULL to indicate that the result is not needed.
+ *   store the logical extents of the glyph string range
  *
  * Computes the extents of a sub-portion of a glyph string.
  *
@@ -262,12 +260,10 @@ pango_glyph_string_extents_range (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_extents:
- * @glyphs:   a `PangoGlyphString`
- * @font:     a `PangoFont`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the glyph string
- *            as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none): rectangle used to store the logical extents of the
- *            glyph string or %NULL to indicate that the result is not needed.
+ * @glyphs: a `PangoGlyphString`
+ * @font: a `PangoFont`
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the glyph string as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical extents of the glyph string
  *
  * Compute the logical and ink extents of a glyph string.
  *
@@ -322,9 +318,8 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs)
  * @length: the length of @text, in bytes
  * @embedding_level: the embedding level of the string
  * @logical_widths: (array): an array whose length is the number of
- *                  characters in text (equal to g_utf8_strlen (text,
- *                  length) unless text has NUL bytes) to be filled in
- *                  with the resulting character widths.
+ *   characters in text (equal to `g_utf8_strlen (text, length)` unless
+ *   text has `NUL` bytes) to be filled in with the resulting character widths.
  *
  * Given a `PangoGlyphString` and corresponding text, determine the width
  * corresponding to each character.
@@ -363,14 +358,14 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_index_to_x:
- * @glyphs:    the glyphs return from [func@shape]
- * @text:      the text for the run
- * @length:    the number of bytes (not characters) in @text.
- * @analysis:  the analysis information return from [func@itemize]
- * @index_:    the byte index within @text
- * @trailing:  whether we should compute the result for the beginning (%FALSE)
- *             or end (%TRUE) of the character.
- * @x_pos:     (out): location to store result
+ * @glyphs: the glyphs return from [func@shape]
+ * @text: the text for the run
+ * @length: the number of bytes (not characters) in @text.
+ * @analysis: the analysis information return from [func@itemize]
+ * @index_: the byte index within @text
+ * @trailing: whether we should compute the result for the beginning (%FALSE)
+ *   or end (%TRUE) of the character.
+ * @x_pos: (out): location to store result
  *
  * Converts from character position to x position.
  *
@@ -378,7 +373,6 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
  * Character positions are computed by dividing up each cluster
  * into equal portions.
  */
-
 void
 pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
 			       char             *text,
@@ -493,15 +487,14 @@ pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
 
 /**
  * pango_glyph_string_x_to_index:
- * @glyphs:    the glyphs returned from [func@shape]
- * @text:      the text for the run
- * @length:    the number of bytes (not characters) in text.
- * @analysis:  the analysis information return from [func@itemize]
- * @x_pos:     the x offset (in Pango units)
- * @index_:    (out): location to store calculated byte index within @text
- * @trailing:  (out): location to store a boolean indicating
- *             whether the user clicked on the leading or trailing
- *             edge of the character.
+ * @glyphs: the glyphs returned from [func@shape]
+ * @text: the text for the run
+ * @length: the number of bytes (not characters) in text.
+ * @analysis: the analysis information return from [func@itemize]
+ * @x_pos: the x offset (in Pango units)
+ * @index_: (out): location to store calculated byte index within @text
+ * @trailing: (out): location to store a boolean indicating whether the
+ *   user clicked on the leading or trailing edge of the character
  *
  * Convert from x offset to character position.
  *
diff --git a/pango/modules.c b/pango/modules.c
index b7ba105b..4aea37c5 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -45,8 +45,8 @@ pango_find_map (PangoLanguage *language G_GNUC_UNUSED,
 
 /**
  * pango_map_get_engine: (skip)
- * @map: a #PangoMap
- * @script: a #PangoScript
+ * @map: a `PangoMap`
+ * @script: a `PangoScript`
  *
  * Do not use.  Does not do anything.
  *
@@ -63,8 +63,8 @@ pango_map_get_engine (PangoMap   *map G_GNUC_UNUSED,
 
 /**
  * pango_map_get_engines: (skip)
- * @map: a #PangoMap
- * @script: a #PangoScript
+ * @map: a `PangoMap`
+ * @script: a `PangoScript`
  * @exact_engines: (nullable): location to store list of engines that exactly
  *  handle this script.
  * @fallback_engines: (nullable): location to store list of engines that
@@ -89,7 +89,7 @@ pango_map_get_engines (PangoMap     *map G_GNUC_UNUSED,
 
 /**
  * pango_module_register: (skip)
- * @module: a #PangoIncludedModule
+ * @module: a `PangoIncludedModule`
  *
  * Do not use.  Does not do anything.
  *
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 225dc654..63c031f9 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -49,7 +49,8 @@ static GHashTable *name_map = NULL; /* MT-safe */
  *
  * Allocate a new attribute type ID.
  *
- * The attribute type name can be accessed later by using [type_func@Pango.AttrType.get_name].
+ * The attribute type name can be accessed later
+ * by using [type_func@Pango.AttrType.get_name].
  *
  * Return value: the new type ID.
  */
@@ -82,14 +83,17 @@ pango_attr_type_register (const gchar *name)
  *
  * Fetches the attribute type name.
  *
- * The attribute type name is the string passed in when registering the type
- * using [type_func@attr_type_register].
+ * The attribute type name is the string passed in
+ * when registering the type using
+ * [type_func@attr_type_register].
  *
- * The returned value is an interned string (see g_intern_string() for what
- * that means) that should not be modified or freed.
+ * The returned value is an interned string (see
+ * g_intern_string() for what that means) that should
+ * not be modified or freed.
  *
- * Return value: (nullable): the type ID name (which may be %NULL), or
- *   %NULL if @type is a built-in Pango attribute type or invalid.
+ * Return value: (nullable): the type ID name (which
+ *   may be %NULL), or %NULL if @type is a built-in Pango
+ *   attribute type or invalid.
  *
  * Since: 1.22
  */
@@ -138,8 +142,9 @@ pango_attribute_init (PangoAttribute       *attr,
  *
  * Make a copy of an attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy].
  */
 PangoAttribute *
 pango_attribute_copy (const PangoAttribute *attr)
@@ -178,11 +183,13 @@ G_DEFINE_BOXED_TYPE (PangoAttribute, pango_attribute,
  * @attr1: a `PangoAttribute`
  * @attr2: another `PangoAttribute`
  *
- * Compare two attributes for equality. This compares only the
- * actual value of the two attributes and not the ranges that the
- * attributes apply to.
+ * Compare two attributes for equality.
+ *
+ * This compares only the actual value of the two
+ * attributes and not the ranges that the attributes
+ * apply to.
  *
- * Return value: %TRUE if the two attributes have the same value.
+ * Return value: %TRUE if the two attributes have the same value
  */
 gboolean
 pango_attribute_equal (const PangoAttribute *attr1,
@@ -232,12 +239,13 @@ pango_attr_string_new (const PangoAttrClass *klass,
 
 /**
  * pango_attr_family_new:
- * @family: the family or comma separated list of families
+ * @family: the family or comma-separated list of families
  *
  * Create a new font family attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_family_new (const char *family)
@@ -281,8 +289,9 @@ pango_attr_language_equal (const PangoAttribute *attr1,
  *
  * Create a new language tag attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_language_new (PangoLanguage *language)
@@ -357,8 +366,9 @@ pango_attr_color_new (const PangoAttrClass *klass,
  *
  * Create a new foreground color attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_foreground_new (guint16 red,
@@ -383,8 +393,9 @@ pango_attr_foreground_new (guint16 red,
  *
  * Create a new background color attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_background_new (guint16 red,
@@ -533,12 +544,13 @@ pango_attr_size_new_internal (int size,
 
 /**
  * pango_attr_size_new:
- * @size: the font size, in %PANGO_SCALEths of a point.
+ * @size: the font size, in %PANGO_SCALE-ths of a point
  *
  * Create a new font-size attribute in fractional points.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_size_new (int size)
@@ -548,12 +560,13 @@ pango_attr_size_new (int size)
 
 /**
  * pango_attr_size_new_absolute:
- * @size: the font size, in %PANGO_SCALEths of a device unit.
+ * @size: the font size, in %PANGO_SCALE-ths of a device unit
  *
  * Create a new font-size attribute in device units.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.8
  */
@@ -569,8 +582,9 @@ pango_attr_size_new_absolute (int size)
  *
  * Create a new font slant style attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_style_new (PangoStyle style)
@@ -591,8 +605,9 @@ pango_attr_style_new (PangoStyle style)
  *
  * Create a new font weight attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_weight_new (PangoWeight weight)
@@ -635,8 +650,9 @@ pango_attr_variant_new (PangoVariant variant)
  *
  * Create a new font stretch attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_stretch_new (PangoStretch  stretch)
@@ -689,8 +705,9 @@ pango_attr_font_desc_equal (const PangoAttribute *attr1,
  * This attribute allows setting family, style, weight, variant,
  * stretch, and size simultaneously.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_font_desc_new (const PangoFontDescription *desc)
@@ -712,12 +729,13 @@ pango_attr_font_desc_new (const PangoFontDescription *desc)
 
 /**
  * pango_attr_underline_new:
- * @underline: the underline style.
+ * @underline: the underline style
  *
  * Create a new underline-style attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_underline_new (PangoUnderline underline)
@@ -740,11 +758,12 @@ pango_attr_underline_new (PangoUnderline underline)
  *
  * Create a new underline color attribute.
  *
- * This attribute modifies the color of underlines. If not set, underlines
- * will use the foreground color.
+ * This attribute modifies the color of underlines.
+ * If not set, underlines will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.8
  */
@@ -765,12 +784,13 @@ pango_attr_underline_color_new (guint16 red,
 
 /**
  * pango_attr_strikethrough_new:
- * @strikethrough: %TRUE if the text should be struck-through.
+ * @strikethrough: %TRUE if the text should be struck-through
  *
  * Create a new strike-through attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_strikethrough_new (gboolean strikethrough)
@@ -793,11 +813,12 @@ pango_attr_strikethrough_new (gboolean strikethrough)
  *
  * Create a new strikethrough color attribute.
  *
- * This attribute modifies the color of strikethrough lines. If not set,
- * strikethrough lines will use the foreground color.
+ * This attribute modifies the color of strikethrough lines.
+ * If not set, strikethrough lines will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.8
  */
@@ -823,8 +844,9 @@ pango_attr_strikethrough_color_new (guint16 red,
  *
  * Create a new baseline displacement attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_rise_new (int rise)
@@ -845,11 +867,12 @@ pango_attr_rise_new (int rise)
  *
  * Create a new font size scale attribute.
  *
- * The base font for the affected text will have its size multiplied
- * by @scale_factor.
+ * The base font for the affected text will have
+ * its size multiplied by @scale_factor.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute*
 pango_attr_scale_new (double scale_factor)
@@ -867,17 +890,18 @@ pango_attr_scale_new (double scale_factor)
 /**
  * pango_attr_fallback_new:
  * @enable_fallback: %TRUE if we should fall back on other fonts
- *   for characters the active font is missing.
+ *   for characters the active font is missing
  *
  * Create a new font fallback attribute.
  *
- * If fallback is disabled, characters will only be used from the
- * closest matching font on the system. No fallback will be done to
- * other fonts on the system that might contain the characters in the
- * text.
+ * If fallback is disabled, characters will only be
+ * used from the closest matching font on the system.
+ * No fallback will be done to other fonts on the system
+ * that might contain the characters in the text.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.4
  */
@@ -896,13 +920,14 @@ pango_attr_fallback_new (gboolean enable_fallback)
 
 /**
  * pango_attr_letter_spacing_new:
- * @letter_spacing: amount of extra space to add between graphemes
- *   of the text, in Pango units.
+ * @letter_spacing: amount of extra space to add between
+ *   graphemes of the text, in Pango units
  *
  * Create a new letter-spacing attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.6
  */
@@ -968,18 +993,21 @@ pango_attr_shape_equal (const PangoAttribute *attr1,
  * @ink_rect: ink rectangle to assign to each character
  * @logical_rect: logical rectangle to assign to each character
  * @data: user data pointer
- * @copy_func: (allow-none): function to copy @data when the
- *   attribute is copied. If %NULL, @data is simply copied as a pointer.
- * @destroy_func: (allow-none): function to free @data when the
- *   attribute is freed, or %NULL
+ * @copy_func: (nullable): function to copy @data when the
+ *   attribute is copied. If %NULL, @data is simply copied
+ *   as a pointer
+ * @destroy_func: (nullable): function to free @data when the
+ *   attribute is freed
  *
  * Creates a new shape attribute.
  *
- * Like pango_attr_shape_new(), but a user data pointer is also
- * provided; this pointer can be accessed when later rendering the glyph.
+ * Like [ctor@Pango.AttrShape.new], but a user data pointer
+ * is also provided; this pointer can be accessed when later
+ * rendering the glyph.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.8
  */
@@ -1020,12 +1048,14 @@ pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
  *
  * Create a new shape attribute.
  *
- * A shape is used to impose a particular ink and logical rectangle
- * on the result of shaping a particular glyph. This might be used,
- * for instance, for embedding a picture or a widget inside a `PangoLayout`.
+ * A shape is used to impose a particular ink and logical
+ * rectangle on the result of shaping a particular glyph.
+ * This might be used, for instance, for embedding a picture
+ * or a widget inside a `PangoLayout`.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  */
 PangoAttribute *
 pango_attr_shape_new (const PangoRectangle *ink_rect,
@@ -1040,12 +1070,13 @@ pango_attr_shape_new (const PangoRectangle *ink_rect,
 
 /**
  * pango_attr_gravity_new:
- * @gravity: the gravity value; should not be %PANGO_GRAVITY_AUTO.
+ * @gravity: the gravity value; should not be %PANGO_GRAVITY_AUTO
  *
  * Create a new gravity attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.16
  */
@@ -1066,12 +1097,13 @@ pango_attr_gravity_new (PangoGravity gravity)
 
 /**
  * pango_attr_gravity_hint_new:
- * @hint: the gravity hint value.
+ * @hint: the gravity hint value
  *
  * Create a new gravity hint attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.16
  */
@@ -1094,8 +1126,9 @@ pango_attr_gravity_hint_new (PangoGravityHint hint)
  *
  * Create a new font features tag attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.38
  */
@@ -1120,8 +1153,9 @@ pango_attr_font_features_new (const gchar *features)
  *
  * Create a new foreground alpha attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.38
  */
@@ -1144,8 +1178,9 @@ pango_attr_foreground_alpha_new (guint16 alpha)
  *
  * Create a new background alpha attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.38
  */
@@ -1171,8 +1206,9 @@ pango_attr_background_alpha_new (guint16 alpha)
  * If breaks are disabled, the range will be kept in a
  * single run, as far as possible.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.44
  */
@@ -1195,11 +1231,13 @@ pango_attr_allow_breaks_new (gboolean allow_breaks)
  *
  * Create a new insert-hyphens attribute.
  *
- * Pango will insert hyphens when breaking lines in the middle
- * of a word. This attribute can be used to suppress the hyphen.
+ * Pango will insert hyphens when breaking lines in
+ * the middle of a word. This attribute can be used
+ * to suppress the hyphen.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.44
  */
@@ -1223,8 +1261,9 @@ pango_attr_insert_hyphens_new (gboolean insert_hyphens)
  * Create a new attribute that influences how invisible
  * characters are rendered.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.44
  **/
@@ -1247,8 +1286,9 @@ pango_attr_show_new (PangoShowFlags flags)
  *
  * Create a new overline-style attribute.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.46
  */
@@ -1273,11 +1313,12 @@ pango_attr_overline_new (PangoOverline overline)
  *
  * Create a new overline color attribute.
  *
- * This attribute modifies the color of overlines. If not set, overlines
- * will use the foreground color.
+ * This attribute modifies the color of overlines.
+ * If not set, overlines will use the foreground color.
  *
- * Return value: (transfer full): the newly allocated `PangoAttribute`,
- *   which should be freed with [method@Pango.Attribute.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttribute`, which should be freed with
+ *   [method@Pango.Attribute.destroy]
  *
  * Since: 1.46
  */
@@ -1314,10 +1355,12 @@ _pango_attr_list_init (PangoAttrList *list)
 /**
  * pango_attr_list_new:
  *
- * Create a new empty attribute list with a reference count of one.
+ * Create a new empty attribute list with a reference
+ * count of one.
  *
- * Return value: (transfer full): the newly allocated `PangoAttrList`,
- *   which should be freed with [method@Pango.AttrList.unref].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttrList`, which should be freed with
+ *   [method@Pango.AttrList.unref]
  */
 PangoAttrList *
 pango_attr_list_new (void)
@@ -1331,9 +1374,10 @@ pango_attr_list_new (void)
 
 /**
  * pango_attr_list_ref:
- * @list: (nullable): a `PangoAttrList`, may be %NULL
+ * @list: (nullable): a `PangoAttrList`
  *
- * Increase the reference count of the given attribute list by one.
+ * Increase the reference count of the given attribute
+ * list by one.
  *
  * Return value: The attribute list passed in
  *
@@ -1370,11 +1414,13 @@ _pango_attr_list_destroy (PangoAttrList *list)
 
 /**
  * pango_attr_list_unref:
- * @list: (nullable): a `PangoAttrList`, may be %NULL
+ * @list: (nullable): a `PangoAttrList`
  *
- * Decrease the reference count of the given attribute list by one.
- * If the result is zero, free the attribute list and the attributes
- * it contains.
+ * Decrease the reference count of the given attribute
+ * list by one.
+ *
+ * If the result is zero, free the attribute list
+ * and the attributes it contains.
  */
 void
 pango_attr_list_unref (PangoAttrList *list)
@@ -1393,13 +1439,14 @@ pango_attr_list_unref (PangoAttrList *list)
 
 /**
  * pango_attr_list_copy:
- * @list: (nullable): a `PangoAttrList`, may be %NULL
+ * @list: (nullable): a `PangoAttrList`
  *
  * Copy @list and return an identical new list.
  *
- * Return value: (nullable): the newly allocated `PangoAttrList`,
- *   with a reference count of one, which should be freed with
- *   [method@Pango.AttrList.unref]. Returns %NULL if @list was %NULL.
+ * Return value: (nullable): the newly allocated
+ *   `PangoAttrList`, with a reference count of one,
+ *   which should be freed with [method@Pango.AttrList.unref].
+ *   Returns %NULL if @list was %NULL.
  */
 PangoAttrList *
 pango_attr_list_copy (PangoAttrList *list)
@@ -1465,8 +1512,7 @@ pango_attr_list_insert_internal (PangoAttrList  *list,
 /**
  * pango_attr_list_insert:
  * @list: a `PangoAttrList`
- * @attr: (transfer full): the attribute to insert. Ownership of this
- *   value is assumed by the list.
+ * @attr: (transfer full): the attribute to insert
  *
  * Insert the given attribute into the `PangoAttrList`.
  *
@@ -1486,8 +1532,7 @@ pango_attr_list_insert (PangoAttrList  *list,
 /**
  * pango_attr_list_insert_before:
  * @list: a `PangoAttrList`
- * @attr: (transfer full): the attribute to insert. Ownership of this
- *   value is assumed by the list.
+ * @attr: (transfer full): the attribute to insert
  *
  * Insert the given attribute into the `PangoAttrList`.
  *
@@ -1507,18 +1552,19 @@ pango_attr_list_insert_before (PangoAttrList  *list,
 /**
  * pango_attr_list_change:
  * @list: a `PangoAttrList`
- * @attr: (transfer full): the attribute to insert. Ownership of this
- *   value is assumed by the list.
+ * @attr: (transfer full): the attribute to insert
  *
  * Insert the given attribute into the `PangoAttrList`.
  *
- * It will replace any attributes of the same type on that segment
- * and be merged with any adjoining attributes that are identical.
+ * It will replace any attributes of the same type
+ * on that segment and be merged with any adjoining
+ * attributes that are identical.
  *
- * This function is slower than [method@Pango.AttrList.insert] for
- * creating an attribute list in order (potentially much slower for
- * large lists). However, [method@Pango.AttrList.insert] is not
- * suitable for continually changing a set of attributes since it
+ * This function is slower than [method@Pango.AttrList.insert]
+ * for creating an attribute list in order (potentially
+ * much slower for large lists). However,
+ * [method@Pango.AttrList.insert] is not suitable for
+ * continually changing a set of attributes since it
  * never removes or combines existing attributes.
  */
 void
@@ -1748,8 +1794,9 @@ pango_attr_list_update (PangoAttrList *list,
  *   must be specified since the attributes in @other may only
  *   be present at some subsection of this range)
  *
- * This function opens up a hole in @list, fills it in with attributes
- * from the left, and then merges @other on top of the hole.
+ * This function opens up a hole in @list, fills it
+ * in with attributes from the left, and then merges
+ * @other on top of the hole.
  *
  * This operation is equivalent to stretching every attribute
  * that applies at position @pos in @list by an amount @len,
@@ -1831,9 +1878,9 @@ pango_attr_list_splice (PangoAttrList *list,
  * Gets a list of all attributes in @list.
  *
  * Return value: (element-type Pango.Attribute) (transfer full):
- *   a list of all attributes in @list. To free this value, call
- *   [mehod@Pango.Attribute.destroy] on each value and g_slist_free()
- *   on the list.
+ *   a list of all attributes in @list. To free this value,
+ *   call [mehod@Pango.Attribute.destroy] on each value and
+ *   g_slist_free() on the list.
  *
  * Since: 1.44
  */
@@ -1863,11 +1910,15 @@ pango_attr_list_get_attributes (PangoAttrList *list)
  * @list: a `PangoAttrList`
  * @other_list: the other `PangoAttrList`
  *
- * Checks whether @list and @other_list contain the same attributes and
- * whether those attributes apply to the same ranges. Beware that this
- * will return wrong values if any list contains duplicates.
+ * Checks whether @list and @other_list contain the same
+ * attributes and whether those attributes apply to the
+ * same ranges.
+ *
+ * Beware that this will return wrong values if any list
+ * contains duplicates.
  *
- * Return value: %TRUE if the lists are equal, %FALSE if they aren't.
+ * Return value: %TRUE if the lists are equal, %FALSE if
+ *   they aren't
  *
  * Since: 1.46
  */
@@ -1958,11 +2009,13 @@ _pango_attr_list_get_iterator (PangoAttrList     *list,
  * @list: a `PangoAttrList`
  *
  * Create a iterator initialized to the beginning of the list.
+ *
  * @list must not be modified until this iterator is freed.
  *
- * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
- *   which should be freed with [method@Pango.AttrIterator.destroy].
- **/
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttrIterator`, which should be freed with
+ *   [method@Pango.AttrIterator.destroy]
+ */
 PangoAttrIterator *
 pango_attr_list_get_iterator (PangoAttrList  *list)
 {
@@ -1978,13 +2031,14 @@ pango_attr_list_get_iterator (PangoAttrList  *list)
 
 /**
  * pango_attr_iterator_range:
- * @iterator: a #PangoAttrIterator
+ * @iterator: a PangoAttrIterator
  * @start: (out): location to store the start of the range
  * @end: (out): location to store the end of the range
  *
- * Get the range of the current segment. Note that the
- * stored return values are signed, not unsigned like
- * the values in `PangoAttribute`. To deal with this API
+ * Get the range of the current segment.
+ *
+ * Note that the stored return values are signed, not unsigned
+ * like the values in `PangoAttribute`. To deal with this API
  * oversight, stored return values that wouldn't fit into
  * a signed integer are clamped to %G_MAXINT.
  */
@@ -2007,8 +2061,8 @@ pango_attr_iterator_range (PangoAttrIterator *iterator,
  *
  * Advance the iterator until the next change of style.
  *
- * Return value: %FALSE if the iterator is at the end of the list,
- *   otherwise %TRUE
+ * Return value: %FALSE if the iterator is at the end
+ *   of the list, otherwise %TRUE
  */
 gboolean
 pango_attr_iterator_next (PangoAttrIterator *iterator)
@@ -2078,8 +2132,9 @@ pango_attr_iterator_next (PangoAttrIterator *iterator)
  *
  * Copy a `PangoAttrIterator`.
  *
- * Return value: (transfer full): the newly allocated `PangoAttrIterator`,
- *   which should be freed with [method@Pango.AttrIterator.destroy].
+ * Return value: (transfer full): the newly allocated
+ *   `PangoAttrIterator`, which should be freed with
+ *   [method@Pango.AttrIterator.destroy]
  */
 PangoAttrIterator *
 pango_attr_iterator_copy (PangoAttrIterator *iterator)
@@ -2127,14 +2182,16 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator)
  * @iterator: a `PangoAttrIterator`
  * @type: the type of attribute to find
  *
- * Find the current attribute of a particular type at the iterator
- * location. When multiple attributes of the same type overlap,
- * the attribute whose range starts closest to the current location
- * is used.
+ * Find the current attribute of a particular type
+ * at the iterator location.
  *
- * Return value: (nullable) (transfer none): the current attribute of
- *   the given type, or %NULL if no attribute of that type applies to
- *   the current location.
+ * When multiple attributes of the same type overlap,
+ * the attribute whose range starts closest to the
+ * current location is used.
+ *
+ * Return value: (nullable) (transfer none): the current
+ *   attribute of the given type, or %NULL if no attribute
+ *   of that type applies to the current location.
  */
 PangoAttribute *
 pango_attr_iterator_get (PangoAttrIterator *iterator,
@@ -2161,21 +2218,24 @@ pango_attr_iterator_get (PangoAttrIterator *iterator,
 /**
  * pango_attr_iterator_get_font:
  * @iterator: a `PangoAttrIterator`
- * @desc: a `PangoFontDescription` to fill in with the current values.
- *   The family name in this structure will be set using
- *   [method@Pango.FontDescription.set_family_static] using values from
- *   an attribute in the `PangoAttrList` associated with the iterator,
- *   so if you plan to keep it around, you must call:
- *   pango_font_description_set_family (desc, pango_font_description_get_family (desc)).
- * @language: (allow-none): if non-%NULL, location to store language tag
+ * @desc: a `PangoFontDescription` to fill in with the current
+ *   values. The family name in this structure will be set using
+ *   [method@Pango.FontDescription.set_family_static] using
+ *   values from an attribute in the `PangoAttrList` associated
+ *   with the iterator, so if you plan to keep it around, you
+ *   must call:
+ *   `pango_font_description_set_family (desc, pango_font_description_get_family (desc))`.
+ * @language: (out) (optional): location to store language tag
  *   for item, or %NULL if none is found.
- * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full):
- *   if non-%NULL, location in which to store a list of non-font attributes
- *   at the the current position; only the highest priority value of each
- *   attribute will be added to this list. In order to free this value, you
- *   must call [method@Pango.Attribute.destroy] on each member.
- *
- * Get the font and other attributes at the current iterator position.
+ * @extra_attrs: (out) (optional) (element-type Pango.Attribute) (transfer full):
+ *   location in which to store a list of non-font attributes
+ *   at the the current position; only the highest priority
+ *   value of each attribute will be added to this list. In
+ *   order to free this value, you must call
+ *   [method@Pango.Attribute.destroy] on each member.
+ *
+ * Get the font and other attributes at the current
+ * iterator position.
  */
 void
 pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
@@ -2324,15 +2384,17 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
 /**
  * pango_attr_list_filter:
  * @list: a `PangoAttrList`
- * @func: (scope call) (closure data): callback function; returns %TRUE
- *        if an attribute should be filtered out.
+ * @func: (scope call) (closure data): callback function;
+ *   returns %TRUE if an attribute should be filtered out
  * @data: (closure): Data to be passed to @func
  *
- * Given a `PangoAttrList` and callback function, removes any elements
- * of @list for which @func returns %TRUE and inserts them into a new list.
+ * Given a `PangoAttrList` and callback function, removes
+ * any elements of @list for which @func returns %TRUE and
+ * inserts them into a new list.
  *
- * Return value: (transfer full) (nullable): the new `PangoAttrList` or
- *  %NULL if no attributes of the given types were found.
+ * Return value: (transfer full) (nullable): the new
+ *   `PangoAttrList` or %NULL if no attributes of the
+ *   given types were found
  *
  * Since: 1.2
  */
@@ -2381,9 +2443,9 @@ pango_attr_list_filter (PangoAttrList       *list,
  * iterator.
  *
  * Return value: (element-type Pango.Attribute) (transfer full):
- *   a list of all attributes for the current range. To free this value,
- *   call [method@Pango.Attribute.destroy] on each value and g_slist_free()
- *   on the list.
+ *   a list of all attributes for the current range. To free
+ *   this value, call [method@Pango.Attribute.destroy] on each
+ *   value and g_slist_free() on the list.
  *
  * Since: 1.2
  */
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index db8d8262..d841d715 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -209,28 +209,28 @@ typedef enum
  * @PANGO_UNDERLINE_SINGLE: a single underline should be drawn
  * @PANGO_UNDERLINE_DOUBLE: a double underline should be drawn
  * @PANGO_UNDERLINE_LOW: a single underline should be drawn at a
- *     position beneath the ink extents of the text being
- *     underlined. This should be used only for underlining
- *     single characters, such as for keyboard accelerators.
- *     %PANGO_UNDERLINE_SINGLE should be used for extended
- *     portions of text.
+ *   position beneath the ink extents of the text being
+ *   underlined. This should be used only for underlining
+ *   single characters, such as for keyboard accelerators.
+ *   %PANGO_UNDERLINE_SINGLE should be used for extended
+ *   portions of text.
  * @PANGO_UNDERLINE_ERROR: an underline indicating an error should
- *     be drawn below. The exact style of rendering is up to the
- *     `PangoRenderer` in use, but typical styles include wavy
- *     or dotted lines.
- *     This underline is typically used to indicate an error such
- *     as a possible mispelling; in some cases a contrasting color
- *     may automatically be used. This type of underlining is
- *     available since Pango 1.4.
+ *   be drawn below. The exact style of rendering is up to the
+ *   `PangoRenderer` in use, but typical styles include wavy
+ *   or dotted lines.
+ *   This underline is typically used to indicate an error such
+ *   as a possible mispelling; in some cases a contrasting color
+ *   may automatically be used. This type of underlining is
+ *   available since Pango 1.4.
  * @PANGO_UNDERLINE_SINGLE_LINE: Like @PANGO_UNDERLINE_SINGLE, but
- *     drawn continuously across multiple runs. This type
- *     of underlining is available since Pango 1.46.
+ *   drawn continuously across multiple runs. This type
+ *   of underlining is available since Pango 1.46.
  * @PANGO_UNDERLINE_DOUBLE_LINE: Like @PANGO_UNDERLINE_DOUBLE, but
- *     drawn continuously across multiple runs. This type
- *     of underlining is available since Pango 1.46.
+ *   drawn continuously across multiple runs. This type
+ *   of underlining is available since Pango 1.46.
  * @PANGO_UNDERLINE_ERROR_LINE: Like @PANGO_UNDERLINE_ERROR, but
- *     drawn continuously across multiple runs. This type
- *     of underlining is available since Pango 1.46.
+ *   drawn continuously across multiple runs. This type
+ *   of underlining is available since Pango 1.46.
  *
  * The `PangoUnderline` enumeration is used to specify whether text
  * should be underlined, and if so, the type of underlining.
@@ -251,7 +251,7 @@ typedef enum {
  * PangoOverline:
  * @PANGO_OVERLINE_NONE: no overline should be drawn
  * @PANGO_OVERLINE_SINGLE: Draw a single line above the ink
- *     extents of the text being underlined.
+ *   extents of the text being underlined.
  *
  * The `PangoOverline` enumeration is used to specify whether text
  * should be overlined, and if so, the type of line.
@@ -596,7 +596,7 @@ PangoAttribute *pango_attr_overline_color_new   (guint16       red,
  * @PANGO_SHOW_SPACES: Render spaces, tabs and newlines visibly
  * @PANGO_SHOW_LINE_BREAKS: Render line breaks visibly
  * @PANGO_SHOW_IGNORABLES: Render default-ignorable Unicode
- *      characters visibly
+ *   characters visibly
  *
  * These flags affect how Pango treats characters that are normally
  * not visible in the output.
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index 01da86d3..e85b23e8 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -91,9 +91,9 @@ pango_bidi_type_for_unichar (gunichar ch)
 
 /**
  * pango_log2vis_get_embedding_levels:
- * @text:      the text to itemize.
- * @length:    the number of bytes (not characters) to process, or -1
- *             if @text is nul-terminated and the length should be calculated.
+ * @text: the text to itemize.
+ * @length: the number of bytes (not characters) to process, or -1
+ *   if @text is nul-terminated and the length should be calculated.
  * @pbase_dir: input base direction, and output resolved direction.
  *
  * Return the bidirectional embedding levels of the input paragraph.
diff --git a/pango/pango-color.c b/pango/pango-color.c
index f616e1f0..b6907035 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -34,18 +34,18 @@ G_DEFINE_BOXED_TYPE (PangoColor, pango_color,
 
 /**
  * pango_color_copy:
- * @src: (nullable): color to copy, may be %NULL
+ * @src: (nullable): color to copy
  *
  * Creates a copy of @src.
  *
- * The copy should be freed with pango_color_free(). Primarily
- * used by language bindings, not that useful otherwise (since
- * colors can just be copied by assignment in C).
+ * The copy should be freed with [method@Pango.Color.free].
+ * Primarily used by language bindings, not that useful
+ * otherwise (since colors can just be copied by assignment
+ * in C).
  *
- * Return value: (nullable): the newly allocated `PangoColor`, which
- *   should be freed with [method@Pango.Color.free], or %NULL if
- *   @src was %NULL.
- **/
+ * Return value: (nullable): the newly allocated `PangoColor`,
+ *   which should be freed with [method@Pango.Color.free]
+ */
 PangoColor*
 pango_color_copy (const PangoColor *src)
 {
@@ -63,10 +63,10 @@ pango_color_copy (const PangoColor *src)
 
 /**
  * pango_color_free:
- * @color: (nullable): an allocated #PangoColor, may be %NULL
+ * @color: (nullable): an allocated `PangoColor`
  *
- * Frees a color allocated by pango_color_copy().
- **/
+ * Frees a color allocated by [ctor@Pango.copy].
+ */
 void
 pango_color_free (PangoColor *color)
 {
@@ -78,18 +78,19 @@ pango_color_free (PangoColor *color)
 
 /**
  * pango_color_to_string:
- * @color: a #PangoColor
+ * @color: a `PangoColor`
  *
  * Returns a textual specification of @color.
  *
- * The string is in the hexadecimal form `#rrrrggggbbbb`, where
- * `r`, `g` and `b` are hex digits representing the red, green,
- * and blue components respectively.
+ * The string is in the hexadecimal form `#rrrrggggbbbb`,
+ * where `r`, `g` and `b` are hex digits representing the
+ * red, green, and blue components respectively.
  *
- * Return value: a newly-allocated text string that must be freed with g_free().
+ * Return value: a newly-allocated text string that must
+ *   be freed with g_free().
  *
  * Since: 1.16
- **/
+ */
 gchar *
 pango_color_to_string (const PangoColor *color)
 {
@@ -211,27 +212,29 @@ hex (const char *spec,
 
 /**
  * pango_color_parse_with_alpha:
- * @color: (nullable): a `PangoColor` structure in which to store the
- *   result, or %NULL
- * @alpha: (out) (optional): return location for alpha, or %NULL
+ * @color: (nullable): a `PangoColor` structure in which
+ *   to store the result
+ * @alpha: (out) (optional): return location for alpha
  * @spec: a string specifying the new color
  *
  * Fill in the fields of a color from a string specification.
  *
- * The string can
- * either one of a large set of standard names. (Taken from the CSS Color
- * [specification](https://www.w3.org/TR/css-color-4/#named-colors),
- * or it can be a hexadecimal value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb`
- * or `#rrrrggggbbbb` where `r`, `g` and `b` are hex digits of the red, green,
- * and blue components of the color, respectively. (White in the four
- * forms is `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
+ * The string can either one of a large set of standard names.
+ * (Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors),
+ * or it can be a hexadecimal value in the form `#rgb`,
+ * `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb` where `r`, `g`
+ * and `b` are hex digits of the red, green, and blue components
+ * of the color, respectively. (White in the four forms is
+ * `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
  *
  * Additionally, parse strings of the form `#rgba`, `#rrggbbaa`,
- * `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha to the value
- * specified by the hex digits for `a`. If no alpha component is found
- * in @spec, @alpha is set to 0xffff (for a solid color).
+ * `#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha
+ * to the value specified by the hex digits for `a`. If no alpha
+ * component is found in @spec, @alpha is set to 0xffff (for a
+ * solid color).
  *
- * Return value: %TRUE if parsing of the specifier succeeded, otherwise false.
+ * Return value: %TRUE if parsing of the specifier succeeded,
+ *   otherwise %FALSE
  *
  * Since: 1.46
  */
@@ -320,22 +323,23 @@ pango_color_parse_with_alpha (PangoColor *color,
 
 /**
  * pango_color_parse:
- * @color: (nullable): a `PangoColor` structure in which to store the
- *   result, or %NULL
+ * @color: (nullable): a `PangoColor` structure in which
+ *   to store the result
  * @spec: a string specifying the new color
  *
  * Fill in the fields of a color from a string specification.
  *
- * The string can either
- * one of a large set of standard names. (Taken from the CSS Color
- * [specification](https://www.w3.org/TR/css-color-4/#named-colors), or it can be
- * a value in the form `#rgb`, `#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb`, where
- * `r`, `g` and `b` are hex digits of the red, green, and blue components of the
- * color, respectively. (White in the four forms is `#fff`, `#ffffff`, `#fffffffff`
- * and `#ffffffffffff`.)
+ * The string can either one of a large set of standard names.
+ * (Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors),
+ * or it can be a value in the form `#rgb`, `#rrggbb`,
+ * `#rrrgggbbb` or `#rrrrggggbbbb`, where `r`, `g` and `b`
+ * are hex digits of the red, green, and blue components
+ * of the color, respectively. (White in the four forms is
+ * `#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.)
  *
- * Return value: %TRUE if parsing of the specifier succeeded, otherwise false.
- **/
+ * Return value: %TRUE if parsing of the specifier succeeded,
+ *   otherwise %FALSE
+ */
 gboolean
 pango_color_parse (PangoColor *color,
                    const char *spec)
diff --git a/pango/pango-context.c b/pango/pango-context.c
index d1e447f7..0db09459 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -169,7 +169,7 @@ update_resolved_gravity (PangoContext *context)
 /**
  * pango_context_set_matrix:
  * @context: a `PangoContext`
- * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL to unset any existing
  * matrix. (No matrix set is the same as setting the identity matrix.)
  *
  * Sets the transformation matrix that will be applied when rendering
@@ -1549,7 +1549,7 @@ itemize_state_finish (ItemizeState *state)
  * @length: the number of bytes (not characters) to process
  *   after @start_index. This must be >= 0.
  * @attrs: the set of attributes that apply to @text.
- * @cached_iter: (allow-none): Cached attribute iterator, or %NULL
+ * @cached_iter: (nullable): Cached attribute iterator, or %NULL
  *
  * Like `pango_itemize()`, but with an explicitly specified base direction.
  *
@@ -1627,7 +1627,7 @@ itemize_with_font (PangoContext               *context,
  * @length: the number of bytes (not characters) to process
  *   after @start_index. This must be >= 0.
  * @attrs: the set of attributes that apply to @text.
- * @cached_iter: (allow-none): Cached attribute iterator, or %NULL
+ * @cached_iter: (nullable): Cached attribute iterator, or %NULL
  *
  * Breaks a piece of text into segments with consistent directional
  * level and font.
@@ -1749,9 +1749,9 @@ update_metrics_from_items (PangoFontMetrics *metrics,
 /**
  * pango_context_get_metrics:
  * @context: a `PangoContext`
- * @desc: (allow-none): a `PangoFontDescription` structure. %NULL means that the
+ * @desc: (nullable): a `PangoFontDescription` structure. %NULL means that the
  *   font description from the context will be used.
- * @language: (allow-none): language tag used to determine which script to get
+ * @language: (nullable): language tag used to determine which script to get
  *   the metrics for. %NULL means that the language tag from the context
  *   will be used. If no language tag is set on the context, metrics
  *   for the default language (as determined by [type_func@Pango.Language.get_default]
diff --git a/pango/pango-context.h b/pango/pango-context.h
index 0f775ff4..b44bd623 100644
--- a/pango/pango-context.h
+++ b/pango/pango-context.h
@@ -119,11 +119,6 @@ void                      pango_context_set_round_glyph_positions (PangoContext
 PANGO_AVAILABLE_IN_1_44
 gboolean                  pango_context_get_round_glyph_positions (PangoContext *context);
 
-
-/* Break a string of Unicode characters into segments with
- * consistent shaping/language engine and bidrectional level.
- * Returns a #GList of #PangoItem's
- */
 PANGO_AVAILABLE_IN_ALL
 GList *pango_itemize                (PangoContext      *context,
 				     const char        *text,
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index ebd258b2..0bc6187b 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -109,11 +109,10 @@ pango_coverage_class_init (PangoCoverageClass *class)
  *
  * Create a new `PangoCoverage`
  *
- * Return value: the newly allocated `PangoCoverage`,
- *               initialized to %PANGO_COVERAGE_NONE
- *               with a reference count of one, which
- *               should be freed with pango_coverage_unref().
- **/
+ * Return value: the newly allocated `PangoCoverage`, initialized
+ *   to %PANGO_COVERAGE_NONE with a reference count of one, which
+ *   should be freed with [method@Pango.Coverage.unref].
+ */
 PangoCoverage *
 pango_coverage_new (void)
 {
@@ -127,9 +126,9 @@ pango_coverage_new (void)
  * Copy an existing `PangoCoverage`.
  *
  * Return value: (transfer full): the newly allocated `PangoCoverage`,
- *               with a reference count of one, which should be freed
- *               with pango_coverage_unref().
- **/
+ *   with a reference count of one, which should be freed with
+ *   [method@Pango.Coverage.unref].
+ */
 PangoCoverage *
 pango_coverage_copy (PangoCoverage *coverage)
 {
@@ -143,7 +142,7 @@ pango_coverage_copy (PangoCoverage *coverage)
  * Increase the reference count on the `PangoCoverage` by one.
  *
  * Return value: (transfer full): @coverage
- **/
+ */
 PangoCoverage *
 pango_coverage_ref (PangoCoverage *coverage)
 {
@@ -157,7 +156,7 @@ pango_coverage_ref (PangoCoverage *coverage)
  * Decrease the reference count on the `PangoCoverage` by one.
  *
  * If the result is zero, free the coverage and all associated memory.
- **/
+ */
 void
 pango_coverage_unref (PangoCoverage *coverage)
 {
@@ -172,7 +171,7 @@ pango_coverage_unref (PangoCoverage *coverage)
  * Determine whether a particular index is covered by @coverage.
  *
  * Return value: the coverage level of @coverage for character @index_.
- **/
+ */
 PangoCoverageLevel
 pango_coverage_get (PangoCoverage *coverage,
 		    int            index)
@@ -187,7 +186,7 @@ pango_coverage_get (PangoCoverage *coverage,
  * @level: the new level for @index_
  *
  * Modify a particular index within @coverage
- **/
+ */
 void
 pango_coverage_set (PangoCoverage     *coverage,
 		    int                index,
@@ -206,7 +205,7 @@ pango_coverage_set (PangoCoverage     *coverage,
  * the corresponding index in @other.
  *
  * Deprecated: 1.44: This function does nothing
- **/
+ */
 void
 pango_coverage_max (PangoCoverage *coverage,
 		    PangoCoverage *other)
@@ -223,7 +222,7 @@ pango_coverage_max (PangoCoverage *coverage,
  * Convert a `PangoCoverage` structure into a flat binary format.
  *
  * Deprecated: 1.44: This returns %NULL
- **/
+ */
 void
 pango_coverage_to_bytes (PangoCoverage  *coverage,
 			 guchar        **bytes,
@@ -243,10 +242,10 @@ pango_coverage_to_bytes (PangoCoverage  *coverage,
  * to a `PangoCoverage`.
  *
  * Return value: (transfer full) (nullable): a newly allocated
- *               `PangoCoverage`, or %NULL if the data was invalid.
+ *   `PangoCoverage`, or %NULL if the data was invalid.
  *
  * Deprecated: 1.44: This returns %NULL
- **/
+ */
 PangoCoverage *
 pango_coverage_from_bytes (guchar *bytes,
 			   int     n_bytes)
diff --git a/pango/pango-coverage.h b/pango/pango-coverage.h
index 67fc6306..dbee7e9f 100644
--- a/pango/pango-coverage.h
+++ b/pango/pango-coverage.h
@@ -32,30 +32,34 @@ G_BEGIN_DECLS
 /**
  * PangoCoverage:
  *
- * A #PangoCoverage structure is a map from Unicode characters
- * to #PangoCoverageLevel values.
+ * A `PangoCoverage` structure is a map from Unicode characters
+ * to [enum@Pango.CoverageLevel] values.
  *
- * It is often necessary in Pango to determine if a particular font can
- * represent a particular character, and also how well it can represent
- * that character. The #PangoCoverage is a data structure that is used to
- * represent that information. It is an opaque structure with no public fields.
+ * It is often necessary in Pango to determine if a particular
+ * font can represent a particular character, and also how well
+ * it can represent that character. The `PangoCoverage` is a data
+ * structure that is used to represent that information. It is an
+ * opaque structure with no public fields.
  */
 typedef struct _PangoCoverage PangoCoverage;
 
 /**
  * PangoCoverageLevel:
- * @PANGO_COVERAGE_NONE: The character is not representable with the font.
- * @PANGO_COVERAGE_FALLBACK: The character is represented in a way that may be
- * comprehensible but is not the correct graphical form.
- * For instance, a Hangul character represented as a
- * a sequence of Jamos, or a Latin transliteration of a Cyrillic word.
- * @PANGO_COVERAGE_APPROXIMATE: The character is represented as basically the correct
- * graphical form, but with a stylistic variant inappropriate for
- * the current script.
- * @PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form.
+ * @PANGO_COVERAGE_NONE: The character is not representable with
+ *   the font.
+ * @PANGO_COVERAGE_FALLBACK: The character is represented in a
+ *   way that may be comprehensible but is not the correct
+ *   graphical form. For instance, a Hangul character represented
+ *   as a a sequence of Jamos, or a Latin transliteration of a
+ *   Cyrillic word.
+ * @PANGO_COVERAGE_APPROXIMATE: The character is represented as
+ *   basically the correct graphical form, but with a stylistic
+ *   variant inappropriate for the current script.
+ * @PANGO_COVERAGE_EXACT: The character is represented as the
+ *   correct graphical form.
  *
- * `PangoCoverageLevel` is used to indicate how well a font can represent
- * a particular Unicode character for a particular script.
+ * `PangoCoverageLevel` is used to indicate how well a font can
+ * represent a particular Unicode character for a particular script.
  *
  * Since 1.44, only %PANGO_COVERAGE_NONE and %PANGO_COVERAGE_EXACT
  * will be returned.
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 16b39c3f..b634fd88 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -60,7 +60,7 @@ typedef struct _PangoEngineClass PangoEngineClass;
 /**
  * PangoEngine:
  *
- * #PangoEngine is the base class for all types of language and
+ * `PangoEngine` is the base class for all types of language and
  * script specific engines. It has no functionality by itself.
  *
  * Deprecated: 1.38
@@ -74,7 +74,7 @@ struct _PangoEngine
 /**
  * PangoEngineClass:
  *
- * Class structure for #PangoEngine
+ * Class structure for `PangoEngine`
  *
  * Deprecated: 1.38
  **/
@@ -91,7 +91,7 @@ GType pango_engine_get_type (void) G_GNUC_CONST;
  * PANGO_ENGINE_TYPE_LANG:
  *
  * A string constant defining the engine type for language engines.
- * These engines derive from #PangoEngineLang.
+ * These engines derive from `PangoEngineLang`.
  *
  * Deprecated: 1.38
  */
@@ -109,10 +109,10 @@ typedef struct _PangoEngineLangClass PangoEngineLangClass;
 /**
  * PangoEngineLang:
  *
- * The #PangoEngineLang class is implemented by engines that
+ * The `PangoEngineLang` class is implemented by engines that
  * customize the rendering-system independent part of the
  * Pango pipeline for a particular script or language. For
- * instance, a custom #PangoEngineLang could be provided for
+ * instance, a custom `PangoEngineLang` could be provided for
  * Thai to implement the dictionary-based word boundary
  * lookups needed for that language.
  *
@@ -133,7 +133,7 @@ struct _PangoEngineLang
  * but in newer versions, pango_default_break() is always called and
  * this is called after that to allow tailoring the breaking results.
  *
- * Class structure for #PangoEngineLang
+ * Class structure for `PangoEngineLang`
  *
  * Deprecated: 1.38
  **/
@@ -158,7 +158,7 @@ GType pango_engine_lang_get_type (void) G_GNUC_CONST;
  * PANGO_ENGINE_TYPE_SHAPE:
  *
  * A string constant defining the engine type for shaping engines.
- * These engines derive from #PangoEngineShape.
+ * These engines derive from `PangoEngineShape`.
  *
  * Deprecated: 1.38
  */
@@ -176,13 +176,13 @@ typedef struct _PangoEngineShapeClass PangoEngineShapeClass;
 /**
  * PangoEngineShape:
  *
- * The #PangoEngineShape class is implemented by engines that
+ * The `PangoEngineShape` class is implemented by engines that
  * customize the rendering-system dependent part of the
  * Pango pipeline for a particular script or language.
- * A #PangoEngineShape implementation is then specific to both
+ * A `PangoEngineShape` implementation is then specific to both
  * a particular rendering system or group of rendering systems
  * and to a particular script. For instance, there is one
- * #PangoEngineShape implementation to handle shaping Arabic
+ * `PangoEngineShape` implementation to handle shaping Arabic
  * for Fontconfig-based backends.
  *
  * Deprecated: 1.38
@@ -194,9 +194,9 @@ struct _PangoEngineShape
 
 /**
  * PangoEngineShapeClass:
- * @script_shape: Given a font, a piece of text, and a #PangoAnalysis
+ * @script_shape: Given a font, a piece of text, and a `PangoAnalysis`
  *   structure, converts characters to glyphs and positions the
- *   resulting glyphs. The results are stored in the #PangoGlyphString
+ *   resulting glyphs. The results are stored in the `PangoGlyphString`
  *   that is passed in. (The implementation should resize it
  *   appropriately using pango_glyph_string_set_size()). All fields
  *   of the @log_clusters and @glyphs array must be filled in, with
@@ -205,7 +205,7 @@ struct _PangoEngineShape
  *   using the @log_clusters array. Each input character must occur in one
  *   of the output logical clusters;
  *   if no rendering is desired for a character, this may involve
- *   inserting glyphs with the #PangoGlyph ID #PANGO_GLYPH_EMPTY, which
+ *   inserting glyphs with the `PangoGlyph` ID %PANGO_GLYPH_EMPTY, which
  *   is guaranteed never to render. If the shaping fails for any reason,
  *   the shaper should return with an empty (zero-size) glyph string.
  *   If the shaper has not set the size on the glyph string yet, simply
@@ -215,7 +215,7 @@ struct _PangoEngineShape
  *   implementation simply returns the coverage information for the
  *   font itself unmodified.
  *
- * Class structure for #PangoEngineShape
+ * Class structure for `PangoEngineShape`
  *
  * Deprecated: 1.38
  **/
@@ -247,7 +247,7 @@ typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
 
 /**
  * PangoEngineScriptInfo:
- * @script: a #PangoScript. The value %PANGO_SCRIPT_COMMON has
+ * @script: a `PangoScript`. The value %PANGO_SCRIPT_COMMON has
  * the special meaning here of "all scripts"
  * @langs: a semicolon separated list of languages that this
  * engine handles for this script. This may be empty,
@@ -259,7 +259,7 @@ typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
  * indicates that this engine is specific to all
  * languages for this range.
  *
- * The #PangoEngineScriptInfo structure contains
+ * The `PangoEngineScriptInfo` structure contains
  * information about how the shaper covers a particular script.
  *
  * Deprecated: 1.38
@@ -278,7 +278,7 @@ struct _PangoEngineScriptInfo
  * @scripts: array of scripts this engine supports.
  * @n_scripts: number of items in @scripts.
  *
- * The #PangoEngineInfo structure contains information about a particular
+ * The `PangoEngineInfo` structure contains information about a particular
  * engine. It contains the following fields:
  *
  * Deprecated: 1.38
@@ -307,7 +307,7 @@ void script_engine_list (PangoEngineInfo **engines,
 
 /**
  * script_engine_init: (skip)
- * @module: a #GTypeModule structure used to associate any
+ * @module: a `GTypeModule` structure used to associate any
  *  GObject types created in this module with the module.
  *
  * Do not use.
@@ -374,7 +374,7 @@ prefix ## _register_type (GTypeModule *module)				  \
  * @instance_init: (nullable): Instance initialization function for the new type, or %NULL
  *
  * Outputs the necessary code for GObject type registration for a
- * #PangoEngineLang class defined in a module. Two static symbols
+ * `PangoEngineLang` class defined in a module. Two static symbols
  * are defined.
  *
  * <programlisting>
@@ -405,7 +405,7 @@ prefix ## _register_type (GTypeModule *module)				  \
  * @instance_init: (nullable): Instance initialization function for the new type, or %NULL
  *
  * Outputs the necessary code for GObject type registration for a
- * #PangoEngineShape class defined in a module. Two static symbols
+ * `PangoEngineShape` class defined in a module. Two static symbols
  * are defined.
  *
  * <programlisting>
diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c
index bc18a7da..525dd923 100644
--- a/pango/pango-fontmap.c
+++ b/pango/pango-fontmap.c
@@ -118,8 +118,9 @@ pango_font_map_load_font  (PangoFontMap               *fontmap,
 /**
  * pango_font_map_list_families:
  * @fontmap: a `PangoFontMap`
- * @families: (out) (array length=n_families) (transfer container): location to store a pointer to an array of `PangoFontFamily` *.
- *            This array should be freed with g_free().
+ * @families: (out) (array length=n_families) (transfer container): location to
+ *   store a pointer to an array of `PangoFontFamily` *.
+ *   This array should be freed with g_free().
  * @n_families: (out): location to store the number of elements in @families
  *
  * List all families for a fontmap.
@@ -291,10 +292,10 @@ pango_font_map_real_load_fontset (PangoFontMap               *fontmap,
  * @fontmap: a `PangoFontMap`
  *
  * Returns the render ID for shape engines for this fontmap.
- * See the `render_type` field of #PangoEngineInfo.
+ * See the `render_type` field of `PangoEngineInfo`.
   *
- * Return value: the ID string for shape engines for this fontmap.
- *   Owned by Pango, should not be modified or freed.
+ * Return value (transfer none): the ID string for shape engines
+ *   for this fontmap
  *
  * Since: 1.4
  * Deprecated: 1.38
diff --git a/pango/pango-fontmap.h b/pango/pango-fontmap.h
index 64b04da3..aec18eeb 100644
--- a/pango/pango-fontmap.h
+++ b/pango/pango-fontmap.h
@@ -27,23 +27,6 @@
 
 G_BEGIN_DECLS
 
-/**
- * PANGO_TYPE_FONT_MAP:
- *
- * The #GObject type for #PangoFontMap.
- */
-/**
- * PANGO_FONT_MAP:
- * @object: a #GObject.
- *
- * Casts a #GObject to a #PangoFontMap.
- */
-/**
- * PANGO_IS_FONT_MAP:
- * @object: a #GObject.
- *
- * Returns: %TRUE if @object is a #PangoFontMap.
- */
 #define PANGO_TYPE_FONT_MAP              (pango_font_map_get_type ())
 #define PANGO_FONT_MAP(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_MAP, PangoFontMap))
 #define PANGO_IS_FONT_MAP(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_MAP))
@@ -70,7 +53,7 @@ struct _PangoFontMap
 
 /**
  * PangoFontMapClass:
- * @parent_class: parent #GObjectClass.
+ * @parent_class: parent `GObjectClass`
  * @load_font: a function to load a font with a given description. See
  * pango_font_map_load_font().
  * @list_families: A function to list available font families. See
@@ -83,8 +66,8 @@ struct _PangoFontMap
  * See pango_font_map_get_serial().
  * @changed: See pango_font_map_changed()
  *
- * The #PangoFontMapClass structure holds the virtual functions for
- * a particular #PangoFontMap implementation.
+ * The `PangoFontMapClass` structure holds the virtual functions for
+ * a particular `PangoFontMap` implementation.
  */
 struct _PangoFontMapClass
 {
diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index 6f3bdcbf..a7cda5ad 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -55,9 +55,8 @@ pango_fontset_class_init (PangoFontsetClass *class)
  * Returns the font in the fontset that contains the best glyph for a
  * Unicode character.
  *
- * Return value: (transfer full): a `PangoFont`. The caller must call
- *          g_object_unref() when finished with the font.
- **/
+ * Return value: (transfer full): a `PangoFont`
+ */
 PangoFont *
 pango_fontset_get_font (PangoFontset  *fontset,
 			guint          wc)
@@ -70,13 +69,12 @@ pango_fontset_get_font (PangoFontset  *fontset,
 
 /**
  * pango_fontset_get_metrics:
- * @fontset: a #PangoFontset
+ * @fontset: a `PangoFontset`
  *
  * Get overall metric information for the fonts in the fontset.
  *
- * Return value: a #PangoFontMetrics object. The caller must call pango_font_metrics_unref()
- *   when finished using the object.
- **/
+ * Return value: a `PangoFontMetrics` object
+ */
 PangoFontMetrics *
 pango_fontset_get_metrics (PangoFontset  *fontset)
 {
@@ -97,7 +95,7 @@ pango_fontset_get_metrics (PangoFontset  *fontset)
  * If @func returns %TRUE, that stops the iteration.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_fontset_foreach (PangoFontset           *fontset,
 		       PangoFontsetForeachFunc func,
@@ -238,9 +236,8 @@ struct _PangoFontsetSimpleClass
  *
  * Creates a new `PangoFontsetSimple` for the given language.
  *
- * Return value: the newly allocated `PangoFontsetSimple`, which should
- *               be freed with g_object_unref().
- **/
+ * Return value: the newly allocated `PangoFontsetSimple`
+ */
 PangoFontsetSimple *
 pango_fontset_simple_new (PangoLanguage *language)
 {
@@ -307,7 +304,7 @@ pango_fontset_simple_finalize (GObject *object)
  * @font: a `PangoFont`.
  *
  * Adds a font to the fontset.
- **/
+ */
 void
 pango_fontset_simple_append (PangoFontsetSimple *fontset,
 			     PangoFont          *font)
@@ -322,8 +319,8 @@ pango_fontset_simple_append (PangoFontsetSimple *fontset,
  *
  * Returns the number of fonts in the fontset.
  *
- * Return value: the size of @fontset.
- **/
+ * Return value: the size of @fontset
+ */
 int
 pango_fontset_simple_size (PangoFontsetSimple *fontset)
 {
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index 2b2018dd..33ca87eb 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -33,11 +33,6 @@ G_BEGIN_DECLS
  * PangoFontset
  */
 
-/**
- * PANGO_TYPE_FONTSET:
- *
- * The #GObject type for #PangoFontset.
- */
 #define PANGO_TYPE_FONTSET              (pango_fontset_get_type ())
 #define PANGO_FONTSET(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET, PangoFontset))
 #define PANGO_IS_FONTSET(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONTSET))
@@ -86,7 +81,7 @@ struct _PangoFontset
 
 /**
  * PangoFontsetClass:
- * @parent_class: parent #GObjectClass.
+ * @parent_class: parent `GObjectClass`
  * @get_font: a function to get the font in the fontset that contains the
  * best glyph for the given Unicode character; see pango_fontset_get_font().
  * @get_metrics: a function to get overall metric information for the fonts
@@ -95,8 +90,8 @@ struct _PangoFontset
  * @foreach: a function to loop over the fonts in the fontset. See
  * pango_fontset_foreach().
  *
- * The #PangoFontsetClass structure holds the virtual functions for
- * a particular #PangoFontset implementation.
+ * The `PangoFontsetClass` structure holds the virtual functions for
+ * a particular `PangoFontset` implementation.
  */
 struct _PangoFontsetClass
 {
@@ -123,11 +118,6 @@ struct _PangoFontsetClass
 };
 
 /**
- * PANGO_TYPE_FONTSET_SIMPLE:
- *
- * The #GObject type for #PangoFontsetSimple.
- */
-/**
  * PangoFontsetSimple:
  *
  * `PangoFontsetSimple` is a implementation of the abstract
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 08bb8762..cbda8f09 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -32,27 +32,27 @@
  * pango_glyph_item_split:
  * @orig: a `PangoItem`
  * @text: text to which positions in @orig apply
- * @split_index: byte index of position to split item, relative to the start of the item
+ * @split_index: byte index of position to split item, relative to the
+ *   start of the item
  *
  * Modifies @orig to cover only the text after @split_index, and
  * returns a new item that covers the text before @split_index that
  * used to be in @orig.
  *
- * You can think of @split_index as the length of
- * the returned item. @split_index may not be 0, and it may not be
- * greater than or equal to the length of @orig (that is, there must
- * be at least one byte assigned to each item, you can't create a
- * zero-length item).
+ * You can think of @split_index as the length of the returned item.
+ * @split_index may not be 0, and it may not be greater than or equal
+ * to the length of @orig (that is, there must be at least one byte
+ * assigned to each item, you can't create a zero-length item).
  *
  * This function is similar in function to pango_item_split() (and uses
  * it internally.)
  *
  * Return value: the newly allocated item representing text before
- *               @split_index, which should be freed
- *               with pango_glyph_item_free().
+ *   @split_index, which should be freed
+ *   with pango_glyph_item_free().
  *
  * Since: 1.2
- **/
+ */
 PangoGlyphItem *
 pango_glyph_item_split (PangoGlyphItem *orig,
 			const char     *text,
@@ -134,16 +134,16 @@ pango_glyph_item_split (PangoGlyphItem *orig,
 
 /**
  * pango_glyph_item_copy:
- * @orig: (nullable): a `PangoGlyphItem`, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`
  *
  * Make a deep copy of an existing `PangoGlyphItem` structure.
  *
- * Return value: (nullable): the newly allocated `PangoGlyphItem`, which should
- *               be freed with pango_glyph_item_free(), or %NULL
- *               if @orig was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphItem`,
+ *   which should be freed with pango_glyph_item_free(), or %NULL
+ *   if @orig was %NULL.
  *
  * Since: 1.20
- **/
+ */
 PangoGlyphItem *
 pango_glyph_item_copy  (PangoGlyphItem *orig)
 {
@@ -162,12 +162,12 @@ pango_glyph_item_copy  (PangoGlyphItem *orig)
 
 /**
  * pango_glyph_item_free:
- * @glyph_item: (nullable): a `PangoGlyphItem`, may be %NULL
+ * @glyph_item: (nullable): a `PangoGlyphItem`
  *
  * Frees a `PangoGlyphItem` and resources to which it points.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_glyph_item_free  (PangoGlyphItem *glyph_item)
 {
@@ -189,7 +189,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
 
 /**
  * pango_glyph_item_iter_copy:
- * @orig: (nullable): a `PangoGlyphItem`Iter, may be %NULL
+ * @orig: (nullable): a `PangoGlyphItem`Iter
  *
  * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
  *
@@ -198,7 +198,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
  *   if @orig was %NULL.
  *
  * Since: 1.22
- **/
+ */
 PangoGlyphItemIter *
 pango_glyph_item_iter_copy  (PangoGlyphItemIter *orig)
 {
@@ -216,12 +216,12 @@ pango_glyph_item_iter_copy  (PangoGlyphItemIter *orig)
 
 /**
  * pango_glyph_item_iter_free:
- * @iter: (nullable): a `PangoGlyphItemIter`, may be %NULL
+ * @iter: (nullable): a `PangoGlyphItemIter`
  *
  * Frees a `PangoGlyphItem`Iter.
  *
  * Since: 1.22
- **/
+ */
 void
 pango_glyph_item_iter_free  (PangoGlyphItemIter *iter)
 {
@@ -247,7 +247,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItemIter, pango_glyph_item_iter,
  *   %FALSE if we were already on the  last cluster.
  *
  * Since: 1.22
- **/
+ */
 gboolean
 pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
 {
@@ -337,7 +337,7 @@ pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter)
  *   %FALSE if we were already on the first cluster.
  *
  * Since: 1.22
- **/
+ */
 gboolean
 pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
 {
@@ -433,7 +433,7 @@ pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter)
  * Return value: %FALSE if there are no clusters in the glyph item
  *
  * Since: 1.22
- **/
+ */
 gboolean
 pango_glyph_item_iter_init_start (PangoGlyphItemIter  *iter,
 				  PangoGlyphItem      *glyph_item,
@@ -472,7 +472,7 @@ pango_glyph_item_iter_init_start (PangoGlyphItemIter  *iter,
  * Return value: %FALSE if there are no clusters in the glyph item
  *
  * Since: 1.22
- **/
+ */
 gboolean
 pango_glyph_item_iter_init_end (PangoGlyphItemIter  *iter,
 				PangoGlyphItem      *glyph_item,
@@ -514,7 +514,7 @@ append_attrs (PangoGlyphItem *glyph_item,
     g_slist_concat (glyph_item->item->analysis.extra_attrs, attrs);
 }
 
-/* Make a deep copy of a #GSList of PangoAttribute
+/* Make a deep copy of a GSList of PangoAttribute
  */
 static GSList *
 attr_slist_copy (GSList *attrs)
@@ -564,11 +564,10 @@ split_before_cluster_start (ApplyAttrsState *state)
  * Splits a shaped item (`PangoGlyphItem`) into multiple items based
  * on an attribute list.
  *
- * The idea is that if you have attributes
- * that don't affect shaping, such as color or underline, to avoid
- * affecting shaping, you filter them out ([method@Pango.AttrList.filter]),
- * apply the shaping process and then reapply them to the result using
- * this function.
+ * The idea is that if you have attributes that don't affect shaping,
+ * such as color or underline, to avoid affecting shaping, you filter
+ * them out ([method@Pango.AttrList.filter]), apply the shaping process
+ * and then reapply them to the result using this function.
  *
  * All attributes that start or end inside a cluster are applied
  * to that cluster; for instance, if half of a cluster is underlined
@@ -586,7 +585,7 @@ split_before_cluster_start (ApplyAttrsState *state)
  *   g_slist_free().
  *
  * Since: 1.2
- **/
+ */
 GSList *
 pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
 			      const char       *text,
@@ -721,7 +720,7 @@ pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
  * @glyph_item: a `PangoGlyphItem`
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
- *    start of @text)
+ *   start of @text)
  * @log_attrs: (array): logical attributes for the item
  *   (the first logical attribute refers to the position
  *   before the first character in the item)
@@ -803,22 +802,21 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
  * @glyph_item: a `PangoGlyphItem`
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
- *    start of @text)
+ *   start of @text)
  * @logical_widths: (array): an array whose length is the number of
- *                  characters in glyph_item (equal to
- *                  glyph_item->item->num_chars) to be filled in with
- *                  the resulting character widths.
+ *   characters in glyph_item (equal to glyph_item->item->num_chars)
+ *   to be filled in with the resulting character widths.
  *
- * Given a `PangoGlyphItem` and the corresponding text, determine the width
- * corresponding to each character.
+ * Given a `PangoGlyphItem` and the corresponding text, determine the
+ * width corresponding to each character.
  *
- * When multiple characters compose a single cluster, the width of the entire
- * cluster is divided equally among the characters.
+ * When multiple characters compose a single cluster, the width of the
+ * entire cluster is divided equally among the characters.
  *
  * See also [method@Pango.GlyphString.get_logical_widths].
  *
  * Since: 1.26
- **/
+ */
 void
 pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
 				     const char     *text,
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 8a1dbff4..6c2f9249 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -49,11 +49,6 @@ struct _PangoGlyphItem
   PangoGlyphString *glyphs;
 };
 
-/**
- * PANGO_TYPE_GLYPH_ITEM:
- *
- * The #GObject type for #PangoGlyphItem.
- */
 #define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
 
 PANGO_AVAILABLE_IN_ALL
@@ -144,13 +139,6 @@ struct _PangoGlyphItemIter
   int end_char;
 };
 
-/**
- * PANGO_TYPE_GLYPH_ITEM_ITER:
- *
- * The #GObject type for #PangoGlyphItemIter.
- *
- * Since: 1.22
- */
 #define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
 
 PANGO_AVAILABLE_IN_1_22
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 7c1bf7b5..abab5572 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -109,9 +109,9 @@ struct _PangoGlyphInfo
  * PangoGlyphString:
  * @num_glyphs: number of the glyphs in this glyph string.
  * @glyphs: (array length=num_glyphs): array of glyph information
- *          for the glyph string.
+ *   for the glyph string.
  * @log_clusters: logical cluster info, indexed by the byte index
- *                within the text corresponding to the glyph string.
+ *   within the text corresponding to the glyph string.
  *
  * A `PangoGlyphString` is used to store strings of glyphs with geometry
  * and visual attribute information.
@@ -129,11 +129,6 @@ struct _PangoGlyphString {
   gint space;
 };
 
-/**
- * PANGO_TYPE_GLYPH_STRING:
- *
- * The #GObject type for #PangoGlyphString.
- */
 #define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
 
 PANGO_AVAILABLE_IN_ALL
@@ -207,13 +202,13 @@ void pango_shape_full (const char          *item_text,
  * PangoShapeFlags:
  * @PANGO_SHAPE_NONE: Default value.
  * @PANGO_SHAPE_ROUND_POSITIONS: Round glyph positions
- *     and widths to whole device units. This option should
- *     be set if the target renderer can't do subpixel
- *     positioning of glyphs.
+ *   and widths to whole device units. This option should
+ *   be set if the target renderer can't do subpixel
+ *   positioning of glyphs.
  *
  * Flags influencing the shaping process.
  *
- * `PangoShapeFlags` can be passed to pango_shape_with_flags().
+ * `PangoShapeFlags` can be passed to [func@Pango.shape_with_flags].
  */
 typedef enum {
   PANGO_SHAPE_NONE            = 0,
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index a21749b6..f01a7349 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -29,7 +29,7 @@
  * pango_gravity_to_rotation:
  * @gravity: gravity to query, should not be %PANGO_GRAVITY_AUTO
  *
- * Converts a #PangoGravity value to its natural rotation in radians.
+ * Converts a `PangoGravity` value to its natural rotation in radians.
  *
  * Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians.
  * So, to call [method@Pango.Matrix,rotate] with the output of this function
@@ -232,7 +232,7 @@ get_script_properties (PangoScript script)
 
 /**
  * pango_gravity_get_for_script:
- * @script: #PangoScript to query
+ * @script: `PangoScript` to query
  * @base_gravity: base gravity of the paragraph
  * @hint: orientation hint
  *
@@ -245,7 +245,7 @@ get_script_properties (PangoScript script)
  * pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in.
  *
  * Return value: resolved gravity suitable to use for a run of text
- * with @script.
+ * with @script
  *
  * Since: 1.16
  */
@@ -265,7 +265,7 @@ pango_gravity_get_for_script (PangoScript      script,
 
 /**
  * pango_gravity_get_for_script_and_width:
- * @script: #PangoScript to query
+ * @script: `PangoScript` to query
  * @wide: %TRUE for wide characters as returned by g_unichar_iswide()
  * @base_gravity: base gravity of the paragraph
  * @hint: orientation hint
diff --git a/pango/pango-gravity.h b/pango/pango-gravity.h
index a3aa7f19..178b018f 100644
--- a/pango/pango-gravity.h
+++ b/pango/pango-gravity.h
@@ -61,13 +61,13 @@ typedef enum {
 /**
  * PangoGravityHint:
  * @PANGO_GRAVITY_HINT_NATURAL: scripts will take their natural gravity based
- * on the base gravity and the script.  This is the default.
+ *   on the base gravity and the script.  This is the default.
  * @PANGO_GRAVITY_HINT_STRONG: always use the base gravity set, regardless of
- * the script.
+ *   the script.
  * @PANGO_GRAVITY_HINT_LINE: for scripts not in their natural direction (eg.
- * Latin in East gravity), choose per-script gravity such that every script
- * respects the line progression.  This means, Latin and Arabic will take
- * opposite gravities and both flow top-to-bottom for example.
+ *   Latin in East gravity), choose per-script gravity such that every script
+ *   respects the line progression. This means, Latin and Arabic will take
+ *   opposite gravities and both flow top-to-bottom for example.
  *
  * `PangoGravityHint` defines how horizontal scripts should behave in a
  * vertical context.
@@ -77,7 +77,7 @@ typedef enum {
  * See also [enum@Pango.Gravity]
  *
  * Since: 1.16
- **/
+ */
 typedef enum {
   PANGO_GRAVITY_HINT_NATURAL,
   PANGO_GRAVITY_HINT_STRONG,
@@ -86,29 +86,30 @@ typedef enum {
 
 /**
  * PANGO_GRAVITY_IS_VERTICAL:
- * @gravity: the #PangoGravity to check
+ * @gravity: the `PangoGravity` to check
  *
- * Whether a #PangoGravity represents vertical writing directions.
+ * Whether a `PangoGravity` represents vertical writing directions.
  *
  * Returns: %TRUE if @gravity is %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST,
- *          %FALSE otherwise.
+ *   %FALSE otherwise.
  *
  * Since: 1.16
- **/
+ */
 #define PANGO_GRAVITY_IS_VERTICAL(gravity) \
 	((gravity) == PANGO_GRAVITY_EAST || (gravity) == PANGO_GRAVITY_WEST)
 
 /**
  * PANGO_GRAVITY_IS_IMPROPER:
- * @gravity: the #PangoGravity to check
+ * @gravity: the `PangoGravity` to check
  *
- * Whether a #PangoGravity represents a gravity that results in reversal of text direction.
+ * Whether a `PangoGravity` represents a gravity that results in reversal
+ * of text direction.
  *
  * Returns: %TRUE if @gravity is %PANGO_GRAVITY_WEST or %PANGO_GRAVITY_NORTH,
- *          %FALSE otherwise.
+ *   %FALSE otherwise.
  *
  * Since: 1.32
- **/
+ */
 #define PANGO_GRAVITY_IS_IMPROPER(gravity) \
 	((gravity) == PANGO_GRAVITY_WEST || (gravity) == PANGO_GRAVITY_NORTH)
 
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 2f79acec..355b9b99 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -279,8 +279,7 @@ _pango_get_lc_ctype (void)
  *
  * Note that the default language can change over the life of an application.
  *
- * Return value: (transfer none): the default language as a
- *               `PangoLanguage`, must not be freed.
+ * Return value: (transfer none): the default language as a `PangoLanguage`
  *
  * Since: 1.16
  **/
@@ -306,7 +305,7 @@ pango_language_get_default (void)
 
 /**
  * pango_language_from_string:
- * @language: (allow-none): a string representing a language tag, or %NULL
+ * @language: (nullable): a string representing a language tag, or %NULL
  *
  * Convert a language tag to a `PangoLanguage`.
  *
@@ -318,12 +317,11 @@ pango_language_get_default (void)
  * lowercase, mapping '_' to '-', and stripping all characters other
  * than letters and '-'.
  *
- * Use [type_func@Pango.Language.get_default] if you want to get the `PangoLanguage`
- * for the current locale of the process.
+ * Use [type_func@Pango.Language.get_default] if you want to get the
+ * `PangoLanguage` for the current locale of the process.
  *
  * Return value: (transfer none) (nullable): an opaque pointer to a
- *   `PangoLanguage` structure, or %NULL if @language was %NULL. The
- *   returned pointer will be valid forever after, and should not be freed.
+ *   `PangoLanguage` structure, or %NULL if @language was %NULL
  */
 PangoLanguage *
 pango_language_from_string (const char *language)
@@ -376,8 +374,7 @@ out:
  *
  * Gets the RFC-3066 format string representing the given language tag.
  *
- * Returns: a string representing the language tag. This is owned by
- *   Pango and should not be freed.
+ * Returns (transfer none): a string representing the language tag
  */
 const char *
 (pango_language_to_string) (PangoLanguage *language)
@@ -397,12 +394,11 @@ const char *
  * Checks if a language tag matches one of the elements in a list of
  * language ranges.
  *
- * A language tag is considered to match a range
- * in the list if the range is '*', the range is exactly the tag,
- * or the range is a prefix of the tag, and the character after it
- * in the tag is '-'.
+ * A language tag is considered to match a range in the list if the
+ * range is '*', the range is exactly the tag, or the range is a prefix
+ * of the tag, and the character after it in the tag is '-'.
  *
- * Return value: %TRUE if a match was found.
+ * Return value: %TRUE if a match was found
  */
 gboolean
 pango_language_matches (PangoLanguage *language,
@@ -585,8 +581,7 @@ static const LangInfo lang_texts[] = {
  * pango_language_get_sample_string (pango_language_from_string ("xx"))
  * ```
  *
- * Return value: the sample string. This value is owned by Pango
- *   and should not be freed.
+ * Return value: (transfer none): the sample string
  */
 const char *
 pango_language_get_sample_string (PangoLanguage *language)
@@ -618,9 +613,9 @@ pango_language_get_sample_string (PangoLanguage *language)
 
 /**
  * pango_language_get_scripts:
- * @language: (allow-none): a `PangoLanguage`, or %NULL
- * @num_scripts: (out caller-allocates) (allow-none): location to
- *   return number of scripts, or %NULL
+ * @language: (nullable): a `PangoLanguage`
+ * @num_scripts: (out caller-allocates) (optional): location to
+ *   return number of scripts
  *
  * Determines the scripts used to to write @language.
  *
@@ -639,19 +634,18 @@ pango_language_get_sample_string (PangoLanguage *language)
  * though, except that it is positive if the return value is not
  * %NULL, and it is a small number.
  *
- * The [method@Pango.Language.includes_script] function uses this function
- * internally.
+ * The [method@Pango.Language.includes_script] function uses this
+ * function internally.
  *
  * Note: while the return value is declared as `PangoScript`, the
  * returned values are from the `GUnicodeScript` enumeration, which
  * may have more values. Callers need to handle unknown values.
  *
- * Return value: (array length=num_scripts) (nullable): An array of
- *   `PangoScript` values, with the number of entries in the array
- *   stored in @num_scripts, or %NULL if Pango does not have any
- *   information about this particular language tag (also the case
- *   if @language is %NULL). The returned array is owned by Pango
- *   and should not be modified or freed.
+ * Return value: (transfer none) (array length=num_scripts) (nullable):
+ *   An array of `PangoScript` values, with the number of entries in
+ *   the array stored in @num_scripts, or %NULL if Pango does not have
+ *   any information about this particular language tag (also the case
+ *   if @language is %NULL).
  *
  * Since: 1.22
  */
@@ -694,10 +688,11 @@ pango_language_get_scripts (PangoLanguage *language,
  * @script: a `PangoScript`
  *
  * Determines if @script is one of the scripts used to
- * write @language. The returned value is conservative;
- * if nothing is known about the language tag @language,
- * %TRUE will be returned, since, as far as Pango knows,
- * @script might be used to write @language.
+ * write @language.
+ *
+ * The returned value is conservative; if nothing is known about
+ * the language tag @language, %TRUE will be returned, since, as
+ * far as Pango knows, @script might be used to write @language.
  *
  * This routine is used in Pango's itemization process when
  * determining if a supplied language tag is relevant to
@@ -843,17 +838,18 @@ out:
  *
  * Returns the list of languages that the user prefers.
  *
- * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` environment
- * variables, in order of preference. Note that this list does not necessarily
- * include the language returned by [type_func@Pango.Language.get_default].
+ * The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE`
+ * environment variables, in order of preference. Note that this
+ * list does not necessarily include the language returned by
+ * [type_func@Pango.Language.get_default].
  *
  * When choosing language-specific resources, such as the sample
- * text returned by [method@Pango.Language.get_sample_string], you should
- * first try the default language, followed by the languages returned
- * by this function.
+ * text returned by [method@Pango.Language.get_sample_string],
+ * you should first try the default language, followed by the
+ * languages returned by this function.
  *
- * Returns: (transfer none) (nullable): a %NULL-terminated array of
- *   `PangoLanguage`*
+ * Returns: (transfer none) (nullable): a %NULL-terminated array
+ *   of `PangoLanguage`*
  *
  * Since: 1.48
  */
@@ -872,9 +868,10 @@ pango_language_get_preferred (void)
  *
  * Finds a language tag that is reasonably representative of @script.
  *
- * The language will usually be the most widely spoken or used language written
- * in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC
- * is ru (Russian), the sample language for %PANGO_SCRIPT_ARABIC is ar.
+ * The language will usually be the most widely spoken or used language
+ * written in that script: for instance, the sample language for
+ * %PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for
+ * %PANGO_SCRIPT_ARABIC is ar.
  *
  * For some scripts, no sample language will be returned because
  * there is no language that is sufficiently representative. The
@@ -900,7 +897,7 @@ pango_language_get_preferred (void)
  * context language is not feasible.
  *
  * Return value: (nullable): a `PangoLanguage` that is representative
- * of the script, or %NULL if no such language exists.
+ *   of the script
  *
  * Since: 1.4
  */
diff --git a/pango/pango-language.h b/pango/pango-language.h
index 16e6512c..b000c5b8 100644
--- a/pango/pango-language.h
+++ b/pango/pango-language.h
@@ -31,11 +31,6 @@ G_BEGIN_DECLS
 
 typedef struct _PangoLanguage PangoLanguage;
 
-/**
- * PANGO_TYPE_LANGUAGE:
- *
- * The #GObject type for #PangoLanguage.
- */
 #define PANGO_TYPE_LANGUAGE (pango_language_get_type ())
 
 PANGO_AVAILABLE_IN_ALL
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index ca70ebe5..1ac44986 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -256,8 +256,7 @@ pango_layout_finalize (GObject *object)
  * Create a new `PangoLayout` object with attributes initialized to
  * default values for a particular `PangoContext`.
  *
- * Return value: the newly allocated `PangoLayout`, with a reference
- *   count of one, which should be freed with g_object_unref().
+ * Return value: the newly allocated `PangoLayout`
  */
 PangoLayout *
 pango_layout_new (PangoContext *context)
@@ -284,9 +283,7 @@ pango_layout_new (PangoContext *context)
  * The attribute list, tab array, and text from the original layout
  * are all copied by value.
  *
- * Return value: (transfer full): the newly allocated `PangoLayout`,
- *   with a reference count of one, which should be freed
- *   with g_object_unref().
+ * Return value: (transfer full): the newly allocated `PangoLayout`
  */
 PangoLayout*
 pango_layout_copy (PangoLayout *src)
@@ -321,9 +318,7 @@ pango_layout_copy (PangoLayout *src)
  *
  * Retrieves the `PangoContext` used for this layout.
  *
- * Return value: (transfer none): the `PangoContext` for the layout.
- *   This does not have an additional refcount added, so if you want to
- *   keep a copy of this around, you must reference it yourself.
+ * Return value: (transfer none): the `PangoContext` for the layout
  */
 PangoContext *
 pango_layout_get_context (PangoLayout *layout)
@@ -507,7 +502,7 @@ pango_layout_get_wrap (PangoLayout *layout)
  * to be wrapped.
  *
  * Return value: %TRUE if any paragraphs had to be wrapped, %FALSE
- *   otherwise.
+ *   otherwise
  *
  * Since: 1.16
  */
@@ -523,8 +518,8 @@ pango_layout_is_wrapped (PangoLayout *layout)
 
 /**
  * pango_layout_set_indent:
- * @layout: a `PangoLayout`.
- * @indent: the amount by which to indent.
+ * @layout: a `PangoLayout`
+ * @indent: the amount by which to indent
  *
  * Sets the width in Pango units to indent each paragraph.
  *
@@ -556,7 +551,7 @@ pango_layout_set_indent (PangoLayout *layout,
  *
  * A negative value indicates a hanging indentation.
  *
- * Return value: the indent in Pango units.
+ * Return value: the indent in Pango units
  */
 int
 pango_layout_get_indent (PangoLayout *layout)
@@ -567,7 +562,7 @@ pango_layout_get_indent (PangoLayout *layout)
 
 /**
  * pango_layout_set_spacing:
- * @layout: a `PangoLayout`.
+ * @layout: a `PangoLayout`
  * @spacing: the amount of spacing
  *
  * Sets the amount of spacing in Pango unit between
@@ -575,7 +570,7 @@ pango_layout_get_indent (PangoLayout *layout)
  *
  * When placing lines with spacing, Pango arranges things so that
  *
- * line2.top = line1.bottom + spacing
+ *     line2.top = line1.bottom + spacing
  *
  * Note: Since 1.44, Pango defaults to using the line height
  * (as determined by the font) for placing lines. The @spacing
@@ -602,7 +597,7 @@ pango_layout_set_spacing (PangoLayout *layout,
  *
  * Gets the amount of spacing between the lines of the layout.
  *
- * Return value: the spacing in Pango units.
+ * Return value: the spacing in Pango units
  */
 int
 pango_layout_get_spacing (PangoLayout *layout)
@@ -665,9 +660,10 @@ pango_layout_get_line_spacing (PangoLayout *layout)
 /**
  * pango_layout_set_attributes:
  * @layout: a `PangoLayout`
- * @attrs: (allow-none) (transfer none): a #PangoAttrList, can be %NULL
+ * @attrs: (nullable) (transfer none): a `PangoAttrList`
  *
  * Sets the text attributes for a layout object.
+ *
  * References @attrs, so the caller can unref its reference.
  */
 void
@@ -708,8 +704,7 @@ pango_layout_set_attributes (PangoLayout   *layout,
  *
  * Gets the attribute list for the layout, if any.
  *
- * Return value: (transfer none) (nullable): a `PangoAttrList` or %NULL
- *   if none was set.
+ * Return value: (transfer none) (nullable): a `PangoAttrList`
  */
 PangoAttrList*
 pango_layout_get_attributes (PangoLayout *layout)
@@ -722,13 +717,13 @@ pango_layout_get_attributes (PangoLayout *layout)
 /**
  * pango_layout_set_font_description:
  * @layout: a `PangoLayout`
- * @desc: (allow-none): the new `PangoFontDescription`, or %NULL
+ * @desc: (nullable): the new `PangoFontDescription`
  *   to unset the current font description
  *
  * Sets the default font description for the layout.
  *
- * If no font description is set on the layout, the font description from
- * the layout's context is used.
+ * If no font description is set on the layout, the
+ * font description from the layout's context is used.
  */
 void
 pango_layout_set_font_description (PangoLayout                *layout,
@@ -755,10 +750,11 @@ pango_layout_set_font_description (PangoLayout                *layout,
  *
  * Gets the font description for the layout, if any.
  *
- * Return value: (nullable): a pointer to the layout's font
- *   description, or %NULL if the font description from the layout's
- *   context is inherited. This value is owned by the layout and must
- *   not be modified or freed.
+ * Return value: (transfer none) (nullable): a pointer to the
+ *   layout's font description, or %NULL if the font description
+ *   from the layout's context is inherited.
+ *   This value is owned by the layout and must not be modified
+ *   or freed.
  *
  * Since: 1.8
  */
@@ -773,7 +769,7 @@ pango_layout_get_font_description (PangoLayout *layout)
 /**
  * pango_layout_set_justify:
  * @layout: a `PangoLayout`
- * @justify: whether the lines in the layout should be justified.
+ * @justify: whether the lines in the layout should be justified
  *
  * Sets whether each complete line should be stretched to fill the
  * entire width of the layout.
@@ -807,7 +803,7 @@ pango_layout_set_justify (PangoLayout *layout,
  * Gets whether each complete line should be stretched to fill the entire
  * width of the layout.
  *
- * Return value: the justify.
+ * Return value: the justify value
  */
 gboolean
 pango_layout_get_justify (PangoLayout *layout)
@@ -820,7 +816,7 @@ pango_layout_get_justify (PangoLayout *layout)
  * pango_layout_set_auto_dir:
  * @layout: a `PangoLayout`
  * @auto_dir: if %TRUE, compute the bidirectional base direction
- *   from the layout's contents.
+ *   from the layout's contents
  *
  * Sets whether to calculate the base direction
  * for the layout according to its contents.
@@ -866,7 +862,7 @@ pango_layout_set_auto_dir (PangoLayout *layout,
  * See [method@Pango.Layout.set_auto_dir].
  *
  * Return value: %TRUE if the bidirectional base direction
- *   is computed from the layout's contents, %FALSE otherwise.
+ *   is computed from the layout's contents, %FALSE otherwise
  *
  * Since: 1.4
  */
@@ -906,7 +902,7 @@ pango_layout_set_alignment (PangoLayout   *layout,
  * Gets the alignment for the layout: how partial lines are
  * positioned within the horizontal space available.
  *
- * Return value: the alignment.
+ * Return value: the alignment
  */
 PangoAlignment
 pango_layout_get_alignment (PangoLayout *layout)
@@ -919,7 +915,7 @@ pango_layout_get_alignment (PangoLayout *layout)
 /**
  * pango_layout_set_tabs:
  * @layout: a `PangoLayout`
- * @tabs: (allow-none): a `PangoTabArray`, or %NULL
+ * @tabs: (nullable): a `PangoTabArray`
  *
  * Sets the tabs to use for @layout, overriding the default tabs.
  *
@@ -956,8 +952,7 @@ pango_layout_set_tabs (PangoLayout   *layout,
  *
  * The return value should be freed with [method@Pango.TabArray.free].
  *
- * Return value: (nullable): a copy of the tabs for this layout,
- * or %NULL.
+ * Return value: (nullable): a copy of the tabs for this layout
  */
 PangoTabArray*
 pango_layout_get_tabs (PangoLayout *layout)
@@ -1005,8 +1000,8 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout,
  *
  * See [method@Pango.Layout.set_single_paragraph_mode].
  *
- * Return value: %TRUE if the layout does not break paragraphs at
- * paragraph separator characters, %FALSE otherwise.
+ * Return value: %TRUE if the layout does not break paragraphs
+ *   at paragraph separator characters, %FALSE otherwise
  */
 gboolean
 pango_layout_get_single_paragraph_mode (PangoLayout *layout)
@@ -1032,6 +1027,7 @@ pango_layout_get_single_paragraph_mode (PangoLayout *layout)
  * force it to be layed out in multiple paragraphs, then whether
  * each paragraph is ellipsized separately or the entire layout
  * is ellipsized as a whole depends on the set height of the layout.
+ *
  * See [method@Pango.Layout.set_height] for details.
  *
  * Since: 1.6
@@ -1062,7 +1058,7 @@ pango_layout_set_ellipsize (PangoLayout        *layout,
  * Use [method@Pango.Layout.is_ellipsized] to query whether any
  * paragraphs were actually ellipsized.
  *
- * Return value: the current ellipsization mode for @layout.
+ * Return value: the current ellipsization mode for @layout
  *
  * Since: 1.6
  */
@@ -1085,8 +1081,8 @@ pango_layout_get_ellipsize (PangoLayout *layout)
  * and there are paragraphs exceeding that width that have to be
  * ellipsized.
  *
- * Return value: %TRUE if any paragraphs had to be ellipsized, %FALSE
- * otherwise.
+ * Return value: %TRUE if any paragraphs had to be ellipsized,
+ *   %FALSE otherwise
  *
  * Since: 1.16
  */
@@ -1187,11 +1183,12 @@ pango_layout_set_text (PangoLayout *layout,
  * pango_layout_get_text:
  * @layout: a `PangoLayout`
  *
- * Gets the text in the layout. The returned text should not
- * be freed or modified.
+ * Gets the text in the layout.
  *
- * Return value: the text in the @layout.
- **/
+ * The returned text should not be freed or modified.
+ *
+ * Return value: (transfer none): the text in the @layout
+ */
 const char*
 pango_layout_get_text (PangoLayout *layout)
 {
@@ -1230,14 +1227,15 @@ pango_layout_get_character_count (PangoLayout *layout)
  * @layout: a `PangoLayout`
  * @markup: marked-up text
  * @length: length of marked-up text in bytes, or -1 if @markup is
- *   null-terminated
+ *   `NUL`-terminated
  *
  * Sets the layout text and attribute list from marked-up text.
  *
  * See [Pango Markup](pango_markup.html)).
+ *
  * Replaces the current text and attribute list.
  *
- * This is the Same as [method@Pango.Layout.set_markup_with_accel],
+ * This is the same as [method@Pango.Layout.set_markup_with_accel],
  * but the markup text isn't scanned for accelerators.
  */
 void
@@ -1253,14 +1251,15 @@ pango_layout_set_markup (PangoLayout *layout,
  * @layout: a `PangoLayout`
  * @markup: marked-up text (see [Pango Markup](pango_markup.html))
  * @length: length of marked-up text in bytes, or -1 if @markup is
- *   null-terminated
+ *   `NUL`-terminated
  * @accel_marker: marker for accelerators in the text
- * @accel_char: (out caller-allocates) (allow-none): return location
- *   for first located accelerator, or %NULL
+ * @accel_char: (out caller-allocates) (optional): return location
+ *   for first located accelerator
  *
  * Sets the layout text and attribute list from marked-up text.
  *
  * See [Pango Markup](pango_markup.html)).
+ *
  * Replaces the current text and attribute list.
  *
  * If @accel_marker is nonzero, the given character will mark the
@@ -1314,7 +1313,7 @@ pango_layout_set_markup_with_accel (PangoLayout *layout,
  * used in combination with %PANGO_ATTR_FALLBACK, to check if a
  * certain font supports all the characters in the string.
  *
- * Return value: The number of unknown glyphs in @layout.
+ * Return value: The number of unknown glyphs in @layout
  *
  * Since: 1.16
  */
@@ -1430,7 +1429,7 @@ pango_layout_get_serial (PangoLayout *layout)
  * pango_layout_get_log_attrs:
  * @layout: a `PangoLayout`
  * @attrs: (out)(array length=n_attrs)(transfer container):
- *   location to store a pointer to an array of logical attributes
+ *   location to store a pointer to an array of logical attributes.
  *   This value must be freed with g_free().
  * @n_attrs: (out): location to store the number of the attributes in the
  *   array. (The stored value will be one more than the total number
@@ -1505,7 +1504,7 @@ pango_layout_get_log_attrs_readonly (PangoLayout *layout,
  *
  * Retrieves the count of lines for the @layout.
  *
- * Return value: the line count.
+ * Return value: the line count
  */
 int
 pango_layout_get_line_count (PangoLayout   *layout)
@@ -1580,7 +1579,7 @@ pango_layout_get_lines_readonly (PangoLayout *layout)
  * pango_layout_get_line:
  * @layout: a `PangoLayout`
  * @line: the index of a line, which must be between 0 and
- *        `pango_layout_get_line_count(layout) - 1`, inclusive.
+ *   `pango_layout_get_line_count(layout) - 1`, inclusive.
  *
  * Retrieves a particular line from a `PangoLayout`.
  *
@@ -1621,7 +1620,7 @@ pango_layout_get_line (PangoLayout *layout,
  * pango_layout_get_line_readonly:
  * @layout: a `PangoLayout`
  * @line: the index of a line, which must be between 0 and
- *        `pango_layout_get_line_count(layout) - 1`, inclusive.
+ *   `pango_layout_get_line_count(layout) - 1`, inclusive.
  *
  * Retrieves a particular line from a `PangoLayout`.
  *
@@ -1664,8 +1663,8 @@ pango_layout_get_line_readonly (PangoLayout *layout,
  * @line: a `PangoLayoutLine`
  * @index_: byte offset of a grapheme within the layout
  * @trailing: an integer indicating the edge of the grapheme to retrieve
- *    the position of. If > 0, the trailing edge of the grapheme,
- *    if 0, the leading of the grapheme.
+ *   the position of. If > 0, the trailing edge of the grapheme,
+ *   if 0, the leading of the grapheme
  * @x_pos: (out): location to store the x_offset (in Pango units)
  *
  * Converts an index within a line to a X position.
@@ -1809,14 +1808,14 @@ pango_layout_index_to_line_and_extents (PangoLayout     *layout,
 /**
  * pango_layout_index_to_line_x:
  * @layout: a `PangoLayout`
- * @index_: the byte index of a grapheme within the layout.
+ * @index_: the byte index of a grapheme within the layout
  * @trailing: an integer indicating the edge of the grapheme to retrieve the
  *   position of. If > 0, the trailing edge of the grapheme, if 0,
- *   the leading of the grapheme.
- * @line: (out) (allow-none): location to store resulting line index. (which will
- *   between 0 and pango_layout_get_line_count(layout) - 1), or %NULL
- * @x_pos: (out) (allow-none): location to store resulting position within line
- *   (%PANGO_SCALE units per device unit), or %NULL
+ *   the leading of the grapheme
+ * @line: (out) (optional): location to store resulting line index. (which will
+ *   between 0 and pango_layout_get_line_count(layout) - 1)
+ * @x_pos: (out) (optional): location to store resulting position within line
+ *   (%PANGO_SCALE units per device unit)
  *
  * Converts from byte @index_ within the @layout to line and X position.
  *
@@ -1867,12 +1866,12 @@ pango_layout_index_to_line_x (PangoLayout *layout,
  * @strong: whether the moving cursor is the strong cursor or the
  *   weak cursor. The strong cursor is the cursor corresponding
  *   to text insertion in the base direction for the layout.
- * @old_index:    the byte index of the grapheme for the old index
+ * @old_index: the byte index of the grapheme for the old index
  * @old_trailing: if 0, the cursor was at the leading edge of the
  *   grapheme indicated by @old_index, if > 0, the cursor
  *   was at the trailing edge.
- * @direction:    direction to move cursor. A negative
- *   value indicates motion to the left.
+ * @direction: direction to move cursor. A negative
+ *   value indicates motion to the left
  * @new_index: (out): location to store the new cursor byte index.
  *   A value of -1 indicates that the cursor has been moved off the
  *   beginning of the layout. A value of %G_MAXINT indicates that
@@ -2051,7 +2050,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
 /**
  * pango_layout_xy_to_index:
  * @layout: a `PangoLayout`
- * @x: the X offset (in Pango units) from the left edge of the layout.
+ * @x: the X offset (in Pango units) from the left edge of the layout
  * @y: the Y offset (in Pango units) from the top edge of the layout
  * @index_: (out): location to store calculated byte index
  * @trailing: (out): location to store a integer indicating where
@@ -2062,15 +2061,14 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
  * Converts from X and Y position within a layout to the byte index to the
  * character at that logical position.
  *
- * If the Y position is not inside the
- * layout, the closest position is chosen (the position will be clamped
- * inside the layout). If the X position is not within the layout, then
- * the start or the end of the line is chosen as described for
- * [method@Pango.LayoutLine.x_to_index]. If either the X or Y positions
- * were not inside the layout, then the function returns %FALSE; on an
- * exact hit, it returns %TRUE.
+ * If the Y position is not inside the layout, the closest position is
+ * chosen (the position will be clamped inside the layout). If the X position
+ * is not within the layout, then the start or the end of the line is
+ * chosen as described for [method@Pango.LayoutLine.x_to_index]. If either
+ * the X or Y positions were not inside the layout, then the function returns
+ * %FALSE; on an exact hit, it returns %TRUE.
  *
- * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise.
+ * Return value: %TRUE if the coordinates were inside text, %FALSE otherwise
  */
 gboolean
 pango_layout_xy_to_index (PangoLayout *layout,
@@ -2416,10 +2414,8 @@ pango_layout_get_direction (PangoLayout *layout,
  * pango_layout_get_cursor_pos:
  * @layout: a `PangoLayout`
  * @index_: the byte index of the cursor
- * @strong_pos: (out) (allow-none): location to store the strong
- *   cursor position (may be %NULL)
- * @weak_pos: (out) (allow-none): location to store the weak cursor
- *   position (may be %NULL)
+ * @strong_pos: (out) (optional): location to store the strong cursor position
+ * @weak_pos: (out) (optional): location to store the weak cursor position
  *
  * Given an index within a layout, determines the positions that of the
  * strong and weak cursors if the insertion point is at that index.
@@ -2858,10 +2854,10 @@ pango_layout_get_extents_internal (PangoLayout    *layout,
 /**
  * pango_layout_get_extents:
  * @layout: a `PangoLayout`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the
- *   layout as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none):rectangle used to store the logical
- *   extents of the layout or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the
+ *   layout as drawn
+ * @logical_rect: (out) (optional):rectangle used to store the logical
+ *   extents of the layout
  *
  * Computes the logical and ink extents of @layout.
  *
@@ -2887,17 +2883,17 @@ pango_layout_get_extents (PangoLayout    *layout,
 /**
  * pango_layout_get_pixel_extents:
  * @layout: a `PangoLayout`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of the
- *   layout as drawn or %NULL to indicate that the result is not needed.
- * @logical_rect: (out) (allow-none): rectangle used to store the logical
- *   extents of the layout or %NULL to indicate that the result is not needed.
+ * @ink_rect: (out) (optional): rectangle used to store the extents of the
+ *   layout as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical
+ *   extents of the layout
  *
  * Computes the logical and ink extents of @layout in device units.
  *
  * This function just calls [method@Pango.Layout.get_extents] followed by
  * two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect
  * such that the rounded rectangles fully contain the unrounded one (that is,
- * passes them as first argument to `pango_extents_to_pixels()`).
+ * passes them as first argument to [func@Pango.extents_to_pixels]).
  */
 void
 pango_layout_get_pixel_extents (PangoLayout    *layout,
@@ -2914,8 +2910,8 @@ pango_layout_get_pixel_extents (PangoLayout    *layout,
 /**
  * pango_layout_get_size:
  * @layout: a `PangoLayout`
- * @width: (out) (allow-none): location to store the logical width, or %NULL
- * @height: (out) (allow-none): location to store the logical height, or %NULL
+ * @width: (out) (optional): location to store the logical width
+ * @height: (out) (optional): location to store the logical height
  *
  * Determines the logical width and height of a `PangoLayout` in Pango
  * units.
@@ -2940,15 +2936,15 @@ pango_layout_get_size (PangoLayout *layout,
 /**
  * pango_layout_get_pixel_size:
  * @layout: a `PangoLayout`
- * @width: (out) (allow-none): location to store the logical width, or %NULL
- * @height: (out) (allow-none): location to store the logical height, or %NULL
+ * @width: (out) (optional): location to store the logical width
+ * @height: (out) (optional): location to store the logical height
  *
  * Determines the logical width and height of a `PangoLayout` in device
  * units.
  *
  * [method@Pango.Layout.get_size] returns the width and height
- * scaled by %PANGO_SCALE. This is simply a convenience function around
- * [method@Pango.Layout.get_pixel_extents].
+ * scaled by %PANGO_SCALE. This is simply a convenience function
+ * around [method@Pango.Layout.get_pixel_extents].
  */
 void
 pango_layout_get_pixel_size (PangoLayout *layout,
@@ -2972,7 +2968,7 @@ pango_layout_get_pixel_size (PangoLayout *layout,
  *
  * Gets the Y position of baseline of the first line in @layout.
  *
- * Return value: baseline of first line, from top of @layout.
+ * Return value: baseline of first line, from top of @layout
  *
  * Since: 1.22
  */
@@ -4456,7 +4452,7 @@ pango_layout_check_lines (PangoLayout *layout)
 
 /**
  * pango_layout_line_ref:
- * @line: (nullable): a `PangoLayoutLine`, may be %NULL
+ * @line: (nullable): a `PangoLayoutLine`
  *
  * Increase the reference count of a `PangoLayoutLine` by one.
  *
@@ -4482,6 +4478,7 @@ pango_layout_line_ref (PangoLayoutLine *line)
  * @line: a `PangoLayoutLine`
  *
  * Decrease the reference count of a `PangoLayoutLine` by one.
+ *
  * If the result is zero, the line and all associated memory
  * will be freed.
  */
@@ -4512,21 +4509,22 @@ G_DEFINE_BOXED_TYPE (PangoLayoutLine, pango_layout_line,
  * @line: a `PangoLayoutLine`
  * @x_pos: the X offset (in Pango units) from the left edge of the line.
  * @index_: (out): location to store calculated byte index for the grapheme
- *   in which the user clicked.
+ *   in which the user clicked
  * @trailing: (out): location to store an integer indicating where in the
  *   grapheme the user clicked. It will either be zero, or the number of
  *   characters in the grapheme. 0 represents the leading edge of the grapheme.
  *
  * Converts from x offset to the byte index of the corresponding character
- * within the text of the layout. If @x_pos is outside the line, @index_ and
- * @trailing will point to the very first or very last position in the line.
- * This determination is based on the resolved direction of the paragraph;
- * for example, if the resolved direction is right-to-left, then an X position
- * to the right of the line (after it) results in 0 being stored in @index_
- * and @trailing. An X position to the left of the line results in @index_
- * pointing to the (logical) last grapheme in the line and @trailing being
- * set to the number of characters in that grapheme. The reverse is true for
- * a left-to-right line.
+ * within the text of the layout.
+ *
+ * If @x_pos is outside the line, @index_ and @trailing will point to the very
+ * first or very last position in the line. This determination is based on the
+ * resolved direction of the paragraph; for example, if the resolved direction
+ * is right-to-left, then an X position to the right of the line (after it)
+ * results in 0 being stored in @index_ and @trailing. An X position to the
+ * left of the line results in @index_ pointing to the (logical) last grapheme
+ * in the line and @trailing being set to the number of characters in that
+ * grapheme. The reverse is true for a left-to-right line.
  *
  * Return value: %FALSE if @x_pos was outside the line, %TRUE if inside
  */
@@ -4742,9 +4740,10 @@ pango_layout_line_get_width (PangoLayoutLine *line)
  *   width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed
  *   with g_free(). The coordinates are relative to the layout and are in
  *   Pango units.
- * @n_ranges: The number of ranges stored in @ranges.
+ * @n_ranges: The number of ranges stored in @ranges
  *
  * Gets a list of visual ranges corresponding to a given logical range.
+ *
  * This list is not necessarily minimal - there may be consecutive
  * ranges which are adjacent. The ranges will be sorted from left to
  * right. The ranges are with respect to the left edge of the entire
@@ -5240,14 +5239,15 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
 /**
  * pango_layout_line_get_extents:
  * @line: a `PangoLayoutLine`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of
+ * @ink_rect: (out) (optional): rectangle used to store the extents of
  *   the glyph string as drawn, or %NULL
- * @logical_rect: (out) (allow-none):rectangle used to store the logical
+ * @logical_rect: (out) (optional): rectangle used to store the logical
  *   extents of the glyph string, or %NULL
  *
- * Computes the logical and ink extents of a layout line. See
- * [method@Pango.Font.get_glyph_extents] for details about the
- * interpretation of the rectangles.
+ * Computes the logical and ink extents of a layout line.
+ *
+ * See [method@Pango.Font.get_glyph_extents] for details
+ * about the interpretation of the rectangles.
  */
 void
 pango_layout_line_get_extents (PangoLayoutLine *line,
@@ -5260,7 +5260,7 @@ pango_layout_line_get_extents (PangoLayoutLine *line,
 /**
  * pango_layout_line_get_height:
  * @line: a `PangoLayoutLine`
- * @height: (out) (allow-none): return location for the line height
+ * @height: (out) (optional): return location for the line height
  *
  * Computes the height of the line, i.e. the distance between
  * this and the previous lines baseline.
@@ -5294,10 +5294,10 @@ pango_layout_line_new (PangoLayout *layout)
 /**
  * pango_layout_line_get_pixel_extents:
  * @layout_line: a `PangoLayoutLine`
- * @ink_rect: (out) (allow-none): rectangle used to store the extents of
- *   the glyph string as drawn, or %NULL
- * @logical_rect: (out) (allow-none): rectangle used to store the logical
- *   extents of the glyph string, or %NULL
+ * @ink_rect: (out) (optional): rectangle used to store the extents of
+ *   the glyph string as drawn
+ * @logical_rect: (out) (optional): rectangle used to store the logical
+ *   extents of the glyph string
  *
  * Computes the logical and ink extents of @layout_line in device units.
  *
@@ -6161,13 +6161,11 @@ update_run (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_copy:
- * @iter: (nullable): a `PangoLayoutIter`, may be %NULL
+ * @iter: (nullable): a `PangoLayoutIter`
  *
  * Copies a `PangoLayoutIter`.
  *
- * Return value: (nullable): the newly allocated `PangoLayoutIter`,
- *   which should be freed with [method@Pango.LayoutIter.free],
- *   or %NULL if @iter was %NULL.
+ * Return value: (nullable): the newly allocated `PangoLayoutIter`
  *
  * Since: 1.20
  */
@@ -6227,8 +6225,7 @@ G_DEFINE_BOXED_TYPE (PangoLayoutIter, pango_layout_iter,
  *
  * Returns an iterator to iterate over the visual extents of the layout.
  *
- * Return value: the new `PangoLayoutIter` that should be freed using
- *   [method@Pango.LayoutIter.free].
+ * Return value: the new `PangoLayoutIter`
  */
 PangoLayoutIter*
 pango_layout_get_iter (PangoLayout *layout)
@@ -6327,12 +6324,14 @@ pango_layout_iter_free (PangoLayoutIter *iter)
  * pango_layout_iter_get_index:
  * @iter: a `PangoLayoutIter`
  *
- * Gets the current byte index. Note that iterating forward by char
- * moves in visual order, not logical order, so indexes may not be
- * sequential. Also, the index may be equal to the length of the text
- * in the layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]).
+ * Gets the current byte index.
+ *
+ * Note that iterating forward by char moves in visual order,
+ * not logical order, so indexes may not be sequential. Also,
+ * the index may be equal to the length of the text in the
+ * layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]).
  *
- * Return value: current byte index.
+ * Return value: current byte index
  */
 int
 pango_layout_iter_get_index (PangoLayoutIter *iter)
@@ -6347,15 +6346,17 @@ pango_layout_iter_get_index (PangoLayoutIter *iter)
  * pango_layout_iter_get_run:
  * @iter: a `PangoLayoutIter`
  *
- * Gets the current run. When iterating by run, at the end of each
- * line, there's a position with a %NULL run, so this function can return
- * %NULL. The %NULL run at the end of each line ensures that all lines have
- * at least one run, even lines consisting of only a newline.
+ * Gets the current run.
+ *
+ * When iterating by run, at the end of each line, there's a position
+ * with a %NULL run, so this function can return %NULL. The %NULL run
+ * at the end of each line ensures that all lines have at least one run,
+ * even lines consisting of only a newline.
  *
  * Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not
  * plan to modify the contents of the run (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none) (nullable): the current run.
+ * Return value: (transfer none) (nullable): the current run
  */
 PangoLayoutRun*
 pango_layout_iter_get_run (PangoLayoutIter *iter)
@@ -6372,17 +6373,19 @@ pango_layout_iter_get_run (PangoLayoutIter *iter)
  * pango_layout_iter_get_run_readonly:
  * @iter: a `PangoLayoutIter`
  *
- * Gets the current run. When iterating by run, at the end of each
- * line, there's a position with a %NULL run, so this function can return
- * %NULL. The %NULL run at the end of each line ensures that all lines have
- * at least one run, even lines consisting of only a newline.
+ * Gets the current run for read-only access.
+ *
+ * When iterating by run, at the end of each line, there's a position
+ * with a %NULL run, so this function can return %NULL. The %NULL run
+ * at the end of each line ensures that all lines have at least one run,
+ * even lines consisting of only a newline.
  *
  * This is a faster alternative to [method@Pango.LayoutIter.get_run],
  * but the user is not expected to modify the contents of the run (glyphs,
  * glyph widths, etc.).
  *
  * Return value: (transfer none) (nullable): the current run, that
- * should not be modified.
+ *   should not be modified
  *
  * Since: 1.16
  */
@@ -6414,7 +6417,7 @@ _pango_layout_iter_get_line (PangoLayoutIter *iter)
  * you do not plan to modify the contents of the line (glyphs,
  * glyph widths, etc.).
  *
- * Return value: (transfer none): the current line.
+ * Return value: (transfer none): the current line
  */
 PangoLayoutLine*
 pango_layout_iter_get_line (PangoLayoutIter *iter)
@@ -6438,7 +6441,7 @@ pango_layout_iter_get_line (PangoLayoutIter *iter)
  * (glyphs, glyph widths, etc.).
  *
  * Return value: (transfer none): the current line, that should not be
- * modified.
+ *   modified
  *
  * Since: 1.16
  */
@@ -6457,7 +6460,7 @@ pango_layout_iter_get_line_readonly (PangoLayoutIter *iter)
  *
  * Determines whether @iter is on the last line of the layout.
  *
- * Return value: %TRUE if @iter is on the last line.
+ * Return value: %TRUE if @iter is on the last line
  */
 gboolean
 pango_layout_iter_at_last_line (PangoLayoutIter *iter)
@@ -6474,7 +6477,7 @@ pango_layout_iter_at_last_line (PangoLayoutIter *iter)
  *
  * Gets the layout associated with a `PangoLayoutIter`.
  *
- * Return value: (transfer none): the layout associated with @iter.
+ * Return value: (transfer none): the layout associated with @iter
  *
  * Since: 1.20
  */
@@ -6595,9 +6598,10 @@ next_cluster_internal (PangoLayoutIter *iter,
  * @iter: a `PangoLayoutIter`
  *
  * Moves @iter forward to the next character in visual order.
+ *
  * If @iter was already at the end of the layout, returns %FALSE.
  *
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
  */
 gboolean
 pango_layout_iter_next_char (PangoLayoutIter *iter)
@@ -6639,9 +6643,10 @@ pango_layout_iter_next_char (PangoLayoutIter *iter)
  * @iter: a `PangoLayoutIter`
  *
  * Moves @iter forward to the next cluster in visual order.
+ *
  * If @iter was already at the end of the layout, returns %FALSE.
  *
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
  */
 gboolean
 pango_layout_iter_next_cluster (PangoLayoutIter *iter)
@@ -6654,9 +6659,10 @@ pango_layout_iter_next_cluster (PangoLayoutIter *iter)
  * @iter: a `PangoLayoutIter`
  *
  * Moves @iter forward to the next run in visual order.
+ *
  * If @iter was already at the end of the layout, returns %FALSE.
  *
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
  */
 gboolean
 pango_layout_iter_next_run (PangoLayoutIter *iter)
@@ -6698,9 +6704,10 @@ pango_layout_iter_next_run (PangoLayoutIter *iter)
  * @iter: a `PangoLayoutIter`
  *
  * Moves @iter forward to the start of the next line.
+ *
  * If @iter is already on the last line, returns %FALSE.
  *
- * Return value: whether motion was possible.
+ * Return value: whether motion was possible
  */
 gboolean
 pango_layout_iter_next_line (PangoLayoutIter *iter)
@@ -6743,10 +6750,12 @@ pango_layout_iter_next_line (PangoLayoutIter *iter)
  * @logical_rect: (out caller-allocates): rectangle to fill with
  *   logical extents
  *
- * Gets the extents of the current character, in layout coordinates
- * (origin is the top left of the entire layout). Only logical extents
- * can sensibly be obtained for characters; ink extents make sense only
- * down to the level of clusters.
+ * Gets the extents of the current character, in layout coordinates.
+ *
+ * Layout coordinates have the origin at the top left of the entire layout.
+ *
+ * Only logical extents can sensibly be obtained for characters;
+ * ink extents make sense only down to the level of clusters.
  */
 void
 pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
@@ -6791,11 +6800,12 @@ pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_cluster_extents:
  * @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
+ *
+ * Gets the extents of the current cluster, in layout coordinates.
  *
- * Gets the extents of the current cluster, in layout coordinates
- * (origin is the top left of the entire layout).
+ * Layout coordinates have the origin at the top left of the entire layout.
  */
 void
 pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
@@ -6838,11 +6848,12 @@ pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_run_extents:
  * @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
  *
- * Gets the extents of the current run in layout coordinates
- * (origin is the top left of the entire layout).
+ * Gets the extents of the current run in layout coordinates.
+ *
+ * Layout coordinates have the origin at the top left of the entire layout.
  */
 void
 pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
@@ -6894,15 +6905,15 @@ pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_line_extents:
  * @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
- *
- * Obtains the extents of the current line. @ink_rect or @logical_rect
- * can be %NULL if you aren't interested in them. Extents are in layout
- * coordinates (origin is the top-left corner of the entire
- * `PangoLayout`). Thus the extents returned by this function will be
- * the same width/height but not at the same x/y as the extents
- * returned from [method@Pango.LayoutLine.get_extents].
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
+ *
+ * Obtains the extents of the current line.
+ *
+ * Extents are in layout coordinates (origin is the top-left corner
+ * of the entire `PangoLayout`). Thus the extents returned by this
+ * function will be the same width/height but not at the same x/y
+ * as the extents returned from [method@Pango.LayoutLine.get_extents].
  */
 void
 pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
@@ -6933,16 +6944,17 @@ pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
 /**
  * pango_layout_iter_get_line_yrange:
  * @iter: a `PangoLayoutIter`
- * @y0_: (out) (allow-none): start of line, or %NULL
- * @y1_: (out) (allow-none): end of line, or %NULL
+ * @y0_: (out) (optional): start of line
+ * @y1_: (out) (optional): end of line
  *
  * Divides the vertical space in the `PangoLayout` being iterated over
  * between the lines in the layout, and returns the space belonging to
- * the current line. A line's range includes the line's logical extents,
- * plus half of the spacing above and below the line, if
- * [method@Pango.Layout.set_spacing] has been called to set layout spacing.
- * The Y positions are in layout coordinates (origin at top left of the
- * entire layout).
+ * the current line.
+ *
+ * A line's range includes the line's logical extents. plus half of the
+ * spacing above and below the line, if [method@Pango.Layout.set_spacing]
+ * has been called to set layout spacing. The Y positions are in layout
+ * coordinates (origin at top left of the entire layout).
  *
  * Note: Since 1.44, Pango uses line heights for placing lines, and there
  * may be gaps between the ranges returned by this function.
@@ -6991,9 +7003,11 @@ pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
  * @iter: a `PangoLayoutIter`
  *
  * Gets the Y position of the current line's baseline, in layout
- * coordinates (origin at top left of the entire layout).
+ * coordinates.
+ *
+ * Layout coordinates have the origin at the top left of the entire layout.
  *
- * Return value: baseline of current line.
+ * Return value: baseline of current line
  */
 int
 pango_layout_iter_get_baseline (PangoLayoutIter *iter)
@@ -7007,16 +7021,15 @@ pango_layout_iter_get_baseline (PangoLayoutIter *iter)
 /**
  * pango_layout_iter_get_layout_extents:
  * @iter: a `PangoLayoutIter`
- * @ink_rect: (out) (allow-none): rectangle to fill with ink extents, or %NULL
- * @logical_rect: (out) (allow-none): rectangle to fill with logical extents, or %NULL
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents
  *
  * Obtains the extents of the `PangoLayout` being iterated over.
- * @ink_rect or @logical_rect can be %NULL if you aren't interested in them.
  */
 void
-pango_layout_iter_get_layout_extents  (PangoLayoutIter *iter,
-                                       PangoRectangle  *ink_rect,
-                                       PangoRectangle  *logical_rect)
+pango_layout_iter_get_layout_extents (PangoLayoutIter *iter,
+                                      PangoRectangle  *ink_rect,
+                                      PangoRectangle  *logical_rect)
 {
   if (ITER_IS_INVALID (iter))
     return;
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 4a464230..f310e7a3 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -100,11 +100,11 @@ typedef enum {
 
 /**
  * PangoLayoutLine:
- * @layout: (allow-none): the layout this line belongs to, might be %NULL
+ * @layout: (nullable): the layout this line belongs to, might be %NULL
  * @start_index: start of line as byte index into layout->text
  * @length: length of line in bytes
- * @runs: (allow-none) (element-type Pango.LayoutRun): list of runs in the
- *        line, from left to right
+ * @runs: (nullable) (element-type Pango.LayoutRun): list of runs in the
+ *   line, from left to right
  * @is_paragraph_start: #TRUE if this is the first line of the paragraph
  * @resolved_dir: #Resolved PangoDirection of line
  *
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index eca3e630..3728d3b3 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -602,9 +602,9 @@ pango_markup_parser_new_internal (char       accel_marker,
  * @markup_text: markup to parse (see the Pango Markup docs)
  * @length: length of @markup_text, or -1 if nul-terminated
  * @accel_marker: character that precedes an accelerator, or 0 for none
- * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL
- * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL
- * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL
+ * @attr_list: (out) (optional): address of return location for a `PangoAttrList`, or %NULL
+ * @text: (out) (optional): address of return location for text with tags stripped, or %NULL
+ * @accel_char: (out) (optional): address of return location for accelerator char, or %NULL
  * @error: address of return location for errors, or %NULL
  *
  * Parses marked-up text to create a plain-text string and an attribute list.
@@ -726,9 +726,9 @@ pango_markup_parser_new (gunichar               accel_marker)
 /**
  * pango_markup_parser_finish:
  * @context: A valid parse context that was returned from [func@markup_parser_new]
- * @attr_list: (out) (allow-none): address of return location for a `PangoAttrList`, or %NULL
- * @text: (out) (allow-none): address of return location for text with tags stripped, or %NULL
- * @accel_char: (out) (allow-none): address of return location for accelerator char, or %NULL
+ * @attr_list: (out) (optional): address of return location for a `PangoAttrList`, or %NULL
+ * @text: (out) (optional): address of return location for text with tags stripped, or %NULL
+ * @accel_char: (out) (optional): address of return location for accelerator char, or %NULL
  * @error: address of return location for errors, or %NULL
  *
  * Finishes parsing markup.
diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c
index 731c3a26..471a5e51 100644
--- a/pango/pango-matrix.c
+++ b/pango/pango-matrix.c
@@ -188,7 +188,7 @@ pango_matrix_concat (PangoMatrix       *matrix,
 
 /**
  * pango_matrix_get_font_scale_factor:
- * @matrix: (allow-none): a `PangoMatrix`, may be %NULL
+ * @matrix: (nullable): a `PangoMatrix`, may be %NULL
  *
  * Returns the scale factor of a matrix on the height of the font.
  *
@@ -212,8 +212,8 @@ pango_matrix_get_font_scale_factor (const PangoMatrix *matrix)
 /**
  * pango_matrix_get_font_scale_factors:
  * @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @xscale: (out) (allow-none): output scale factor in the x direction, or %NULL
- * @yscale: (out) (allow-none): output scale factor perpendicular to the x direction, or %NULL
+ * @xscale: (out) (optional): output scale factor in the x direction, or %NULL
+ * @yscale: (out) (optional): output scale factor perpendicular to the x direction, or %NULL
  *
  * Calculates the scale factor of a matrix on the width and height of the font.
  *
@@ -332,7 +332,7 @@ pango_matrix_transform_point (const PangoMatrix *matrix,
 /**
  * pango_matrix_transform_rectangle:
  * @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @rect: (inout) (allow-none): in/out bounding box in Pango units, or %NULL
+ * @rect: (inout) (optional): in/out bounding box in Pango units, or %NULL
  *
  * First transforms @rect using @matrix, then calculates the bounding box
  * of the transformed rectangle.
@@ -412,7 +412,7 @@ pango_matrix_transform_rectangle (const PangoMatrix *matrix,
 /**
  * pango_matrix_transform_pixel_rectangle:
  * @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @rect: (inout) (allow-none): in/out bounding box in device units, or %NULL
+ * @rect: (inout) (optional): in/out bounding box in device units, or %NULL
  *
  * First transforms the @rect using @matrix, then calculates the bounding box
  * of the transformed rectangle.
diff --git a/pango/pango-matrix.h b/pango/pango-matrix.h
index c3ff5414..d4277401 100644
--- a/pango/pango-matrix.h
+++ b/pango/pango-matrix.h
@@ -60,17 +60,12 @@ struct _PangoMatrix
   double y0;
 };
 
-/**
- * PANGO_TYPE_MATRIX:
- *
- * The GObject type for #PangoMatrix
- **/
 #define PANGO_TYPE_MATRIX (pango_matrix_get_type ())
 
 /**
  * PANGO_MATRIX_INIT:
  *
- * Constant that can be used to initialize a PangoMatrix to
+ * Constant that can be used to initialize a `PangoMatrix` to
  * the identity transform.
  *
  * ```
diff --git a/pango/pango-modules.h b/pango/pango-modules.h
index 54b347a2..5bd707b4 100644
--- a/pango/pango-modules.h
+++ b/pango/pango-modules.h
@@ -45,7 +45,7 @@ typedef struct _PangoIncludedModule PangoIncludedModule;
  * @exit: a function to finalize the module.
  * @create: a function to create an engine, given the engine name.
  *
- * The #PangoIncludedModule structure for a statically linked module
+ * The `PangoIncludedModule` structure for a statically linked module
  * contains the functions that would otherwise be loaded from a dynamically
  * loaded module.
  *
diff --git a/pango/pango-ot-buffer.c b/pango/pango-ot-buffer.c
index bec4365a..c48edae2 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -38,16 +38,16 @@ G_DEFINE_BOXED_TYPE (PangoOTBuffer, pango_ot_buffer,
                      pango_ot_buffer_destroy)
 
 /**
- * pango_ot_buffer_new
- * @font: a #PangoFcFont
+ * pango_ot_buffer_new:
+ * @font: a `PangoFcFont`
  *
- * Creates a new #PangoOTBuffer for the given OpenType font.
+ * Creates a new `PangoOTBuffer` for the given OpenType font.
  *
- * Return value: the newly allocated #PangoOTBuffer, which should
- *               be freed with pango_ot_buffer_destroy().
+ * Return value: the newly allocated `PangoOTBuffer`, which should
+ *   be freed with [method@PangoOT.Buffer.destroy].
  *
  * Since: 1.4
- **/
+ */
 PangoOTBuffer *
 pango_ot_buffer_new (PangoFcFont *font)
 {
@@ -59,13 +59,13 @@ pango_ot_buffer_new (PangoFcFont *font)
 }
 
 /**
- * pango_ot_buffer_destroy
- * @buffer: a #PangoOTBuffer
+ * pango_ot_buffer_destroy:
+ * @buffer: a `PangoOTBuffer`
  *
- * Destroys a #PangoOTBuffer and free all associated memory.
+ * Destroys a `PangoOTBuffer` and free all associated memory.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_buffer_destroy (PangoOTBuffer *buffer)
 {
@@ -74,13 +74,13 @@ pango_ot_buffer_destroy (PangoOTBuffer *buffer)
 }
 
 /**
- * pango_ot_buffer_clear
- * @buffer: a #PangoOTBuffer
+ * pango_ot_buffer_clear:
+ * @buffer: a `PangoOTBuffer`
  *
- * Empties a #PangoOTBuffer, make it ready to add glyphs to.
+ * Empties a `PangoOTBuffer`, make it ready to add glyphs to.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_buffer_clear (PangoOTBuffer *buffer)
 {
@@ -88,17 +88,19 @@ pango_ot_buffer_clear (PangoOTBuffer *buffer)
 }
 
 /**
- * pango_ot_buffer_add_glyph
- * @buffer: a #PangoOTBuffer
- * @glyph: the glyph index to add, like a #PangoGlyph
+ * pango_ot_buffer_add_glyph:
+ * @buffer: a `PangoOTBuffer`
+ * @glyph: the glyph index to add, like a `PangoGlyph`
  * @properties: the glyph properties
  * @cluster: the cluster that this glyph belongs to
  *
- * Appends a glyph to a #PangoOTBuffer, with @properties identifying which
- * features should be applied on this glyph.  See pango_ot_ruleset_add_feature().
+ * Appends a glyph to a `PangoOTBuffer`, with @properties identifying which
+ * features should be applied on this glyph.
+ *
+ * See [method@PangoOT.Ruleset.add_feature].
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
 			   guint          glyph,
@@ -109,15 +111,17 @@ pango_ot_buffer_add_glyph (PangoOTBuffer *buffer,
 }
 
 /**
- * pango_ot_buffer_set_rtl
- * @buffer: a #PangoOTBuffer
+ * pango_ot_buffer_set_rtl:
+ * @buffer: a `PangoOTBuffer`
  * @rtl: %TRUE for right-to-left text
  *
- * Sets whether glyphs will be rendered right-to-left.  This setting
- * is needed for proper horizontal positioning of right-to-left scripts.
+ * Sets whether glyphs will be rendered right-to-left.
+ *
+ * This setting is needed for proper horizontal positioning
+ * of right-to-left scripts.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
 			 gboolean       rtl)
@@ -127,37 +131,38 @@ pango_ot_buffer_set_rtl (PangoOTBuffer *buffer,
 
 /**
  * pango_ot_buffer_set_zero_width_marks
- * @buffer: a #PangoOTBuffer
+ * @buffer: a `PangoOTBuffer`
  * @zero_width_marks: %TRUE if characters with a mark class should
- *  be forced to zero width.
+ *   be forced to zero width
  *
  * Sets whether characters with a mark class should be forced to zero width.
+ *
  * This setting is needed for proper positioning of Arabic accents,
  * but will produce incorrect results with standard OpenType Indic
  * fonts.
  *
  * Since: 1.6
- **/
+ */
 void
-pango_ot_buffer_set_zero_width_marks (PangoOTBuffer     *buffer,
-				      gboolean           zero_width_marks)
+pango_ot_buffer_set_zero_width_marks (PangoOTBuffer *buffer,
+				      gboolean       zero_width_marks)
 {
 }
 
 /**
  * pango_ot_buffer_get_glyphs
- * @buffer: a #PangoOTBuffer
+ * @buffer: a `PangoOTBuffer`
  * @glyphs: (array length=n_glyphs) (out) (optional): location to
- *   store the array of glyphs, or %NULL
- * @n_glyphs: (out) (optional): location to store the number of
- *   glyphs, or %NULL
+ *   store the array of glyphs
+ * @n_glyphs: (out) (optional): location to store the number of glyphs
+ *
+ * Gets the glyph array contained in a `PangoOTBuffer`.
  *
- * Gets the glyph array contained in a #PangoOTBuffer.  The glyphs are
- * owned by the buffer and should not be freed, and are only valid as long
- * as buffer is not modified.
+ * The glyphs are owned by the buffer and should not be freed,
+ * and are only valid as long as buffer is not modified.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_buffer_get_glyphs (const PangoOTBuffer  *buffer,
 			    PangoOTGlyph        **glyphs,
@@ -172,15 +177,17 @@ pango_ot_buffer_get_glyphs (const PangoOTBuffer  *buffer,
 
 /**
  * pango_ot_buffer_output
- * @buffer: a #PangoOTBuffer
- * @glyphs: a #PangoGlyphString
+ * @buffer: a `PangoOTBuffer`
+ * @glyphs: a `PangoGlyphString`
+ *
+ * Exports the glyphs in a `PangoOTBuffer` into a `PangoGlyphString`.
  *
- * Exports the glyphs in a #PangoOTBuffer into a #PangoGlyphString.  This is
- * typically used after the OpenType layout processing is over, to convert the
- * resulting glyphs into a generic Pango glyph string.
+ * This is typically used after the OpenType layout processing
+ * is over, to convert the resulting glyphs into a generic Pango
+ * glyph string.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_buffer_output (const PangoOTBuffer *buffer,
 			PangoGlyphString    *glyphs)
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index 891ae323..821c4f8b 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -64,15 +64,15 @@ pango_ot_info_finalizer (void *object)
 
 /**
  * pango_ot_info_get:
- * @face: a FT_Face
+ * @face: a `FT_Face`
  *
- * Returns the #PangoOTInfo structure for the given FreeType font face.
+ * Returns the `PangoOTInfo` structure for the given FreeType font face.
  *
- * Return value: (transfer none): the #PangoOTInfo for @face. This object
- *   will have the same lifetime as @face.
+ * Return value: (transfer none): the `PangoOTInfo` for @face.
+ *   This object will have the same lifetime as @face.
  *
  * Since: 1.2
- **/
+ */
 PangoOTInfo *
 pango_ot_info_get (FT_Face face)
 {
@@ -110,24 +110,24 @@ get_hb_table_type (PangoOTTableType table_type)
 
 /**
  * pango_ot_info_find_script:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @script_tag: the tag of the script to find.
- * @script_index: (out) (optional): location to store the index of the
- *   script, or %NULL.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @script_tag: the tag of the script to find
+ * @script_index: (out) (optional): location to store the index of the script
+ *
+ * Finds the index of a script.
  *
- * Finds the index of a script.  If not found, tries to find the 'DFLT'
- * and then 'dflt' scripts and return the index of that in @script_index.
- * If none of those is found either, %PANGO_OT_NO_SCRIPT is placed in
- * @script_index.
+ * If not found, tries to find the 'DFLT' and then 'dflt' scripts and
+ * return the index of that in @script_index. If none of those is found
+ * either, %PANGO_OT_NO_SCRIPT is placed in @script_index.
  *
  * All other functions taking an input script_index parameter know
  * how to handle %PANGO_OT_NO_SCRIPT, so one can ignore the return
  * value of this function completely and proceed, to enjoy the automatic
  * fallback to the 'DFLT'/'dflt' script.
  *
- * Return value: %TRUE if the script was found.
- **/
+ * Return value: %TRUE if the script was found
+ */
 gboolean
 pango_ot_info_find_script (PangoOTInfo      *info,
 			   PangoOTTableType  table_type,
@@ -143,26 +143,26 @@ pango_ot_info_find_script (PangoOTInfo      *info,
 
 /**
  * pango_ot_info_find_language:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @script_index: the index of the script whose languages are searched.
- * @language_tag: the tag of the language to find.
- * @language_index: (out) (optional): location to store the index of
- *   the language, or %NULL.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @script_index: the index of the script whose languages are searched
+ * @language_tag: the tag of the language to find
+ * @language_index: (out) (optional): location to store the index of the language
  * @required_feature_index: (out) (optional): location to store the
- *    required feature index of the language, or %NULL.
+ *   required feature index of the language
  *
  * Finds the index of a language and its required feature index.
- * If the language is not found, sets @language_index to
- * PANGO_OT_DEFAULT_LANGUAGE and the required feature of the default language
- * system is returned in required_feature_index.  For best compatibility with
- * some fonts, also searches the language system tag 'dflt' before falling
- * back to the default language system, but that is transparent to the user.
- * The user can simply ignore the return value of this function to
- * automatically fall back to the default language system.
  *
- * Return value: %TRUE if the language was found.
- **/
+ * If the language is not found, sets @language_index to %PANGO_OT_DEFAULT_LANGUAGE
+ * and the required feature of the default language system is returned in
+ * required_feature_index. For best compatibility with some fonts, also
+ * searches the language system tag 'dflt' before falling back to the default
+ * language system, but that is transparent to the user. The user can simply
+ * ignore the return value of this function to automatically fall back to the
+ * default language system.
+ *
+ * Return value: %TRUE if the language was found
+ */
 gboolean
 pango_ot_info_find_language (PangoOTInfo      *info,
 			     PangoOTTableType  table_type,
@@ -194,27 +194,29 @@ pango_ot_info_find_language (PangoOTInfo      *info,
 
 /**
  * pango_ot_info_find_feature:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @feature_tag: the tag of the feature to find.
- * @script_index: the index of the script.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @feature_tag: the tag of the feature to find
+ * @script_index: the index of the script
  * @language_index: the index of the language whose features are searched,
- *     or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script.
+ *   or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script
  * @feature_index: (out) (optional): location to store the index of
- *   the feature, or %NULL.
+ *   the feature
  *
- * Finds the index of a feature.  If the feature is not found, sets
- * @feature_index to PANGO_OT_NO_FEATURE, which is safe to pass to
- * pango_ot_ruleset_add_feature() and similar functions.
+ * Finds the index of a feature.
  *
- * In the future, this may set @feature_index to an special value that if used
- * in pango_ot_ruleset_add_feature() will ask Pango to synthesize the
- * requested feature based on Unicode properties and data.  However, this
- * function will still return %FALSE in those cases.  So, users may want to
+ * If the feature is not found, sets @feature_index to PANGO_OT_NO_FEATURE,
+ * which is safe to pass to [method@PangoOT.Ruleset.add_feature] and similar
+ * functions.
+ *
+ * In the future, this may set @feature_index to an special value that if
+ * used in [method@PangoOT.Ruleset.add_feature] will ask Pango to synthesize
+ * the requested feature based on Unicode properties and data. However, this
+ * function will still return %FALSE in those cases. So, users may want to
  * ignore the return value of this function in certain cases.
  *
- * Return value: %TRUE if the feature was found.
- **/
+ * Return value: %TRUE if the feature was found
+ */
 gboolean
 pango_ot_info_find_feature  (PangoOTInfo      *info,
 			     PangoOTTableType  table_type,
@@ -234,14 +236,14 @@ pango_ot_info_find_feature  (PangoOTInfo      *info,
 
 /**
  * pango_ot_info_list_scripts:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
  *
  * Obtains the list of available scripts.
  *
- * Return value: a newly-allocated zero-terminated array containing the tags of the
- *   available scripts.  Should be freed using g_free().
- **/
+ * Return value: a newly-allocated zero-terminated
+ *   array containing the tags of the available scripts
+ */
 PangoOTTag *
 pango_ot_info_list_scripts (PangoOTInfo      *info,
 			    PangoOTTableType  table_type)
@@ -260,16 +262,16 @@ pango_ot_info_list_scripts (PangoOTInfo      *info,
 
 /**
  * pango_ot_info_list_languages:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @script_index: the index of the script to list languages for.
- * @language_tag: unused parameter.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @script_index: the index of the script to list languages for
+ * @language_tag: unused parameter
  *
  * Obtains the list of available languages for a given script.
  *
- * Return value: a newly-allocated zero-terminated array containing the tags of the
- *   available languages.  Should be freed using g_free().
- **/
+ * Return value: a newly-allocated zero-terminated
+ *   array containing the tags of the available languages
+ */
 PangoOTTag *
 pango_ot_info_list_languages (PangoOTInfo      *info,
 			      PangoOTTableType  table_type,
@@ -290,19 +292,19 @@ pango_ot_info_list_languages (PangoOTInfo      *info,
 
 /**
  * pango_ot_info_list_features:
- * @info: a #PangoOTInfo.
- * @table_type: the table type to obtain information about.
- * @tag: unused parameter.
- * @script_index: the index of the script to obtain information about.
+ * @info: a `PangoOTInfo`
+ * @table_type: the table type to obtain information about
+ * @tag: unused parameter
+ * @script_index: the index of the script to obtain information about
  * @language_index: the index of the language to list features for, or
- *     %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default
- *     language of the script.
+ *   %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default
+ *   language of the script
  *
  * Obtains the list of features for the given language of the given script.
  *
- * Return value: a newly-allocated zero-terminated array containing the tags of the
- * available features.  Should be freed using g_free().
- **/
+ * Return value: a newly-allocated zero-terminated
+ *   array containing the tags of the available features
+ */
 PangoOTTag *
 pango_ot_info_list_features  (PangoOTInfo      *info,
 			      PangoOTTableType  table_type,
diff --git a/pango/pango-ot-private.h b/pango/pango-ot-private.h
index 7ba44c6a..9a88c3f4 100644
--- a/pango/pango-ot-private.h
+++ b/pango/pango-ot-private.h
@@ -38,10 +38,10 @@ typedef struct _PangoOTInfoClass PangoOTInfoClass;
 /**
  * PangoOTInfo:
  *
- * The #PangoOTInfo struct contains the various
+ * The `PangoOTInfo` struct contains the various
  * tables associated with an OpenType font. It contains only private fields and
  * should only be accessed via the pango_ot_info_… functions
- * which are documented below. To obtain a #PangoOTInfo,
+ * which are documented below. To obtain a `PangoOTInfo`,
  * use pango_ot_info_get().
  */
 struct _PangoOTInfo
@@ -73,11 +73,11 @@ struct _PangoOTRulesetClass
 /**
  * PangoOTBuffer:
  *
- * The #PangoOTBuffer structure is used to store strings of glyphs associated
- * with a #PangoFcFont, suitable for OpenType layout processing.  It contains
+ * The `PangoOTBuffer` structure is used to store strings of glyphs associated
+ * with a `PangoFcFont`, suitable for OpenType layout processing.  It contains
  * only private fields and should only be accessed via the
  * pango_ot_buffer_… functions which are documented below.
- * To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
+ * To obtain a `PangoOTBuffer`, use pango_ot_buffer_new().
  */
 struct _PangoOTBuffer
 {
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 9cf4cfb0..82a6ceca 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -28,14 +28,17 @@ static void pango_ot_ruleset_finalize   (GObject        *object);
 /**
  * PangoOTRuleset:
  *
- * The #PangoOTRuleset structure holds a
- * set of features selected from the tables in an OpenType font.
- * (A feature is an operation such as adjusting glyph positioning
+ * The `PangoOTRuleset` structure holds a set of features selected
+ * from the tables in an OpenType font.
+ *
+ * A feature is an operation such as adjusting glyph positioning
  * that should be applied to a text feature such as a certain
- * type of accent.) A #PangoOTRuleset
- * is created with pango_ot_ruleset_new(), features are added
- * to it with pango_ot_ruleset_add_feature(), then it is
- * applied to a #PangoGlyphString with pango_ot_ruleset_shape().
+ * type of accent.
+ *
+ * A `PangoOTRuleset` is created with [ctor@PangoOT.Ruleset.new],
+ * features are added to it with [method@PangoOT.Ruleset.add_feature],
+ * then it is applied to a `PangoGlyphString` with
+ * [method@PangoOT.Ruleset.position].
  */
 G_DEFINE_TYPE (PangoOTRuleset, pango_ot_ruleset, G_TYPE_OBJECT);
 
@@ -60,22 +63,24 @@ pango_ot_ruleset_finalize (GObject *object)
 
 /**
  * pango_ot_ruleset_get_for_description:
- * @info: a #PangoOTInfo.
- * @desc: a #PangoOTRulesetDescription.
+ * @info: a `PangoOTInfo`
+ * @desc: a `PangoOTRulesetDescription`
  *
  * Returns a ruleset for the given OpenType info and ruleset
- * description.  Rulesets are created on demand using
- * pango_ot_ruleset_new_from_description().
+ * description.
+ *
+ * Rulesets are created on demand using
+ * [ctor@PangoOT.Ruleset.new_from_description].
  * The returned ruleset should not be modified or destroyed.
  *
  * The static feature map members of @desc should be alive as
  * long as @info is.
  *
- * Return value: the #PangoOTRuleset for @desc. This object will have
- * the same lifetime as @info.
+ * Return value: the `PangoOTRuleset` for @desc. This object will have
+ *   the same lifetime as @info.
  *
  * Since: 1.18
- **/
+ */
 const PangoOTRuleset *
 pango_ot_ruleset_get_for_description (PangoOTInfo                     *info,
 				      const PangoOTRulesetDescription *desc)
@@ -90,13 +95,12 @@ pango_ot_ruleset_get_for_description (PangoOTInfo                     *info,
 
 /**
  * pango_ot_ruleset_new:
- * @info: a #PangoOTInfo.
+ * @info: a `PangoOTInfo`
  *
- * Creates a new #PangoOTRuleset for the given OpenType info.
+ * Creates a new `PangoOTRuleset` for the given OpenType info.
  *
- * Return value: the newly allocated #PangoOTRuleset, which
- *               should be freed with g_object_unref().
- **/
+ * Return value: the newly allocated `PangoOTRuleset`
+ */
 PangoOTRuleset *
 pango_ot_ruleset_new (PangoOTInfo *info)
 {
@@ -105,48 +109,46 @@ pango_ot_ruleset_new (PangoOTInfo *info)
 
 /**
  * pango_ot_ruleset_new_for:
- * @info: a #PangoOTInfo.
- * @script: a #PangoScript.
- * @language: a #PangoLanguage.
+ * @info: a `PangoOTInfo`
+ * @script: a `PangoScript`
+ * @language: a `PangoLanguage`
  *
- * Creates a new #PangoOTRuleset for the given OpenType info, script, and
+ * Creates a new `PangoOTRuleset` for the given OpenType info, script, and
  * language.
  *
  * This function is part of a convenience scheme that highly simplifies
- * using a #PangoOTRuleset to represent features for a specific pair of script
+ * using a `PangoOTRuleset` to represent features for a specific pair of script
  * and language.  So one can use this function passing in the script and
  * language of interest, and later try to add features to the ruleset by just
  * specifying the feature name or tag, without having to deal with finding
  * script, language, or feature indices manually.
  *
- * In excess to what pango_ot_ruleset_new() does, this function will:
+ * In addition to what [ctor@PangoOT.Ruleset.new] does, this function will:
  *
- * * Find the #PangoOTTag script and language tags associated with
- *   @script and @language using pango_ot_tag_from_script() and
- *   pango_ot_tag_from_language(),
+ * * Find the `PangoOTTag` script and language tags associated with
+ *   @script and @language using [func@PangoOT.tag_from_script] and
+ *   [func@PangoOT.tag_from_language],
  *
  * * For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS,
  *   find the script index of the script tag found and the language
  *   system index of the language tag found in that script system, using
- *   pango_ot_info_find_script() and pango_ot_info_find_language(),
+ *   [method@PangoOT.Info.find_script] and [method@PangoOT.Info.find_language],
  *
- * * For found language-systems, if they have required feature
- *   index, add that feature to the ruleset using
- *   pango_ot_ruleset_add_feature(),
+ * * For found language-systems, if they have required feature index,
+ *   add that feature to the ruleset using [method@PangoOT.Ruleset.add_feature],
  *
  * * Remember found script and language indices for both table types,
- *   and use them in future pango_ot_ruleset_maybe_add_feature() and
- *   pango_ot_ruleset_maybe_add_features().
+ *   and use them in future [method@PangoOT.Ruleset.maybe_add_feature] and
+ *   [method@PangoOT.Ruleset.maybe_add_features].
  *
- * Because of the way return values of pango_ot_info_find_script() and
- * pango_ot_info_find_language() are ignored, this function automatically
+ * Because of the way return values of [method@PangoOT.Info.find_script] and
+ * [method@PangoOT.Info.find_language] are ignored, this function automatically
  * finds and uses the 'DFLT' script and the default language-system.
  *
- * Return value: the newly allocated #PangoOTRuleset, which
- *               should be freed with g_object_unref().
+ * Return value: the newly allocated `PangoOTRuleset`
  *
  * Since: 1.18
- **/
+ */
 PangoOTRuleset *
 pango_ot_ruleset_new_for (PangoOTInfo       *info,
 			  PangoScript        script,
@@ -157,24 +159,23 @@ pango_ot_ruleset_new_for (PangoOTInfo       *info,
 
 /**
  * pango_ot_ruleset_new_from_description:
- * @info: a #PangoOTInfo.
- * @desc: a #PangoOTRulesetDescription.
+ * @info: a `PangoOTInfo`
+ * @desc: a `PangoOTRulesetDescription`
  *
- * Creates a new #PangoOTRuleset for the given OpenType infor and
+ * Creates a new `PangoOTRuleset` for the given OpenType info and
  * matching the given ruleset description.
  *
- * This is a convenience function that calls pango_ot_ruleset_new_for() and
- * adds the static GSUB/GPOS features to the resulting ruleset, followed by
- * adding other features to both GSUB and GPOS.
+ * This is a convenience function that calls [ctor@PangoOT.Ruleset.new_for]
+ * and adds the static GSUB/GPOS features to the resulting ruleset,
+ * followed by adding other features to both GSUB and GPOS.
  *
  * The static feature map members of @desc should be alive as
  * long as @info is.
  *
- * Return value: the newly allocated #PangoOTRuleset, which
- *               should be freed with g_object_unref().
+ * Return value: the newly allocated `PangoOTRuleset`
  *
  * Since: 1.18
- **/
+ */
 PangoOTRuleset *
 pango_ot_ruleset_new_from_description (PangoOTInfo                     *info,
 				       const PangoOTRulesetDescription *desc)
@@ -184,15 +185,15 @@ pango_ot_ruleset_new_from_description (PangoOTInfo                     *info,
 
 /**
  * pango_ot_ruleset_add_feature:
- * @ruleset: a #PangoOTRuleset.
- * @table_type: the table type to add a feature to.
- * @feature_index: the index of the feature to add.
- * @property_bit: the property bit to use for this feature. Used to identify
- *                the glyphs that this feature should be applied to, or
- *                %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
+ * @ruleset: a `PangoOTRuleset`
+ * @table_type: the table type to add a feature to
+ * @feature_index: the index of the feature to add
+ * @property_bit: the property bit to use for this feature. Used to
+ *   identify the glyphs that this feature should be applied to, or
+ *   %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
  *
  * Adds a feature to the ruleset.
- **/
+ */
 void
 pango_ot_ruleset_add_feature (PangoOTRuleset   *ruleset,
 			      PangoOTTableType  table_type,
@@ -203,26 +204,26 @@ pango_ot_ruleset_add_feature (PangoOTRuleset   *ruleset,
 
 /**
  * pango_ot_ruleset_maybe_add_feature:
- * @ruleset: a #PangoOTRuleset.
- * @table_type: the table type to add a feature to.
- * @feature_tag: the tag of the feature to add.
- * @property_bit: the property bit to use for this feature. Used to identify
- *                the glyphs that this feature should be applied to, or
- *                %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
+ * @ruleset: a `PangoOTRuleset`
+ * @table_type: the table type to add a feature to
+ * @feature_tag: the tag of the feature to add
+ * @property_bit: the property bit to use for this feature. Used to
+ *   identify the glyphs that this feature should be applied to, or
+ *   %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs.
  *
  * This is a convenience function that first tries to find the feature
- * using pango_ot_info_find_feature() and the ruleset script and language
- * passed to pango_ot_ruleset_new_for(),
- * and if the feature is found, adds it to the ruleset.
+ * using [method@PangoOT.Info.find_feature] and the ruleset script and
+ * language passed to [ctor@PangoOT.Ruleset.new_for] and if the feature
+ * is found, adds it to the ruleset.
  *
- * If @ruleset was not created using pango_ot_ruleset_new_for(), this function
- * does nothing.
+ * If @ruleset was not created using [ctor@PangoOT.Ruleset.new_for],
+ * this function does nothing.
  *
  * Return value: %TRUE if the feature was found and added to ruleset,
- *               %FALSE otherwise.
+ *   %FALSE otherwise
  *
  * Since: 1.18
- **/
+ */
 gboolean
 pango_ot_ruleset_maybe_add_feature (PangoOTRuleset          *ruleset,
 				    PangoOTTableType         table_type,
@@ -234,21 +235,21 @@ pango_ot_ruleset_maybe_add_feature (PangoOTRuleset          *ruleset,
 
 /**
  * pango_ot_ruleset_maybe_add_features:
- * @ruleset: a #PangoOTRuleset.
- * @table_type: the table type to add features to.
- * @features: array of feature name and property bits to add.
- * @n_features: number of feature records in @features array.
+ * @ruleset: a `PangoOTRuleset`
+ * @table_type: the table type to add features to
+ * @features: array of feature name and property bits to add
+ * @n_features: number of feature records in @features array
  *
- * This is a convenience function that 
- * for each feature in the feature map array @features
- * converts the feature name to a #PangoOTTag feature tag using PANGO_OT_TAG_MAKE()
- * and calls pango_ot_ruleset_maybe_add_feature() on it.
+ * This is a convenience function that for each feature in the feature map
+ * array @features converts the feature name to a `PangoOTTag` feature tag
+ * using PANGO_OT_TAG_MAKE() and calls [method@PangoOT.Ruleset.maybe_add_feature]
+ * on it.
  *
  * Return value: The number of features in @features that were found
- *               and added to @ruleset.
+ *   and added to @ruleset
  *
  * Since: 1.18
- **/
+ */
 guint
 pango_ot_ruleset_maybe_add_features (PangoOTRuleset          *ruleset,
 				     PangoOTTableType         table_type,
@@ -260,18 +261,16 @@ pango_ot_ruleset_maybe_add_features (PangoOTRuleset          *ruleset,
 
 /**
  * pango_ot_ruleset_get_feature_count:
- * @ruleset: a #PangoOTRuleset.
- * @n_gsub_features: (out) (optional): location to store number of
- *   GSUB features, or %NULL.
- * @n_gpos_features: (out) (optional): location to store number of
- *   GPOS features, or %NULL.
+ * @ruleset: a `PangoOTRuleset`
+ * @n_gsub_features: (out) (optional): location to store number of GSUB features
+ * @n_gpos_features: (out) (optional): location to store number of GPOS features
  *
  * Gets the number of GSUB and GPOS features in the ruleset.
  *
- * Return value: Total number of features in the @ruleset.
+ * Return value: Total number of features in the @ruleset
  *
  * Since: 1.18
- **/
+ */
 guint
 pango_ot_ruleset_get_feature_count (const PangoOTRuleset   *ruleset,
 				    guint                  *n_gsub_features,
@@ -282,14 +281,14 @@ pango_ot_ruleset_get_feature_count (const PangoOTRuleset   *ruleset,
 
 /**
  * pango_ot_ruleset_substitute:
- * @ruleset: a #PangoOTRuleset.
- * @buffer: a #PangoOTBuffer.
+ * @ruleset: a `PangoOTRuleset`
+ * @buffer: a `PangoOTBuffer`
  *
- * Performs the OpenType GSUB substitution on @buffer using the features
- * in @ruleset
+ * Performs the OpenType GSUB substitution on @buffer using
+ * the features in @ruleset.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_ruleset_substitute  (const PangoOTRuleset *ruleset,
 			      PangoOTBuffer        *buffer)
@@ -298,14 +297,14 @@ pango_ot_ruleset_substitute  (const PangoOTRuleset *ruleset,
 
 /**
  * pango_ot_ruleset_position:
- * @ruleset: a #PangoOTRuleset.
- * @buffer: a #PangoOTBuffer.
+ * @ruleset: a `PangoOTRuleset`
+ * @buffer: a `PangoOTBuffer`
  *
- * Performs the OpenType GPOS positioning on @buffer using the features
- * in @ruleset
+ * Performs the OpenType GPOS positioning on @buffer using
+ * the features in @ruleset.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_ot_ruleset_position (const PangoOTRuleset *ruleset,
 			   PangoOTBuffer        *buffer)
@@ -319,13 +318,13 @@ pango_ot_ruleset_position (const PangoOTRuleset *ruleset,
  * pango_ot_ruleset_description_hash:
  * @desc: a ruleset description
  *
- * Computes a hash of a #PangoOTRulesetDescription structure suitable
+ * Computes a hash of a `PangoOTRulesetDescription` structure suitable
  * to be used, for example, as an argument to g_hash_table_new().
  *
- * Return value: the hash value.
+ * Return value: the hash value
  *
  * Since: 1.18
- **/
+ */
 guint
 pango_ot_ruleset_description_hash  (const PangoOTRulesetDescription *desc)
 {
@@ -338,16 +337,18 @@ pango_ot_ruleset_description_hash  (const PangoOTRulesetDescription *desc)
  * @desc2: a ruleset description
  *
  * Compares two ruleset descriptions for equality.
+ *
  * Two ruleset descriptions are considered equal if the rulesets
- * they describe are provably identical.  This means that their
- * script, language, and all feature sets should be equal.  For static feature
- * sets, the array addresses are compared directly, while for other
- * features, the list of features is compared one by one.
- * (Two ruleset descriptions may result in identical rulesets
+ * they describe are provably identical. This means that their
+ * script, language, and all feature sets should be equal.
+ *
+ * For static feature sets, the array addresses are compared directly,
+ * while for other features, the list of features is compared one by
+ * one.(Two ruleset descriptions may result in identical rulesets
  * being created, but still compare %FALSE.)
  *
  * Return value: %TRUE if two ruleset descriptions are identical,
- *               %FALSE otherwise.
+ *   %FALSE otherwise
  *
  * Since: 1.18
  **/
@@ -367,15 +368,15 @@ G_DEFINE_BOXED_TYPE (PangoOTRulesetDescription, pango_ot_ruleset_description,
  * @desc: ruleset description to copy
  *
  * Creates a copy of @desc, which should be freed with
- * pango_ot_ruleset_description_free(). Primarily used internally
- * by pango_ot_ruleset_get_for_description() to cache rulesets for
- * ruleset descriptions.
+ * [method@PangoOT.RulesetDescription.free].
+ *
+ * Primarily used internally by [type_func@PangoOT.Ruleset.get_for_description]
+ * to cache rulesets for ruleset descriptions.
  *
- * Return value: the newly allocated #PangoOTRulesetDescription, which
- *               should be freed with pango_ot_ruleset_description_free().
+ * Return value: the newly allocated `PangoOTRulesetDescription`
  *
  * Since: 1.18
- **/
+ */
 PangoOTRulesetDescription *
 pango_ot_ruleset_description_copy  (const PangoOTRulesetDescription *desc)
 {
@@ -392,15 +393,15 @@ pango_ot_ruleset_description_copy  (const PangoOTRulesetDescription *desc)
 
 /**
  * pango_ot_ruleset_description_free:
- * @desc: an allocated #PangoOTRulesetDescription
+ * @desc: an allocated `PangoOTRulesetDescription`
  *
- * Frees a ruleset description allocated by 
+ * Frees a ruleset description allocated by
  * pango_ot_ruleset_description_copy().
  *
  * Since: 1.18
- **/
+ */
 void
-pango_ot_ruleset_description_free  (PangoOTRulesetDescription *desc)
+pango_ot_ruleset_description_free (PangoOTRulesetDescription *desc)
 {
   g_slice_free (PangoOTRulesetDescription, desc);
 }
diff --git a/pango/pango-ot-tag.c b/pango/pango-ot-tag.c
index 5f50b77c..65f9c89d 100644
--- a/pango/pango-ot-tag.c
+++ b/pango/pango-ot-tag.c
@@ -25,7 +25,7 @@
 
 /**
  * pango_ot_tag_from_script:
- * @script: A #PangoScript
+ * @script: A `PangoScript`
  *
  * Finds the OpenType script tag corresponding to @script.
  *
@@ -34,11 +34,11 @@
  * 'DFLT' script tag that is also defined as
  * %PANGO_OT_TAG_DEFAULT_SCRIPT.
  *
- * Note that multiple #PangoScript values may map to the same
+ * Note that multiple `PangoScript` values may map to the same
  * OpenType script tag.  In particular, %PANGO_SCRIPT_HIRAGANA
  * and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'.
  *
- * Return value: #PangoOTTag corresponding to @script or
+ * Return value: `PangoOTTag` corresponding to @script or
  * %PANGO_OT_TAG_DEFAULT_SCRIPT if none found.
  *
  * Since: 1.18
@@ -62,21 +62,21 @@ pango_ot_tag_from_script (PangoScript script)
 
 /**
  * pango_ot_tag_to_script:
- * @script_tag: A #PangoOTTag OpenType script tag
+ * @script_tag: A `PangoOTTag` OpenType script tag
  *
- * Finds the #PangoScript corresponding to @script_tag.
+ * Finds the `PangoScript` corresponding to @script_tag.
  *
  * The 'DFLT' script tag is mapped to %PANGO_SCRIPT_COMMON.
  *
  * Note that an OpenType script tag may correspond to multiple
- * #PangoScript values.  In such cases, the #PangoScript value
+ * `PangoScript` values.  In such cases, the `PangoScript` value
  * with the smallest value is returned.
  * In particular, %PANGO_SCRIPT_HIRAGANA
  * and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'.
  * This function will return %PANGO_SCRIPT_HIRAGANA for
  * 'kana'.
  *
- * Return value: #PangoScript corresponding to @script_tag or
+ * Return value: `PangoScript` corresponding to @script_tag or
  * %PANGO_SCRIPT_UNKNOWN if none found.
  *
  * Since: 1.18
@@ -90,11 +90,11 @@ pango_ot_tag_to_script (PangoOTTag script_tag)
 
 /**
  * pango_ot_tag_from_language:
- * @language: (nullable): A #PangoLanguage, or %NULL
+ * @language: (nullable): A `PangoLanguage`
  *
  * Finds the OpenType language-system tag best describing @language.
  *
- * Return value: #PangoOTTag best matching @language or
+ * Return value: `PangoOTTag` best matching @language or
  * %PANGO_OT_TAG_DEFAULT_LANGUAGE if none found or if @language
  * is %NULL.
  *
@@ -119,12 +119,12 @@ pango_ot_tag_from_language (PangoLanguage *language)
 
 /**
  * pango_ot_tag_to_language:
- * @language_tag: A #PangoOTTag OpenType language-system tag
+ * @language_tag: A `PangoOTTag` OpenType language-system tag
  *
- * Finds a #PangoLanguage corresponding to @language_tag.
+ * Finds a `PangoLanguage` corresponding to @language_tag.
  *
- * Return value: #PangoLanguage best matching @language_tag or
- * #PangoLanguage corresponding to the string "xx" if none found.
+ * Return value: `PangoLanguage` best matching @language_tag or
+ * `PangoLanguage` corresponding to the string "xx" if none found.
  *
  * Since: 1.18
  **/
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index 6390538b..37380e71 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -40,7 +40,7 @@ G_BEGIN_DECLS
 /**
  * PangoOTTag:
  *
- * The #PangoOTTag typedef is used to represent TrueType and OpenType
+ * The `PangoOTTag` typedef is used to represent TrueType and OpenType
  * four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
  * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually.
  */
@@ -53,14 +53,14 @@ typedef guint32 PangoOTTag;
  * @c3: Third character.
  * @c4: Fourth character.
  *
- * Creates a #PangoOTTag from four characters.  This is similar and
+ * Creates a `PangoOTTag` from four characters.  This is similar and
  * compatible with the FT_MAKE_TAG() macro from FreeType.
  */
 /**
  * PANGO_OT_TAG_MAKE_FROM_STRING:
  * @s: The string representation of the tag.
  *
- * Creates a #PangoOTTag from a string. The string should be at least
+ * Creates a `PangoOTTag` from a string. The string should be at least
  * four characters long (pad with space characters if needed), and need
  * not be nul-terminated.  This is a convenience wrapper around
  * PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for
@@ -147,7 +147,7 @@ typedef enum
 /**
  * PANGO_OT_TAG_DEFAULT_SCRIPT:
  *
- * This is a #PangoOTTag representing the special script tag 'DFLT'.  It is
+ * This is a `PangoOTTag` representing the special script tag 'DFLT'.  It is
  * returned as script tag by pango_ot_tag_from_script() if the requested script
  * is not found.
  *
@@ -156,7 +156,7 @@ typedef enum
 /**
  * PANGO_OT_TAG_DEFAULT_LANGUAGE:
  *
- * This is a #PangoOTTag representing a special language tag 'dflt'.  It is
+ * This is a `PangoOTTag` representing a special language tag 'dflt'.  It is
  * returned as language tag by pango_ot_tag_from_language() if the requested
  * language is not found.  It is safe to pass this value to
  * pango_ot_info_find_language() as that function falls back to returning default
@@ -178,7 +178,7 @@ typedef enum
  * @ligID: a ligature index value, set by the OpenType layout engine.
  * @internal: for Pango internal use
  *
- * The #PangoOTGlyph structure represents a single glyph together with
+ * The `PangoOTGlyph` structure represents a single glyph together with
  * information used for OpenType layout processing of the glyph.
  * It contains the following fields.
  */
@@ -199,9 +199,9 @@ struct _PangoOTGlyph
  * @property_bit: the property bit to use for this feature.  See
  * pango_ot_ruleset_add_feature() for details.
  *
- * The #PangoOTFeatureMap typedef is used to represent an OpenType
+ * The `PangoOTFeatureMap` typedef is used to represent an OpenType
  * feature with the property bit associated with it.  The feature tag is
- * represented as a char array instead of a #PangoOTTag for convenience.
+ * represented as a char array instead of a `PangoOTTag` for convenience.
  *
  * Since: 1.18
  */
@@ -213,8 +213,8 @@ struct _PangoOTFeatureMap
 
 /**
  * PangoOTRulesetDescription:
- * @script: a #PangoScript.
- * @language: a #PangoLanguage.
+ * @script: a `PangoScript`
+ * @language: a `PangoLanguage`
  * @static_gsub_features: (nullable): static map of GSUB features,
  * or %NULL.
  * @n_static_gsub_features: length of @static_gsub_features, or 0.
@@ -227,8 +227,8 @@ struct _PangoOTFeatureMap
  * struct.
  * @n_other_features: length of @other_features, or 0.
  *
- * The #PangoOTRuleset structure holds all the information needed
- * to build a complete #PangoOTRuleset from an OpenType font.
+ * The `PangoOTRuleset` structure holds all the information needed
+ * to build a complete `PangoOTRuleset` from an OpenType font.
  * The main use of this struct is to act as the key for a per-font
  * hash of rulesets.  The user populates a ruleset description and
  * gets the ruleset using pango_ot_ruleset_get_for_description()
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index 8f3c9846..c36f1921 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -153,7 +153,7 @@ pango_renderer_finalize (GObject *gobject)
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
- *    in Pango units.
+ *   in Pango units.
  *
  * Draws @layout with the specified `PangoRenderer`.
  *
@@ -557,7 +557,7 @@ draw_shaped_glyphs (PangoRenderer    *renderer,
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
- *    in Pango units.
+ *   in Pango units.
  *
  * Draws @line with the specified `PangoRenderer`.
  *
@@ -750,7 +750,7 @@ pango_renderer_draw_layout_line (PangoRenderer   *renderer,
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
- *    in Pango units.
+ *   in Pango units.
  *
  * Draws the glyphs in @glyphs with the specified `PangoRenderer`.
  *
@@ -801,12 +801,12 @@ pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
 /**
  * pango_renderer_draw_glyph_item:
  * @renderer: a `PangoRenderer`
- * @text: (allow-none): the UTF-8 text that @glyph_item refers to, or %NULL
+ * @text: (nullable): the UTF-8 text that @glyph_item refers to, or %NULL
  * @glyph_item: a `PangoGlyphItem`
  * @x: X position of left edge of baseline, in user space coordinates
  *   in Pango units.
  * @y: Y position of left edge of baseline, in user space coordinates
- *    in Pango units.
+ *   in Pango units.
  *
  * Draws the glyphs in @glyph_item with the specified `PangoRenderer`,
  * embedding the text associated with the glyphs in the output if the
@@ -1206,7 +1206,7 @@ pango_renderer_draw_trapezoid (PangoRenderer   *renderer,
 /**
  * pango_renderer_draw_glyph:
  * @renderer: a `PangoRenderer`
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  * @glyph: the glyph index of a single glyph
  * @x: X coordinate of left edge of baseline of glyph
  * @y: Y coordinate of left edge of baseline of glyph
@@ -1237,16 +1237,17 @@ pango_renderer_draw_glyph (PangoRenderer *renderer,
  * @renderer: a `PangoRenderer`
  *
  * Does initial setup before rendering operations on @renderer.
- * 
+ *
  * [method@Pango.Renderer.deactivate] should be called when done drawing.
  * Calls such as [method@Pango.Renderer.draw_layout] automatically
- * activate the layout before drawing on it. Calls to
- * `pango_renderer_activate()` and `pango_renderer_deactivate()`
- * can be nested and the renderer will only be initialized and
- * deinitialized once.
+ * activate the layout before drawing on it.
+ *
+ * Calls to [method@Pango.Renderer.activate] and
+ * [method@Pango.Renderer.deactivate] can be nested and the
+ * renderer will only be initialized and deinitialized once.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_renderer_activate (PangoRenderer *renderer)
 {
@@ -1288,7 +1289,7 @@ pango_renderer_deactivate (PangoRenderer *renderer)
  * pango_renderer_set_color:
  * @renderer: a `PangoRenderer`
  * @part: the part to change the color of
- * @color: (allow-none): the new color or %NULL to unset the current color
+ * @color: (nullable): the new color or %NULL to unset the current color
  *
  * Sets the color for part of the rendering.
  *
@@ -1552,7 +1553,7 @@ pango_renderer_default_prepare_run (PangoRenderer  *renderer,
 /**
  * pango_renderer_set_matrix:
  * @renderer: a `PangoRenderer`
- * @matrix: (allow-none): a `PangoMatrix`, or %NULL to unset any existing matrix.
+ * @matrix: (nullable): a `PangoMatrix`, or %NULL to unset any existing matrix
  *  (No matrix set is the same as setting the identity matrix.)
  *
  * Sets the transformation matrix that will be applied when rendering.
diff --git a/pango/pango-renderer.h b/pango/pango-renderer.h
index 98c4cfb0..16a1bbd4 100644
--- a/pango/pango-renderer.h
+++ b/pango/pango-renderer.h
@@ -44,7 +44,7 @@ typedef struct _PangoRendererPrivate PangoRendererPrivate;
  * @PANGO_RENDER_PART_STRIKETHROUGH: strikethrough lines
  * @PANGO_RENDER_PART_OVERLINE: overlines
  *
- * #PangoRenderPart defines different items to render for such
+ * `PangoRenderPart` defines different items to render for such
  * purposes as setting colors.
  *
  * Since: 1.8
@@ -62,8 +62,8 @@ typedef enum
 /**
  * PangoRenderer:
  * @matrix: (nullable): the current transformation matrix for
- *    the Renderer; may be %NULL, which should be treated the
- *    same as the identity matrix.
+ *   the Renderer; may be %NULL, which should be treated the
+ *   same as the identity matrix.
  *
  * `PangoRenderer` is a base class for objects that can render text
  * provided as `PangoGlyphString` or `PangoLayout`.
@@ -92,12 +92,12 @@ struct _PangoRenderer
 
 /**
  * PangoRendererClass:
- * @draw_glyphs: draws a #PangoGlyphString
+ * @draw_glyphs: draws a `PangoGlyphString`
  * @draw_rectangle: draws a rectangle
  * @draw_error_underline: draws a squiggly line that approximately
  * covers the given rectangle in the style of an underline used to
  * indicate a spelling error.
- * @draw_shape: draw content for a glyph shaped with #PangoAttrShape.
+ * @draw_shape: draw content for a glyph shaped with `PangoAttrShape`
  *   @x, @y are the coordinates of the left edge of the baseline,
  *   in user coordinates.
  * @draw_trapezoid: draws a trapezoidal filled area
@@ -107,9 +107,9 @@ struct _PangoRenderer
  * @begin: Do renderer-specific initialization before drawing
  * @end: Do renderer-specific cleanup after drawing
  * @prepare_run: updates the renderer for a new run
- * @draw_glyph_item: draws a #PangoGlyphItem
+ * @draw_glyph_item: draws a `PangoGlyphItem`
  *
- * Class structure for #PangoRenderer.
+ * Class structure for `PangoRenderer`.
  *
  * The following vfuncs take user space coordinates in Pango units
  * and have default implementations:
diff --git a/pango/pango-script.c b/pango/pango-script.c
index 7116a0a4..fc7c6332 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -122,14 +122,16 @@ _pango_script_iter_init (PangoScriptIter *iter,
  * @text: a UTF-8 string
  * @length: length of @text, or -1 if @text is nul-terminated.
  *
- * Create a new #PangoScriptIter, used to break a string of
- * Unicode text into runs by Unicode script. No copy is made of
- * @text, so the caller needs to make sure it remains valid until
- * the iterator is freed with pango_script_iter_free().
+ * Create a new `PangoScriptIter`, used to break a string of
+ * Unicode text into runs by Unicode script.
+ *
+ * No copy is made of @text, so the caller needs to make
+ * sure it remains valid until the iterator is freed with
+ * [method@Pango.ScriptIter.free].
  *
  * Return value: the new script iterator, initialized
  *  to point at the first range in the text, which should be
- *  freed with pango_script_iter_free(). If the string is
+ *  freed with [method@Pango.ScriptIter.free]. If the string is
  *  empty, it will point at an empty range.
  *
  * Since: 1.4
@@ -154,12 +156,12 @@ _pango_script_iter_fini (PangoScriptIter *iter)
 
 /**
  * pango_script_iter_free:
- * @iter: a #PangoScriptIter
+ * @iter: a `PangoScriptIter`
  *
- * Frees a #PangoScriptIter created with pango_script_iter_new().
+ * Frees a `PangoScriptIter`.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_script_iter_free (PangoScriptIter *iter)
 {
@@ -169,22 +171,22 @@ pango_script_iter_free (PangoScriptIter *iter)
 
 /**
  * pango_script_iter_get_range:
- * @iter: a #PangoScriptIter
- * @start: (out) (allow-none): location to store start position of the range, or %NULL
- * @end: (out) (allow-none): location to store end position of the range, or %NULL
- * @script: (out) (allow-none): location to store script for range, or %NULL
+ * @iter: a `PangoScriptIter`
+ * @start: (out) (optional): location to store start position of the range
+ * @end: (out) (optional): location to store end position of the range
+ * @script: (out) (optional): location to store script for range
  *
  * Gets information about the range to which @iter currently points.
  * The range is the set of locations p where *start <= p < *end.
  * (That is, it doesn't include the character stored at *end)
  *
  * Note that while the type of the @script argument is declared
- * as PangoScript, as of Pango 1.18, this function simply returns
+ * as `PangoScript`, as of Pango 1.18, this function simply returns
  * GUnicodeScript values. Callers must be prepared to handle unknown
  * values.
  *
  * Since: 1.4
- **/
+ */
 void
 pango_script_iter_get_range (PangoScriptIter  *iter,
                              const char      **start,
@@ -292,16 +294,17 @@ get_pair_index (gunichar ch)
 
 /**
  * pango_script_iter_next:
- * @iter: a #PangoScriptIter
+ * @iter: a `PangoScriptIter`
+ *
+ * Advances a `PangoScriptIter` to the next range.
  *
- * Advances a #PangoScriptIter to the next range. If @iter
- * is already at the end, it is left unchanged and %FALSE
- * is returned.
+ * If @iter is already at the end, it is left unchanged
+ * and %FALSE is returned.
  *
- * Return value: %TRUE if @iter was successfully advanced.
+ * Return value: %TRUE if @iter was successfully advanced
  *
  * Since: 1.4
- **/
+ */
 gboolean
 pango_script_iter_next (PangoScriptIter *iter)
 {
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 2c2717ee..1bb65621 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -292,8 +292,8 @@ pango_tab_array_set_tab (PangoTabArray *tab_array,
  * pango_tab_array_get_tab:
  * @tab_array: a `PangoTabArray`
  * @tab_index: tab stop index
- * @alignment: (out) (allow-none): location to store alignment, or %NULL
- * @location: (out) (allow-none): location to store tab position, or %NULL
+ * @alignment: (out) (optional): location to store alignment, or %NULL
+ * @location: (out) (optional): location to store tab position, or %NULL
  *
  * Gets the alignment and position of a tab stop.
  */
@@ -317,9 +317,9 @@ pango_tab_array_get_tab (PangoTabArray *tab_array,
 /**
  * pango_tab_array_get_tabs:
  * @tab_array: a `PangoTabArray`
- * @alignments: (out) (allow-none): location to store an array of tab
+ * @alignments: (out) (optional): location to store an array of tab
  *   stop alignments, or %NULL
- * @locations: (out) (allow-none) (array): location to store an array
+ * @locations: (out) (optional) (array): location to store an array
  *   of tab positions, or %NULL
  *
  * If non-%NULL, @alignments and @locations are filled with allocated
diff --git a/pango/pango-types.h b/pango/pango-types.h
index 2998d8ec..a7bcd747 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -150,41 +150,49 @@ struct _PangoRectangle
  */
 /**
  * PANGO_ASCENT:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
  *
- * Extracts the *ascent* from a #PangoRectangle
- * representing glyph extents. The ascent is the distance from the
- * baseline to the highest point of the character. This is positive if the
+ * Extracts the *ascent* from a `PangoRectangle`
+ * representing glyph extents.
+ *
+ * The ascent is the distance from the baseline to the
+ * highest point of the character. This is positive if the
  * glyph ascends above the baseline.
  */
 /**
  * PANGO_DESCENT:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
+ *
+ * Extracts the *descent* from a `PangoRectangle`
+ * representing glyph extents.
  *
- * Extracts the *descent* from a #PangoRectangle
- * representing glyph extents. The descent is the distance from the
- * baseline to the lowest point of the character. This is positive if the
+ * The descent is the distance from the baseline to the
+ * lowest point of the character. This is positive if the
  * glyph descends below the baseline.
  */
 /**
  * PANGO_LBEARING:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
  *
- * Extracts the *left bearing* from a #PangoRectangle
- * representing glyph extents. The left bearing is the distance from the
- * horizontal origin to the farthest left point of the character.
- * This is positive for characters drawn completely to the right of the
- * glyph origin.
+ * Extracts the *left bearing* from a `PangoRectangle`
+ * representing glyph extents.
+ *
+ * The left bearing is the distance from the horizontal
+ * origin to the farthest left point of the character.
+ * This is positive for characters drawn completely to
+ * the right of the glyph origin.
  */
 /**
  * PANGO_RBEARING:
- * @rect: a #PangoRectangle
+ * @rect: a `PangoRectangle`
+ *
+ * Extracts the *right bearing* from a `PangoRectangle`
+ * representing glyph extents.
  *
- * Extracts the *right bearing* from a #PangoRectangle
- * representing glyph extents. The right bearing is the distance from the
- * horizontal origin to the farthest right point of the character.
- * This is positive except for characters drawn completely to the left of the
- * horizontal origin.
+ * The right bearing is the distance from the horizontal
+ * origin to the farthest right point of the character.
+ * This is positive except for characters drawn completely
+ * to the left of the horizontal origin.
  */
 #define PANGO_ASCENT(rect) (-(rect).y)
 #define PANGO_DESCENT(rect) ((rect).y + (rect).height)
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 5283da35..0057859e 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -61,7 +61,7 @@
  * Returns: The encoded version of Pango library available at run time.
  *
  * Since: 1.16
- **/
+ */
 int
 pango_version (void)
 {
@@ -81,7 +81,7 @@ pango_version (void)
  *   be modified or freed.
  *
  * Since: 1.16
- **/
+ */
 const char *
 pango_version_string (void)
 {
@@ -90,9 +90,9 @@ pango_version_string (void)
 
 /**
  * pango_version_check:
- * @required_major: the required major version.
- * @required_minor: the required minor version.
- * @required_micro: the required major version.
+ * @required_major: the required major version
+ * @required_minor: the required minor version
+ * @required_micro: the required major version
  *
  * Checks that the Pango library in use is compatible with the
  * given version.
@@ -118,7 +118,7 @@ pango_version_string (void)
  *   be modified or freed.
  *
  * Since: 1.16
- **/
+ */
 const gchar*
 pango_version_check (int required_major,
 		     int required_minor,
@@ -145,7 +145,7 @@ pango_version_check (int required_major,
  * Return value: A newly-allocated string that must be freed with g_free()
  *
  * Deprecated: 1.38
- **/
+ */
 char *
 pango_trim_string (const char *str)
 {
@@ -177,10 +177,10 @@ _pango_trim_string (const char *str)
  * white space and substituting ~/ with $HOME/.
  *
  * Return value: (transfer full) (array zero-terminated=1): a list of
- * strings to be freed with g_strfreev()
+ *   strings to be freed with g_strfreev()
  *
  * Deprecated: 1.38
- **/
+ */
 char **
 pango_split_file_list (const char *str)
 {
@@ -238,7 +238,7 @@ pango_split_file_list (const char *str)
 /**
  * pango_read_line:
  * @stream: a stdio stream
- * @str: #GString buffer into which to write the result
+ * @str: `GString` buffer into which to write the result
  *
  * Reads an entire line from a file into a buffer.
  *
@@ -254,7 +254,7 @@ pango_split_file_list (const char *str)
  *   a line number counter which doesn't combine lines with '\')
  *
  * Deprecated: 1.38
- **/
+ */
 gint
 pango_read_line (FILE *stream, GString *str)
 {
@@ -355,10 +355,10 @@ pango_read_line (FILE *stream, GString *str)
  * Skips 0 or more characters of white space.
  *
  * Return value: %FALSE if skipping the white space leaves
- * the position at a '\0' character.
+ *   the position at a '\0' character.
  *
  * Deprecated: 1.38
- **/
+ */
 gboolean
 pango_skip_space (const char **pos)
 {
@@ -375,17 +375,17 @@ pango_skip_space (const char **pos)
 /**
  * pango_scan_word:
  * @pos: (inout): in/out string position
- * @out: a #GString into which to write the result
+ * @out: a `GString` into which to write the result
  *
- * Scans a word into a #GString buffer.
+ * Scans a word into a `GString` buffer.
  *
  * A word consists of [A-Za-z_] followed by zero or more
  * [A-Za-z_0-9]. Leading white space is skipped.
  *
- * Return value: %FALSE if a parse error occurred.
+ * Return value: %FALSE if a parse error occurred
  *
  * Deprecated: 1.38
- **/
+ */
 gboolean
 pango_scan_word (const char **pos, GString *out)
 {
@@ -420,18 +420,18 @@ pango_scan_word (const char **pos, GString *out)
 /**
  * pango_scan_string:
  * @pos: (inout): in/out string position
- * @out: a #GString into which to write the result
+ * @out: a `GString` into which to write the result
  *
- * Scans a string into a #GString buffer.
+ * Scans a string into a `GString` buffer.
  *
  * The string may either be a sequence of non-white-space characters,
  * or a quoted string with '"'. Instead a quoted string, '\"' represents
  * a literal quote. Leading white space outside of quotes is skipped.
  *
- * Return value: %FALSE if a parse error occurred.
+ * Return value: %FALSE if a parse error occurred
  *
  * Deprecated: 1.38
- **/
+ */
 gboolean
 pango_scan_string (const char **pos, GString *out)
 {
@@ -519,10 +519,10 @@ pango_scan_string (const char **pos, GString *out)
  *
  * Leading white space is skipped.
  *
- * Return value: %FALSE if a parse error occurred.
+ * Return value: %FALSE if a parse error occurred
  *
  * Deprecated: 1.38
- **/
+ */
 gboolean
 pango_scan_int (const char **pos, int *out)
 {
@@ -556,14 +556,14 @@ _pango_scan_int (const char **pos, int *out)
 
 /**
  * pango_config_key_get_system:
- * @key: Key to look up, in the form "SECTION/KEY".
+ * @key: Key to look up, in the form "SECTION/KEY"
  *
  * Do not use.  Does not do anything.
  *
  * Return value: %NULL
  *
  * Deprecated: 1.38
- **/
+ */
 char *
 pango_config_key_get_system (const char *key)
 {
@@ -572,14 +572,14 @@ pango_config_key_get_system (const char *key)
 
 /**
  * pango_config_key_get:
- * @key: Key to look up, in the form "SECTION/KEY".
+ * @key: Key to look up, in the form "SECTION/KEY"
  *
  * Do not use.  Does not do anything.
  *
  * Return value: %NULL
  *
  * Deprecated: 1.38
- **/
+ */
 char *
 pango_config_key_get (const char *key)
 {
@@ -672,28 +672,30 @@ parse_int (const char *word,
 
 /**
  * pango_parse_enum:
- * @type: enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE.
- * @str: (allow-none): string to parse.  May be %NULL.
- * @value: (out) (allow-none): integer to store the result in, or %NULL.
- * @warn: if %TRUE, issue a g_warning() on bad input.
- * @possible_values: (out) (allow-none): place to store list of possible values on failure, or %NULL.
+ * @type: enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE
+ * @str: (nullable): string to parse
+ * @value: (out) (optional): integer to store the result in
+ * @warn: if %TRUE, issue a g_warning() on bad input
+ * @possible_values: (out) (optional): place to store list of possible
+ *   values on failure
  *
  * Parses an enum type and stores the result in @value.
  *
- * If @str does not match the nick name of any of the possible values for the
- * enum and is not an integer, %FALSE is returned, a warning is issued
- * if @warn is %TRUE, and a
- * string representing the list of possible values is stored in
- * @possible_values.  The list is slash-separated, eg.
- * "none/start/middle/end".  If failed and @possible_values is not %NULL,
- * returned string should be freed using g_free().
+ * If @str does not match the nick name of any of the possible values
+ * for the enum and is not an integer, %FALSE is returned, a warning
+ * is issued if @warn is %TRUE, and a string representing the list of
+ * possible values is stored in @possible_values. The list is
+ * slash-separated, eg. "none/start/middle/end".
  *
- * Return value: %TRUE if @str was successfully parsed.
+ * If failed and @possible_values is not %NULL, returned string should
+ * be freed using g_free().
+ *
+ * Return value: %TRUE if @str was successfully parsed
  *
  * Deprecated: 1.38
  *
  * Since: 1.16
- **/
+ */
 gboolean
 pango_parse_enum (GType       type,
 		  const char *str,
@@ -822,10 +824,10 @@ pango_parse_flags (GType        type,
 
 /**
  * pango_lookup_aliases:
- * @fontname: an ascii string
- * @families: (out) (array length=n_families): will be set to an array of font family names.
- *    this array is owned by pango and should not be freed.
- * @n_families: (out): will be set to the length of the @families array.
+ * @fontname: an ASCII string
+ * @families: (out) (array length=n_families): will be set to an array of
+ *   font family names. This array is owned by Pango and should not be freed
+ * @n_families: (out): will be set to the length of the @families array
  *
  * Look up all user defined aliases for the alias @fontname.
  *
@@ -848,14 +850,14 @@ pango_lookup_aliases (const char   *fontname,
 
 /**
  * pango_find_base_dir:
- * @text:   the text to process. Must be valid UTF-8
+ * @text: the text to process. Must be valid UTF-8
  * @length: length of @text in bytes (may be -1 if @text is nul-terminated)
  *
  * Searches a string the first character that has a strong
  * direction, according to the Unicode bidirectional algorithm.
  *
  * Return value: The direction corresponding to the first strong character.
- * If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned.
+ *   If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned.
  *
  * Since: 1.4
  */
@@ -1016,8 +1018,8 @@ pango_units_to_double (int i)
 
 /**
  * pango_extents_to_pixels:
- * @inclusive: (allow-none): rectangle to round to pixels inclusively, or %NULL.
- * @nearest: (allow-none): rectangle to round to nearest pixels, or %NULL.
+ * @inclusive: (nullable): rectangle to round to pixels inclusively
+ * @nearest: (nullable): rectangle to round to nearest pixels
  *
  * Converts extents from Pango units to device units.
  *
@@ -1038,7 +1040,7 @@ pango_units_to_double (int i)
  * as @nearest.
  *
  * Since: 1.16
- **/
+ */
 void
 pango_extents_to_pixels (PangoRectangle *inclusive,
 			 PangoRectangle *nearest)
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index d880f1b3..08a90678 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -164,9 +164,8 @@ _pango_cairo_update_context (cairo_t      *cr,
  * match the current transformation and target surface of a Cairo
  * context.
  *
- * If any layouts have been created for the context,
- * it's necessary to call [method@Pango.Layout.context_changed] on those
- * layouts.
+ * If any layouts have been created for the context, it's necessary
+ * to call [method@Pango.Layout.context_changed] on those layouts.
  *
  * Since: 1.10
  */
@@ -189,10 +188,9 @@ pango_cairo_update_context (cairo_t      *cr,
  *
  * Sets the resolution for the context.
  *
- * This is a scale factor between
- * points specified in a `PangoFontDescription` and Cairo units. The
- * default value is 96, meaning that a 10 point font will be 13
- * units high. (10 * 96. / 72. = 13.3).
+ * This is a scale factor between points specified in a `PangoFontDescription`
+ * and Cairo units. The default value is 96, meaning that a 10 point font will
+ * be 13 units high. (10 * 96. / 72. = 13.3).
  *
  * Since: 1.10
  */
@@ -209,6 +207,7 @@ pango_cairo_context_set_resolution (PangoContext *context,
  * @context: a `PangoContext`, from a pangocairo font map
  *
  * Gets the resolution for the context.
+ *
  * See [func@PangoCairo.context_set_resolution]
  *
  * Return value: the resolution in "dots per inch". A negative value will
@@ -289,9 +288,8 @@ pango_cairo_context_set_font_options (PangoContext               *context,
  * Retrieves any font rendering options previously set with
  * [func@PangoCairo.context_set_font_options].
  *
- * This function
- * does not report options that are derived from the target
- * surface by [func@update_context].
+ * This function does not report options that are derived from
+ * the target surface by [func@update_context].
  *
  * Return value: (nullable): the font options previously set on the
  *   context, or %NULL if no options have been set. This value is
@@ -347,10 +345,10 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
  * pango_cairo_context_set_shape_renderer:
  * @context: a `PangoContext`, from a pangocairo font map
  * @func: (nullable): Callback function for rendering attributes of
- *        type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
- * @data: User data that will be passed to @func.
- * @dnotify: Callback that will be called when the
- *           context is freed to release @data, or %NULL.
+ *   type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
+ * @data: (nullable): User data that will be passed to @func.
+ * @dnotify: (nullable): Callback that will be called when the
+ *   context is freed to release @data
  *
  * Sets callback function for context to use for rendering attributes
  * of type %PANGO_ATTR_SHAPE.
@@ -382,7 +380,7 @@ pango_cairo_context_set_shape_renderer (PangoContext                *context,
 /**
  * pango_cairo_context_get_shape_renderer: (skip)
  * @context: a `PangoContext`, from a pangocairo font map
- * @data: Pointer to #gpointer to return user data
+ * @data: Pointer to `gpointer` to return user data
  *
  * Sets callback function for context to use for rendering attributes
  * of type %PANGO_ATTR_SHAPE.
@@ -438,8 +436,7 @@ pango_cairo_context_get_shape_renderer (PangoContext *context,
  * create a layout for use with @cr and do not need to access `PangoContext`
  * directly, you can use [func@create_layout] instead.
  *
- * Return value: (transfer full): the newly created `PangoContext`.
- *   Free with g_object_unref().
+ * Return value: (transfer full): the newly created `PangoContext`
  *
  * Since: 1.22
  */
@@ -465,9 +462,8 @@ pango_cairo_create_context (cairo_t *cr)
  * Creates a layout object set up to match the current transformation
  * and target surface of the Cairo context.
  *
- * This layout can then be
- * used for text measurement with functions like
- * [method@Pango.Layout.get_size] or drawing with functions like
+ * This layout can then be used for text measurement with functions
+ * like [method@Pango.Layout.get_size] or drawing with functions like
  * [func@show_layout]. If you change the transformation or target
  * surface for @cr, you need to call [func@update_layout].
  *
@@ -476,8 +472,7 @@ pango_cairo_create_context (cairo_t *cr)
  * `PangoContext` object for each layout. This might matter in an
  * application that was laying out large amounts of text.
  *
- * Return value: (transfer full): the newly created `PangoLayout`.
- *   Free with g_object_unref().
+ * Return value: (transfer full): the newly created `PangoLayout`
  *
  * Since: 1.10
  */
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 9e3cfab8..2c552ba1 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -1203,8 +1203,8 @@ pango_cairo_glyph_string_path (cairo_t          *cr,
  * Adds the text in `PangoLayoutLine` to the current path in the
  * specified cairo context.
  *
- * The origin of the glyphs (the left edge
- * of the line) will be at the current point of the cairo context.
+ * The origin of the glyphs (the left edge of the line) will be
+ * at the current point of the cairo context.
  *
  * Since: 1.10
  */
@@ -1226,8 +1226,8 @@ pango_cairo_layout_line_path (cairo_t          *cr,
  * Adds the text in a `PangoLayout` to the current path in the
  * specified cairo context.
  *
- * The top-left corner of the `PangoLayout`
- * will be at the current point of the cairo context.
+ * The top-left corner of the `PangoLayout` will be at the
+ * current point of the cairo context.
  *
  * Since: 1.10
  */
@@ -1253,9 +1253,8 @@ pango_cairo_layout_path (cairo_t     *cr,
  * approximately covers the given rectangle in the style of an underline used
  * to indicate a spelling error.
  *
- * The width of the underline is rounded to an
- * integer number of up/down segments and the resulting rectangle is centered
- * in the original rectangle.
+ * The width of the underline is rounded to an integer number of up/down
+ * segments and the resulting rectangle is centered in the original rectangle.
  *
  * Since: 1.14
  */
diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c
index 5f9cf2df..ccb3f674 100644
--- a/pango/pangocoretext.c
+++ b/pango/pangocoretext.c
@@ -266,7 +266,7 @@ _pango_core_text_font_set_ctfont (PangoCoreTextFont *font,
 
 /**
  * pango_core_text_font_get_ctfont:
- * @font: A #PangoCoreTextFont
+ * @font: A `PangoCoreTextFont`
  *
  * Returns the CTFontRef of a font.
  *
diff --git a/pango/pangofc-font-private.h b/pango/pangofc-font-private.h
index 588bd512..532aed2f 100644
--- a/pango/pangofc-font-private.h
+++ b/pango/pangofc-font-private.h
@@ -32,7 +32,7 @@ G_BEGIN_DECLS
  *
  * A string constant used to identify shape engines that work
  * with the fontconfig based backends. See the @engine_type field
- * of #PangoEngineInfo.
+ * of `PangoEngineInfo`.
  **/
 #define PANGO_RENDER_TYPE_FC "PangoRenderFc"
 
@@ -46,7 +46,7 @@ G_BEGIN_DECLS
  *  the reference count for the face by one.
  * @unlock_face: Decreases the reference count for the
  *  FT_Face of the font by one. When the count is zero,
- *  the #PangoFcFont subclass is allowed to free the
+ *  the `PangoFcFont` subclass is allowed to free the
  *  FT_Face.
  * @has_char: Return %TRUE if the the font contains a glyph
  *   corresponding to the specified character.
@@ -59,7 +59,7 @@ G_BEGIN_DECLS
  *   shutdown code that needs to be done when
  *   pango_fc_font_map_shutdown is called.  May be %NULL.
  *
- * Class structure for #PangoFcFont.
+ * Class structure for `PangoFcFont`.
  **/
 struct _PangoFcFontClass
 {
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 5a164343..2bd84276 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -567,7 +567,7 @@ pango_fc_font_unlock_face (PangoFcFont *font)
 
 /**
  * pango_fc_font_has_char:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  * @wc: Unicode codepoint to look up
  *
  * Determines whether @font has a glyph for the codepoint @wc.
@@ -575,7 +575,7 @@ pango_fc_font_unlock_face (PangoFcFont *font)
  * Return value: %TRUE if @font has the requested codepoint.
  *
  * Since: 1.4
- * Deprecated: 1.44: Use pango_font_has_char()
+ * Deprecated: 1.44: Use [method@Pango.Font.has_char]
  */
 gboolean
 pango_fc_font_has_char (PangoFcFont *font,
@@ -597,7 +597,7 @@ pango_fc_font_has_char (PangoFcFont *font,
 
 /**
  * pango_fc_font_get_glyph:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  * @wc: Unicode character to look up
  *
  * Gets the glyph index for a given Unicode character
@@ -632,11 +632,11 @@ pango_fc_font_get_glyph (PangoFcFont *font,
 
 /**
  * pango_fc_font_get_unknown_glyph:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  * @wc: the Unicode character for which a glyph is needed.
  *
- * Returns the index of a glyph suitable for drawing @wc as an
- * unknown character.
+ * Returns the index of a glyph suitable for drawing @wc
+ * as an unknown character.
  *
  * Use PANGO_GET_UNKNOWN_GLYPH() instead.
  *
@@ -665,7 +665,7 @@ _pango_fc_font_shutdown (PangoFcFont *font)
 
 /**
  * pango_fc_font_kern_glyphs:
- * @font: a #PangoFcFont
+ * @font: a `PangoFcFont`
  * @glyphs: a `PangoGlyphString`
  *
  * This function used to adjust each adjacent pair of glyphs
@@ -1043,7 +1043,7 @@ done:
  * and its fontmap are valid.
  *
  * Returns: (transfer none) (nullable): a %NULL-terminated
- *    array of `PangoLanguage`*
+ *   array of `PangoLanguage`*
  *
  * Since: 1.48
  */
diff --git a/pango/pangofc-fontmap-private.h b/pango/pangofc-fontmap-private.h
index b32982f2..e081147d 100644
--- a/pango/pangofc-fontmap-private.h
+++ b/pango/pangofc-fontmap-private.h
@@ -83,11 +83,11 @@ const char        *pango_fc_font_key_get_variations  (const PangoFcFontKey *key)
 /**
  * PangoFcFontMap:
  *
- * #PangoFcFontMap is a base class for font map implementations
+ * `PangoFcFontMap` is a base class for font map implementations
  * using the Fontconfig and FreeType libraries. To create a new
  * backend using Fontconfig and FreeType, you derive from this class
  * and implement a new_font() virtual function that creates an
- * instance deriving from #PangoFcFont.
+ * instance deriving from `PangoFcFont`.
  **/
 struct _PangoFcFontMap
 {
@@ -111,10 +111,10 @@ struct _PangoFcFontMap
  *  Implementations must call substitute_func if it is
  *  defined. May be  %NULL. Deprecated in favor of
  *  @font_key_substitute().
- * @new_font: Creates a new #PangoFcFont for the specified
+ * @new_font: Creates a new `PangoFcFont` for the specified
  *  pattern of the appropriate type for this font map. The
  *  @pattern argument must be passed to the "pattern" property
- *  of #PangoFcFont when you call g_object_new(). Deprecated
+ *  of `PangoFcFont` when you call g_object_new(). Deprecated
  *  in favor of @create_font().
  * @get_resolution: Gets the resolution (the scale factor
  *  between logical and absolute font sizes) that the backend
@@ -138,16 +138,16 @@ struct _PangoFcFontMap
  *  #FcPattern. This will be called prior to creating a font
  *  for the pattern. Implementations must call substitute_func
  *  if it is defined. May be %NULL.  (Since: 1.24)
- * @create_font: (nullable): Creates a new #PangoFcFont for
+ * @create_font: (nullable): Creates a new `PangoFcFont` for
  *  the specified pattern of the appropriate type for this
  *  font map using information from the font key that is
  *  passed in. The @pattern member of @font_key can be
  *  retrieved using pango_fc_font_key_get_pattern() and must
- *  be passed to the "pattern" property of #PangoFcFont when
+ *  be passed to the "pattern" property of `PangoFcFont` when
  *  you call g_object_new().  If %NULL, new_font() is used.
  *  (Since: 1.24)
  *
- * Class structure for #PangoFcFontMap.
+ * Class structure for `PangoFcFontMap`.
  **/
 struct _PangoFcFontMapClass
 {
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 8ae9250e..074bca20 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -119,10 +119,9 @@ typedef void (*PangoFcSubstituteFunc) (FcPattern *pattern,
 /**
  * pango_fc_font_map_set_default_substitute:
  * @fontmap: a `PangoFcFontMap`
- * @func: function to call to to do final config tweaking
- *        on `FcPattern` objects.
+ * @func: function to call to to do final config tweaking on `FcPattern` objects
  * @data: data to pass to @func
- * @notify: function to call when @data is no longer used.
+ * @notify: function to call when @data is no longer used
  *
  * Sets a function that will be called to do final configuration
  * substitution on a `FcPattern` before it is used to load
diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c
index 45ac5820..f2da8e7f 100644
--- a/pango/pangoft2-render.c
+++ b/pango/pangoft2-render.c
@@ -579,16 +579,18 @@ pango_ft2_renderer_draw_trapezoid (PangoRenderer   *renderer,
 
 /**
  * pango_ft2_render_layout_subpixel:
- * @bitmap:    a FT_Bitmap to render the layout onto
- * @layout:    a #PangoLayout
- * @x:         the X position of the left of the layout (in Pango units)
- * @y:         the Y position of the top of the layout (in Pango units)
+ * @bitmap: a FT_Bitmap to render the layout onto
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in Pango units)
+ * @y: the Y position of the top of the layout (in Pango units)
  *
- * Render a #PangoLayout onto a FreeType2 bitmap, with he
+ * Render a `PangoLayout` onto a FreeType2 bitmap, with he
  * location specified in fixed-point Pango units rather than
- * pixels. (Using this will avoid extra inaccuracies from
- * rounding to integer pixels multiple times, even if the
- * final glyph positions are integers.)
+ * pixels.
+ *
+ * (Using this will avoid extra inaccuracies from rounding
+ * to integer pixels multiple times, even if the final glyph
+ * positions are integers.)
  *
  * Since: 1.6
  */
@@ -616,12 +618,12 @@ pango_ft2_render_layout_subpixel (FT_Bitmap   *bitmap,
 
 /**
  * pango_ft2_render_layout:
- * @bitmap:    a FT_Bitmap to render the layout onto
- * @layout:    a #PangoLayout
- * @x:         the X position of the left of the layout (in pixels)
- * @y:         the Y position of the top of the layout (in pixels)
+ * @bitmap: a FT_Bitmap to render the layout onto
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in pixels)
+ * @y: the Y position of the top of the layout (in pixels)
  *
- * Render a #PangoLayout onto a FreeType2 bitmap
+ * Render a `PangoLayout` onto a FreeType2 bitmap
  */
 void
 pango_ft2_render_layout (FT_Bitmap   *bitmap,
@@ -634,16 +636,18 @@ pango_ft2_render_layout (FT_Bitmap   *bitmap,
 
 /**
  * pango_ft2_render_layout_line_subpixel:
- * @bitmap:    a FT_Bitmap to render the line onto
- * @line:      a #PangoLayoutLine
- * @x:         the x position of start of string (in Pango units)
- * @y:         the y position of baseline (in Pango units)
+ * @bitmap: a FT_Bitmap to render the line onto
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in Pango units)
+ * @y: the y position of baseline (in Pango units)
  *
- * Render a #PangoLayoutLine onto a FreeType2 bitmap, with he
+ * Render a `PangoLayoutLine` onto a FreeType2 bitmap, with he
  * location specified in fixed-point Pango units rather than
- * pixels. (Using this will avoid extra inaccuracies from
- * rounding to integer pixels multiple times, even if the
- * final glyph positions are integers.)
+ * pixels.
+ *
+ * (Using this will avoid extra inaccuracies from rounding
+ * to integer pixels multiple times, even if the final glyph
+ * positions are integers.)
  *
  * Since: 1.6
  */
@@ -671,12 +675,12 @@ pango_ft2_render_layout_line_subpixel (FT_Bitmap       *bitmap,
 
 /**
  * pango_ft2_render_layout_line:
- * @bitmap:    a FT_Bitmap to render the line onto
- * @line:      a #PangoLayoutLine
- * @x:         the x position of start of string (in pixels)
- * @y:         the y position of baseline (in pixels)
+ * @bitmap: a FT_Bitmap to render the line onto
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
  *
- * Render a #PangoLayoutLine onto a FreeType2 bitmap
+ * Render a `PangoLayoutLine` onto a FreeType2 bitmap
  */
 void
 pango_ft2_render_layout_line (FT_Bitmap       *bitmap,
@@ -689,25 +693,26 @@ pango_ft2_render_layout_line (FT_Bitmap       *bitmap,
 
 /**
  * pango_ft2_render_transformed:
- * @bitmap:  the FreeType2 bitmap onto which to draw the string
- * @font:    the font in which to draw the string
- * @matrix:  (nullable): a #PangoMatrix, or %NULL to use an identity
- *           transformation
- * @glyphs:  the glyph string to draw
- * @x:       the x position of the start of the string (in Pango
- *           units in user space coordinates)
- * @y:       the y position of the baseline (in Pango units
- *           in user space coordinates)
+ * @bitmap: the FreeType2 bitmap onto which to draw the string
+ * @font: the font in which to draw the string
+ * @matrix: (nullable): a `PangoMatrix`
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in Pango
+ *   units in user space coordinates)
+ * @y: the y position of the baseline (in Pango units
+ *   in user space coordinates)
  *
- * Renders a #PangoGlyphString onto a FreeType2 bitmap, possibly
+ * Renders a `PangoGlyphString` onto a FreeType2 bitmap, possibly
  * transforming the layed-out coordinates through a transformation
- * matrix. Note that the transformation matrix for @font is not
+ * matrix.
+ *
+ * Note that the transformation matrix for @font is not
  * changed, so to produce correct rendering results, the @font
- * must have been loaded using a #PangoContext with an identical
+ * must have been loaded using a `PangoContext` with an identical
  * transformation matrix to that passed in to this function.
  *
  * Since: 1.6
- **/
+ */
 void
 pango_ft2_render_transformed (FT_Bitmap         *bitmap,
 			      const PangoMatrix *matrix,
@@ -734,14 +739,14 @@ pango_ft2_render_transformed (FT_Bitmap         *bitmap,
 
 /**
  * pango_ft2_render:
- * @bitmap:  the FreeType2 bitmap onto which to draw the string
- * @font:    the font in which to draw the string
- * @glyphs:  the glyph string to draw
- * @x:       the x position of the start of the string (in pixels)
- * @y:       the y position of the baseline (in pixels)
+ * @bitmap: the FreeType2 bitmap onto which to draw the string
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in pixels)
+ * @y: the y position of the baseline (in pixels)
  *
- * Renders a #PangoGlyphString onto a FreeType2 bitmap.
- **/
+ * Renders a `PangoGlyphString` onto a FreeType2 bitmap.
+ */
 void
 pango_ft2_render (FT_Bitmap        *bitmap,
 		  PangoFont        *font,
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index efaf853d..f330ef7c 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -152,18 +152,21 @@ set_transform (PangoFT2Font *ft2font)
 
 /**
  * pango_ft2_font_get_face: (skip)
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
- * Returns the native FreeType2 `FT_Face` structure used for this #PangoFont.
- * This may be useful if you want to use FreeType2 functions directly.
+ * Returns the native FreeType2 `FT_Face` structure
+ * used for this `PangoFont`.
  *
- * Use pango_fc_font_lock_face() instead; when you are done with a
- * face from pango_fc_font_lock_face() you must call
- * pango_fc_font_unlock_face().
+ * This may be useful if you want to use FreeType2
+ * functions directly.
  *
- * Return value: (nullable): a pointer to a `FT_Face` structure, with the
- *   size set correctly, or %NULL if @font is %NULL.
- **/
+ * Use [method@PangoFc.Font.lock_face] instead; when you are
+ * done with a face from [method@PangoFc.Font.lock_face], you
+ * must call [method@PangoFc.Font.unlock_face].
+ *
+ * Return value: (nullable): a pointer to a `FT_Face` structure,
+ *   with the size set correctly
+ */
 FT_Face
 pango_ft2_font_get_face (PangoFont *font)
 {
@@ -378,17 +381,17 @@ pango_ft2_font_get_glyph_extents (PangoFont      *font,
 
 /**
  * pango_ft2_font_get_kerning:
- * @font: a #PangoFont
- * @left: the left #PangoGlyph
- * @right: the right #PangoGlyph
+ * @font: a `PangoFont`
+ * @left: the left `PangoGlyph`
+ * @right: the right `PangoGlyph`
  *
  * Retrieves kerning information for a combination of two glyphs.
  *
  * Use pango_fc_font_kern_glyphs() instead.
  *
- * Return value: The amount of kerning (in Pango units) to apply for
- * the given combination of glyphs.
- **/
+ * Return value: The amount of kerning (in Pango units) to
+ *   apply for the given combination of glyphs.
+ */
 int
 pango_ft2_font_get_kerning (PangoFont *font,
 			    PangoGlyph left,
@@ -470,11 +473,12 @@ pango_ft2_font_finalize (GObject *object)
  * @font: a Pango FT2 font
  * @language: a language tag.
  *
- * Gets the #PangoCoverage for a `PangoFT2Font`. Use
- * pango_font_get_coverage() instead.
+ * Gets the `PangoCoverage` for a `PangoFT2Font`.
  *
- * Return value: (transfer full): a #PangoCoverage.
- **/
+ * Use [method@Pango.Font.get_coverage] instead.
+ *
+ * Return value: (transfer full): a `PangoCoverage`
+ */
 PangoCoverage *
 pango_ft2_font_get_coverage (PangoFont     *font,
 			     PangoLanguage *language)
@@ -486,17 +490,18 @@ pango_ft2_font_get_coverage (PangoFont     *font,
 
 /**
  * pango_ft2_get_unknown_glyph:
- * @font: a #PangoFont
+ * @font: a `PangoFont`
  *
- * Return the index of a glyph suitable for drawing unknown characters with
- * @font, or %PANGO_GLYPH_EMPTY if no suitable glyph found.
+ * Return the index of a glyph suitable for drawing unknown
+ * characters with @font, or %PANGO_GLYPH_EMPTY if no suitable
+ * glyph found.
  *
- * If you want to draw an unknown-box for a character that is not covered
- * by the font,
- * use PANGO_GET_UNKNOWN_GLYPH() instead.
+ * If you want to draw an unknown-box for a character that
+ * is not covered by the font, use PANGO_GET_UNKNOWN_GLYPH()
+ * instead.
  *
  * Return value: a glyph index into @font, or %PANGO_GLYPH_EMPTY
- **/
+ */
 PangoGlyph
 pango_ft2_get_unknown_glyph (PangoFont *font)
 {
diff --git a/pango/pangowin32-fontcache.c b/pango/pangowin32-fontcache.c
index 1a1a1cef..bca80270 100644
--- a/pango/pangowin32-fontcache.c
+++ b/pango/pangowin32-fontcache.c
@@ -38,7 +38,7 @@ typedef struct _CacheEntry CacheEntry;
 /**
  * PangoWin32FontCache:
  *
- * A #PangoWin32FontCache caches HFONTs by their LOGFONT descriptions.
+ * A `PangoWin32FontCache` caches HFONTs by their LOGFONT descriptions.
  */
 struct _PangoWin32FontCache
 {
@@ -72,11 +72,13 @@ free_cache_entry (LOGFONTW            *logfont,
 
 /**
  * pango_win32_font_cache_free:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
  *
- * Frees a #PangoWin32FontCache and all associated memory. All fonts loaded
- * through this font cache will be freed along with the cache.
- **/
+ * Frees a `PangoWin32FontCache` and all associated memory.
+ *
+ * All fonts loaded through this font cache will be freed
+ * along with the cache.
+ */
 void
 pango_win32_font_cache_free (PangoWin32FontCache *cache)
 {
@@ -178,7 +180,7 @@ cache_entry_unref (PangoWin32FontCache *cache,
 
 /**
  * pango_win32_font_cache_load:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
  * @logfont: a pointer to a LOGFONTA structure describing the font to load.
  *
  * Creates a HFONT from a LOGFONTA. The
@@ -186,9 +188,9 @@ cache_entry_unref (PangoWin32FontCache *cache,
  * stored
  *
  * Return value: (nullable): The font structure, or %NULL if the font
- * could not be loaded. In order to free this structure, you must call
- * pango_win32_font_cache_unload().
- **/
+ *   could not be loaded. In order to free this structure, you must call
+ *   [method@Pango.Win32FontCache.unload].
+ */
 HFONT
 pango_win32_font_cache_load (PangoWin32FontCache *cache,
 			     const LOGFONTA      *lfp)
@@ -208,7 +210,7 @@ pango_win32_font_cache_load (PangoWin32FontCache *cache,
 
 /**
  * pango_win32_font_cache_loadw:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
  * @logfont: a pointer to a LOGFONTW structure describing the font to load.
  *
  * Creates a HFONT from a LOGFONTW. The
@@ -216,11 +218,11 @@ pango_win32_font_cache_load (PangoWin32FontCache *cache,
  * stored
  *
  * Return value: (nullable): The font structure, or %NULL if the font
- * could not be loaded. In order to free this structure, you must call
- * pango_win32_font_cache_unload().
+ *   could not be loaded. In order to free this structure, you must call
+ *   [method@Pango.Win32FontCache.unload].
  *
  * Since: 1.16
- **/
+ */
 HFONT
 pango_win32_font_cache_loadw (PangoWin32FontCache *cache,
 			      const LOGFONTW      *lfp)
@@ -412,11 +414,12 @@ pango_win32_font_cache_loadw (PangoWin32FontCache *cache,
 
 /**
  * pango_win32_font_cache_unload:
- * @cache: a #PangoWin32FontCache
+ * @cache: a `PangoWin32FontCache`
  * @hfont: the HFONT to unload
  *
- * Frees a font structure previously loaded with pango_win32_font_cache_load().
- **/
+ * Frees a font structure previously loaded with
+ * [method@Pango.Win32FontCache.load].
+ */
 void
 pango_win32_font_cache_unload (PangoWin32FontCache *cache,
 			       HFONT		    hfont)
diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c
index 18d4544e..4cf2df3a 100644
--- a/pango/pangowin32-fontmap.c
+++ b/pango/pangowin32-fontmap.c
@@ -816,11 +816,13 @@ _pango_win32_font_map_class_init (PangoWin32FontMapClass *class)
 /**
  * pango_win32_font_map_for_display:
  *
- * Returns a PangoWin32FontMap. Font maps are cached and should
- * not be freed. If the font map is no longer needed, it can
- * be released with pango_win32_shutdown_display().
+ * Returns a `PangoWin32FontMap`.
  *
- * Return value: a #PangoFontMap.
+ * Font maps are cached and should not be freed. If
+ * the font map is no longer needed, it can be released
+ * with [func@Pango.win32_shutdown_display].
+ *
+ * Return value: a `PangoFontMap`
  **/
 PangoFontMap *
 pango_win32_font_map_for_display (void)
@@ -1296,18 +1298,18 @@ get_family_nameA (const LOGFONTA *lfp)
  * pango_win32_font_description_from_logfont:
  * @lfp: a LOGFONTA
  *
- * Creates a #PangoFontDescription that matches the specified LOGFONTA.
+ * Creates a `PangoFontDescription` that matches the specified LOGFONTA.
  *
  * The face name, italicness and weight fields in the LOGFONTA are used
- * to set up the resulting #PangoFontDescription. If the face name in
+ * to set up the resulting `PangoFontDescription`. If the face name in
  * the LOGFONTA contains non-ASCII characters the font is temporarily
  * loaded (using CreateFontIndirect()) and an ASCII (usually English)
  * name for it is looked up from the font name tables in the font
  * data. If that doesn't work, the face name is converted from the
  * system codepage to UTF-8 and that is used.
  *
- * Return value: the newly allocated #PangoFontDescription, which
- *  should be freed using pango_font_description_free()
+ * Return value: the newly allocated `PangoFontDescription`, which
+ *  should be freed using [method@Pango.FontDescription.free]
  *
  * Since: 1.12
  */
@@ -1481,18 +1483,18 @@ get_family_nameW (const LOGFONTW *lfp)
  * pango_win32_font_description_from_logfontw:
  * @lfp: a LOGFONTW
  *
- * Creates a #PangoFontDescription that matches the specified LOGFONTW.
+ * Creates a `PangoFontDescription` that matches the specified LOGFONTW.
  *
  * The face name, italicness and weight fields in the LOGFONTW are used
- * to set up the resulting #PangoFontDescription. If the face name in
+ * to set up the resulting `PangoFontDescription`. If the face name in
  * the LOGFONTW contains non-ASCII characters the font is temporarily
  * loaded (using CreateFontIndirect()) and an ASCII (usually English)
  * name for it is looked up from the font name tables in the font
  * data. If that doesn't work, the face name is converted from UTF-16
  * to UTF-8 and that is used.
  *
- * Return value: the newly allocated #PangoFontDescription, which
- *  should be freed using pango_font_description_free()
+ * Return value: the newly allocated `PangoFontDescription`, which
+ *  should be freed using [method@Pango.FontDescription.free]
  *
  * Since: 1.16
  */
@@ -1801,12 +1803,12 @@ pango_win32_face_list_sizes (PangoFontFace  *face,
 
 /**
  * pango_win32_font_map_get_font_cache:
- * @font_map: a PangoWin32FontMap
+ * @font_map: a `PangoWin32FontMap`
  *
  * Obtains the font cache associated with the given font map.
  *
- * Return value: the #PangoWin32FontCache of @font_map.
- **/
+ * Return value: the `PangoWin32FontCache` of @font_map.
+ */
 PangoWin32FontCache *
 pango_win32_font_map_get_font_cache (PangoFontMap *font_map)
 {
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index 12b4a36e..c8a5b46c 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -100,13 +100,13 @@ _pango_win32_font_get_hfont (PangoFont *font)
 /**
  * pango_win32_get_context:
  *
- * Retrieves a #PangoContext appropriate for rendering with Windows fonts.
+ * Retrieves a `PangoContext` appropriate for rendering with Windows fonts.
  *
- * Return value: the new #PangoContext
+ * Return value: the new `PangoContext`
  *
- * Deprecated: 1.22: Use pango_win32_font_map_for_display() followed by
- * pango_font_map_create_context() instead.
- **/
+ * Deprecated: 1.22: Use [func@Pango.Win32FontMap.for_display] followed by
+ * [method@Pango.FontMap.create_context] instead.
+ */
 PangoContext *
 pango_win32_get_context (void)
 {
@@ -214,7 +214,7 @@ _pango_win32_font_class_init (PangoWin32FontClass *class)
  * @x:       the x position of start of string (in pixels)
  * @y:       the y position of baseline (in pixels)
  *
- * Render a #PangoGlyphString onto a Windows DC
+ * Render a `PangoGlyphString` onto a Windows DC
  */
 void
 pango_win32_render (HDC               hdc,
@@ -370,23 +370,24 @@ pango_win32_render (HDC               hdc,
 
 /**
  * pango_win32_render_transformed:
- * @hdc:     a windows device context
- * @matrix:  (nullable): a #PangoMatrix, or %NULL to use an identity
- *           transformation
- * @font:    the font in which to draw the string
- * @glyphs:  the glyph string to draw
- * @x:       the x position of the start of the string (in Pango
- *           units in user space coordinates)
- * @y:       the y position of the baseline (in Pango units
- *           in user space coordinates)
+ * @hdc: a windows device context
+ * @matrix: (nullable): a `PangoMatrix`
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in Pango
+ *   units in user space coordinates)
+ * @y: the y position of the baseline (in Pango units
+ *   in user space coordinates)
  *
- * Renders a #PangoGlyphString onto a windows DC, possibly
+ * Renders a `PangoGlyphString` onto a windows DC, possibly
  * transforming the layed-out coordinates through a transformation
- * matrix. Note that the transformation matrix for @font is not
+ * matrix.
+ *
+ * Note that the transformation matrix for @font is not
  * changed, so to produce correct rendering results, the @font
- * must have been loaded using a #PangoContext with an identical
+ * must have been loaded using a `PangoContext` with an identical
  * transformation matrix to that passed in to this function.
- **/
+ */
 void
 pango_win32_render_transformed (HDC                hdc,
 				const PangoMatrix *matrix,
@@ -648,7 +649,7 @@ pango_win32_font_real_get_metrics_factor (PangoFont *font)
 
 /**
  * pango_win32_font_logfont:
- * @font: a #PangoFont which must be from the Win32 backend
+ * @font: a `PangoFont` which must be from the Win32 backend
  *
  * Determine the LOGFONTA struct for the specified font. Note that
  * Pango internally uses LOGFONTW structs, so if converting the UTF-16
@@ -659,8 +660,8 @@ pango_win32_font_real_get_metrics_factor (PangoFont *font)
  * to come across fonts with odd names.
  *
  * Return value: A newly allocated LOGFONTA struct. It must be
- * freed with g_free().
- **/
+ *   freed with g_free().
+ */
 LOGFONTA *
 pango_win32_font_logfont (PangoFont *font)
 {
@@ -684,12 +685,12 @@ pango_win32_font_logfont (PangoFont *font)
 
 /**
  * pango_win32_font_logfontw:
- * @font: a #PangoFont which must be from the Win32 backend
- * 
+ * @font: a `PangoFont` which must be from the Win32 backend
+ *
  * Determine the LOGFONTW struct for the specified font.
- * 
+ *
  * Return value: A newly allocated LOGFONTW struct. It must be
- * freed with g_free().
+ *   freed with g_free().
  *
  * Since: 1.16
  **/
@@ -710,21 +711,22 @@ pango_win32_font_logfontw (PangoFont *font)
 
 /**
  * pango_win32_font_select_font:
- * @font: a #PangoFont from the Win32 backend
+ * @font: a `PangoFont` from the Win32 backend
  * @hdc: a windows device context
  *
  * Selects the font into the specified DC and changes the mapping mode
  * and world transformation of the DC appropriately for the font.
+ *
  * You may want to surround the use of this function with calls
- * to SaveDC() and RestoreDC(). Call pango_win32_font_done_font() when
+ * to SaveDC() and RestoreDC(). Call [method@Pango.Win32Font.done_font[ when
  * you are done using the DC to release allocated resources.
  *
- * See pango_win32_font_get_metrics_factor() for information about
+ * See [method@Pango.Win32Font.get_metrics_factor] for information about
  * converting from the coordinate space used by this function
  * into Pango units.
  *
  * Return value: %TRUE if the operation succeeded.
- **/
+ */
 gboolean
 pango_win32_font_select_font (PangoFont *font,
 			      HDC        hdc)
@@ -736,10 +738,10 @@ pango_win32_font_select_font (PangoFont *font,
 
 /**
  * pango_win32_font_done_font:
- * @font: a #PangoFont from the win32 backend
+ * @font: a `PangoFont` from the win32 backend
  *
- * Releases any resources allocated by pango_win32_font_done_font()
- **/
+ * Releases any resources allocated by [method@Pango.Win32Font.select_font].
+ */
 void
 pango_win32_font_done_font (PangoFont *font)
 {
@@ -750,15 +752,15 @@ pango_win32_font_done_font (PangoFont *font)
 
 /**
  * pango_win32_font_get_metrics_factor:
- * @font: a #PangoFont from the win32 backend
+ * @font: a `PangoFont` from the win32 backend
  *
  * Returns the scale factor from logical units in the coordinate
- * space used by pango_win32_font_select_font() to Pango units
- * in user space.
+ * space used by [method@Pango.Win32Font.select_font] to Pango
+ * units in user space.
  *
  * Return value: factor to multiply logical units by to get Pango
- *               units.
- **/
+ *   units.
+ */
 double
 pango_win32_font_get_metrics_factor (PangoFont *font)
 {
@@ -893,8 +895,8 @@ pango_win32_font_get_coverage (PangoFont     *font,
 
 /**
  * pango_win32_get_unknown_glyph:
- * @font: a #PangoFont
- * @wc: the Unicode character for which a glyph is needed.
+ * @font: a `PangoFont`
+ * @wc: the Unicode character for which a glyph is needed
  *
  * Returns the index of a glyph suitable for drawing @wc as an
  * unknown character.
@@ -902,7 +904,7 @@ pango_win32_font_get_coverage (PangoFont     *font,
  * Use PANGO_GET_UNKNOWN_GLYPH() instead.
  *
  * Return value: a glyph index into @font
- **/
+ */
 PangoGlyph
 pango_win32_get_unknown_glyph (PangoFont *font,
 			       gunichar   wc)
@@ -912,14 +914,15 @@ pango_win32_get_unknown_glyph (PangoFont *font,
 
 /**
  * pango_win32_render_layout_line:
- * @hdc:       DC to use for drawing
- * @line:      a #PangoLayoutLine
- * @x:         the x position of start of string (in pixels)
- * @y:         the y position of baseline (in pixels)
+ * @hdc: DC to use for drawing
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
  *
- * Render a #PangoLayoutLine onto a device context. For underlining to
- * work property the text alignment of the DC should have TA_BASELINE
- * and TA_LEFT.
+ * Render a `PangoLayoutLine` onto a device context.
+ *
+ * For underlining to work property the text alignment
+ * of the DC should have TA_BASELINE and TA_LEFT.
  */
 void
 pango_win32_render_layout_line (HDC              hdc,
@@ -1068,12 +1071,12 @@ pango_win32_render_layout_line (HDC              hdc,
 
 /**
  * pango_win32_render_layout:
- * @hdc:       HDC to use for drawing
- * @layout:    a #PangoLayout
- * @x:         the X position of the left of the layout (in pixels)
- * @y:         the Y position of the top of the layout (in pixels)
+ * @hdc: HDC to use for drawing
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in pixels)
+ * @y: the Y position of the top of the layout (in pixels)
  *
- * Render a #PangoLayoutLine onto an X drawable
+ * Render a `PangoLayoutLine` onto an HDC.
  */
 void
 pango_win32_render_layout (HDC          hdc,
@@ -1174,14 +1177,14 @@ pango_win32_get_item_properties (PangoItem      *item,
 
 /**
  * pango_win32_font_get_glyph_index:
- * @font: a #PangoFont.
- * @wc: a Unicode character.
+ * @font: a `PangoFont`
+ * @wc: a Unicode character
  *
  * Obtains the index of the glyph for @wc in @font, or 0, if not
  * covered.
  *
  * Return value: the glyph index for @wc.
- **/
+ */
 gint
 pango_win32_font_get_glyph_index (PangoFont *font,
 				  gunichar   wc)
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index ac4e6f39..1e1fff6f 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -108,15 +108,15 @@ _pango_xft_font_new (PangoXftFontMap *xftfontmap,
 
 /**
  * _pango_xft_font_get_mini_font:
- * @xfont: a #PangoXftFont
+ * @xfont: a `PangoXftFont`
  *
  * Gets the font used for drawing the digits in the
  * missing-character hex squares
  *
- * Return value: the #PangoFont used for the digits; this
+ * Return value: the `PangoFont` used for the digits; this
  *  value is associated with the main font and will be freed
  *  along with the main font.
- **/
+ */
 PangoFont *
 _pango_xft_font_get_mini_font (PangoXftFont *xfont)
 {
@@ -470,13 +470,13 @@ pango_xft_font_real_shutdown (PangoFcFont *fcfont)
 
 /**
  * pango_xft_font_get_font: (skip)
- * @font: (nullable): a #PangoFont.
+ * @font: (nullable): a `PangoFont`
  *
  * Returns the `XftFont` of a font.
  *
  * Return value: (nullable): the `XftFont` associated to @font,
  *   or %NULL if @font is %NULL.
- **/
+ */
 XftFont *
 pango_xft_font_get_font (PangoFont *font)
 {
@@ -488,7 +488,7 @@ pango_xft_font_get_font (PangoFont *font)
 
 /**
  * pango_xft_font_get_display: (skip)
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
  *
  * Returns the X display of the `XftFont` of a font.
  *
@@ -510,7 +510,7 @@ pango_xft_font_get_display (PangoFont *font)
 
 /**
  * pango_xft_font_get_unknown_glyph:
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
  * @wc: the Unicode character for which a glyph is needed.
  *
  * Returns the index of a glyph suitable for drawing @wc as an
@@ -531,7 +531,7 @@ pango_xft_font_get_unknown_glyph (PangoFont *font,
 
 /**
  * pango_xft_font_lock_face: (skip)
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
  *
  * Gets the FreeType `FT_Face` associated with a font.
  *
@@ -553,7 +553,7 @@ pango_xft_font_lock_face (PangoFont *font)
 
 /**
  * pango_xft_font_unlock_face: (skip)
- * @font: (type PangoXftFont): a #PangoFont.
+ * @font: (type PangoXftFont): a `PangoFont`
  *
  * Releases a font previously obtained with
  * pango_xft_font_lock_face().
@@ -572,12 +572,14 @@ pango_xft_font_unlock_face (PangoFont *font)
 
 /**
  * pango_xft_font_get_glyph:
- * @font: (type PangoXftFont): a #PangoFont for the Xft backend
+ * @font: (type PangoXftFont): a `PangoFont` for the Xft backend
  * @wc: Unicode codepoint to look up
  *
  * Gets the glyph index for a given Unicode character
- * for @font. If you only want to determine
- * whether the font has the glyph, use pango_xft_font_has_char().
+ * for @font.
+ *
+ * If you only want to determine whether the font has
+ * the glyph, use pango_xft_font_has_char().
  *
  * Use pango_fc_font_get_glyph() instead.
  *
@@ -597,7 +599,7 @@ pango_xft_font_get_glyph (PangoFont *font,
 
 /**
  * pango_xft_font_has_char:
- * @font: (type PangoXftFont): a #PangoFont for the Xft backend
+ * @font: (type PangoXftFont): a `PangoFont` for the Xft backend
  * @wc: Unicode codepoint to look up
  *
  * Determines whether @font has a glyph for the codepoint @wc.
diff --git a/pango/pangoxft-fontmap.c b/pango/pangoxft-fontmap.c
index 82955165..1b5f5b5a 100644
--- a/pango/pangoxft-fontmap.c
+++ b/pango/pangoxft-fontmap.c
@@ -203,11 +203,11 @@ register_display (Display *display)
  * @display: an X display
  * @screen: the screen number of a screen within @display
  *
- * Returns the #PangoXftFontMap for the given display and screen.
+ * Returns the `PangoXftFontMap` for the given display and screen.
  * The fontmap is owned by Pango and will be valid until
  * the display is closed.
  *
- * Return value: (transfer none): a #PangoFontMap object, owned by Pango.
+ * Return value: (transfer none): a `PangoFontMap` object, owned by Pango.
  *
  * Since: 1.2
  **/
@@ -348,10 +348,10 @@ _pango_xft_font_map_get_info (PangoFontMap *fontmap,
  * @display: an X display.
  * @screen: an X screen.
  *
- * Retrieves a #PangoContext appropriate for rendering with
+ * Retrieves a `PangoContext` appropriate for rendering with
  * Xft fonts on the given screen of the given display.
  *
- * Return value: the new #PangoContext.
+ * Return value: the new `PangoContext`.
  *
  * Deprecated: 1.22: Use pango_xft_get_font_map() followed by
  * pango_font_map_create_context() instead.
@@ -367,9 +367,9 @@ pango_xft_get_context (Display *display,
 
 /**
  * _pango_xft_font_map_get_renderer:
- * @fontmap: a #PangoXftFontMap
+ * @fontmap: a `PangoXftFontMap`
  *
- * Gets the singleton #PangoXFTRenderer for this fontmap.
+ * Gets the singleton `PangoXFTRenderer` for this fontmap.
  *
  * Return value: the renderer.
  **/
diff --git a/pango/pangoxft-render.c b/pango/pangoxft-render.c
index a2584f3c..9228a5c5 100644
--- a/pango/pangoxft-render.c
+++ b/pango/pangoxft-render.c
@@ -705,14 +705,14 @@ release_renderer (PangoRenderer *renderer)
 
 /**
  * pango_xft_render_layout:
- * @draw:      an #XftDraw
- * @color:     the foreground color in which to draw the layout
- *             (may be overridden by color attributes)
- * @layout:    a #PangoLayout
- * @x:         the X position of the left of the layout (in Pango units)
- * @y:         the Y position of the top of the layout (in Pango units)
+ * @draw: an XftDraw
+ * @color: the foreground color in which to draw the layout
+ *   (may be overridden by color attributes)
+ * @layout: a `PangoLayout`
+ * @x: the X position of the left of the layout (in Pango units)
+ * @y: the Y position of the top of the layout (in Pango units)
  *
- * Render a #PangoLayout onto a #XftDraw
+ * Render a `PangoLayout` onto a XftDraw
  *
  * Since: 1.8
  */
@@ -742,14 +742,14 @@ pango_xft_render_layout (XftDraw     *draw,
 
 /**
  * pango_xft_render_layout_line:
- * @draw:      an #XftDraw
- * @color:     the foreground color in which to draw the layout line
- *             (may be overridden by color attributes)
- * @line:      a #PangoLayoutLine
- * @x:         the x position of start of string (in Pango units)
- * @y:         the y position of baseline (in Pango units)
+ * @draw: an XftDraw
+ * @color: the foreground color in which to draw the layout line
+ *   (may be overridden by color attributes)
+ * @line: a `PangoLayoutLine`
+ * @x: the x position of start of string (in Pango units)
+ * @y: the y position of baseline (in Pango units)
  *
- * Render a #PangoLayoutLine onto a #XftDraw
+ * Render a `PangoLayoutLine` onto a XftDraw
  *
  * Since: 1.8
  */
@@ -779,22 +779,23 @@ pango_xft_render_layout_line (XftDraw         *draw,
 
 /**
  * pango_xft_render_transformed:
- * @draw:    an #XftDraw
- * @color:   the color in which to draw the glyphs
- * @font:    the font in which to draw the string
- * @matrix:  (nullable): a #PangoMatrix, or %NULL to use an identity
- *           transformation
- * @glyphs:  the glyph string to draw
- * @x:       the x position of the start of the string (in Pango
- *           units in user space coordinates)
- * @y:       the y position of the baseline (in Pango units
- *           in user space coordinates)
+ * @draw: an XftDraw
+ * @color: the color in which to draw the glyphs
+ * @font: the font in which to draw the string
+ * @matrix: (nullable): a `PangoMatrix`
+ * @glyphs: the glyph string to draw
+ * @x: the x position of the start of the string (in Pango
+ *   units in user space coordinates)
+ * @y: the y position of the baseline (in Pango units
+ *   in user space coordinates)
  *
- * Renders a #PangoGlyphString onto a #XftDraw, possibly
+ * Renders a `PangoGlyphString` onto a XftDraw, possibly
  * transforming the layed-out coordinates through a transformation
- * matrix. Note that the transformation matrix for @font is not
+ * matrix.
+ *
+ * Note that the transformation matrix for @font is not
  * changed, so to produce correct rendering results, the @font
- * must have been loaded using a #PangoContext with an identical
+ * must have been loaded using a `PangoContext` with an identical
  * transformation matrix to that passed in to this function.
  *
  * Since: 1.8
@@ -828,14 +829,14 @@ pango_xft_render_transformed (XftDraw          *draw,
 
 /**
  * pango_xft_render:
- * @draw:    the XftDraw object.
- * @color:   the color in which to draw the string
- * @font:    the font in which to draw the string
- * @glyphs:  the glyph string to draw
- * @x:       the x position of start of string (in pixels)
- * @y:       the y position of baseline (in pixels)
+ * @draw: the XftDraw object.
+ * @color: the color in which to draw the string
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
  *
- * Renders a #PangoGlyphString onto an XftDraw object wrapping an X drawable.
+ * Renders a `PangoGlyphString` onto an XftDraw object wrapping an X drawable.
  */
 void
 pango_xft_render (XftDraw          *draw,
@@ -856,15 +857,15 @@ pango_xft_render (XftDraw          *draw,
 
 /**
  * pango_xft_picture_render:
- * @display:      an X display
- * @src_picture:  the source picture to draw the string with
+ * @display: an X display
+ * @src_picture: the source picture to draw the string with
  * @dest_picture: the destination picture to draw the string onto
- * @font:         the font in which to draw the string
- * @glyphs:       the glyph string to draw
- * @x:            the x position of start of string (in pixels)
- * @y:            the y position of baseline (in pixels)
+ * @font: the font in which to draw the string
+ * @glyphs: the glyph string to draw
+ * @x: the x position of start of string (in pixels)
+ * @y: the y position of baseline (in pixels)
  *
- * Renders a #PangoGlyphString onto an Xrender Picture object.
+ * Renders a `PangoGlyphString` onto an Xrender Picture object.
  */
 void
 pango_xft_picture_render (Display          *display,
@@ -900,17 +901,18 @@ pango_xft_picture_render (Display          *display,
 /**
  * pango_xft_renderer_new:
  * @display: an X display
- * @screen:   the index of the screen for @display to which rendering will be done
+ * @screen: the index of the screen for @display to which rendering will be done
+ *
+ * Create a new `PangoXftRenderer` to allow rendering Pango objects
+ * with the Xft library.
  *
- * Create a new #PangoXftRenderer to allow rendering Pango objects
- * with the Xft library. You must call pango_xft_renderer_set_draw() before
+ * You must call pango_xft_renderer_set_draw() before
  * using the renderer.
  *
- * Return value: the newly created #PangoXftRenderer, which should
- *               be freed with g_object_unref().
+ * Return value: the newly created `PangoXftRenderer`
  *
  * Since: 1.8
- **/
+ */
 PangoRenderer *
 pango_xft_renderer_new (Display *display,
 			int      screen)
@@ -927,14 +929,14 @@ pango_xft_renderer_new (Display *display,
 
 /**
  * pango_xft_renderer_set_draw:
- * @xftrenderer: a #PangoXftRenderer
- * @draw: a #XftDraw
+ * @xftrenderer: a `PangoXftRenderer`
+ * @draw: a XftDraw
  *
- * Sets the #XftDraw object that the renderer is drawing to.
+ * Sets the XftDraw object that the renderer is drawing to.
  * The renderer must not be currently active.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_xft_renderer_set_draw (PangoXftRenderer *xftrenderer,
 			     XftDraw          *draw)
@@ -946,13 +948,13 @@ pango_xft_renderer_set_draw (PangoXftRenderer *xftrenderer,
 
 /**
  * pango_xft_renderer_set_default_color:
- * @xftrenderer: a #XftRenderer
+ * @xftrenderer: a XftRenderer
  * @default_color: the default foreground color
  *
- * Sets the default foreground color for a #XftRenderer.
+ * Sets the default foreground color for a XftRenderer.
  *
  * Since: 1.8
- **/
+ */
 void
 pango_xft_renderer_set_default_color (PangoXftRenderer *xftrenderer,
 				      PangoColor       *default_color)
diff --git a/pango/pangoxft-render.h b/pango/pangoxft-render.h
index 77684728..bf4b33e9 100644
--- a/pango/pangoxft-render.h
+++ b/pango/pangoxft-render.h
@@ -57,7 +57,7 @@ typedef struct _PangoXftRendererPrivate PangoXftRendererPrivate;
 /**
  * PangoXftRenderer:
  *
- * #PangoXftRenderer is a subclass of #PangoRenderer used for rendering
+ * `PangoXftRenderer` is a subclass of `PangoRenderer` used for rendering
  * with Pango's Xft backend. It can be used directly, or it can be
  * further subclassed to modify exactly how drawing of individual
  * elements occurs.
@@ -84,7 +84,7 @@ struct _PangoXftRenderer
  *   the current foreground color and other foreground
  *   attributes
  *
- * The class structure for #PangoXftRenderer
+ * The class structure for `PangoXftRenderer`
  *
  * Since: 1.8
  */
diff --git a/pango/pangoxft.h b/pango/pangoxft.h
index 0852c202..105de5c2 100644
--- a/pango/pangoxft.h
+++ b/pango/pangoxft.h
@@ -49,9 +49,9 @@ G_BEGIN_DECLS
 /**
  * PangoXftFontMap:
  *
- * #PangoXftFontMap is an implementation of #PangoFcFontMap suitable for
+ * `PangoXftFontMap` is an implementation of `PangoFcFontMap` suitable for
  * the Xft library as the renderer.  It is used in to create fonts of
- * type #PangoXftFont.
+ * type `PangoXftFont`.
  */
 
 /* This is a hack needed because PangoXft hijacks the Pango namespace
@@ -73,8 +73,8 @@ typedef struct _PangoXftFontMap      PangoXftFontMap;
 /**
  * PangoXftFont:
  *
- * #PangoXftFont is an implementation of #PangoFcFont using the Xft
- * library for rendering.  It is used in conjunction with #PangoXftFontMap.
+ * `PangoXftFont` is an implementation of `PangoFcFont` using the Xft
+ * library for rendering.  It is used in conjunction with `PangoXftFontMap`.
  */
 typedef struct _PangoXftFont    PangoXftFont;
 
diff --git a/pango/reorder-items.c b/pango/reorder-items.c
index d00fee4c..e5ceeb6f 100644
--- a/pango/reorder-items.c
+++ b/pango/reorder-items.c
@@ -39,12 +39,12 @@ static GList *reorder_items_recurse (GList *items, int n_items);
  * The visual order is determined from the associated directional
  * levels of the items. The original list is unmodified.
  *
- * Returns: (transfer full) (element-type Pango.Item): a #GList
- *          of #PangoItem structures in visual order.
- *
  * (Please open a bug if you use this function.
  *  It is not a particularly convenient interface, and the code
  *  is duplicated elsewhere in Pango for that reason.)
+ *
+ * Returns: (transfer full) (element-type Pango.Item): a `GList`
+ *   of `PangoItem` structures in visual order.
  */
 GList *
 pango_reorder_items (GList *logical_items)
diff --git a/pango/shape.c b/pango/shape.c
index 1b2986c4..04407732 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -63,7 +63,7 @@ pango_shape (const gchar         *text,
  * pango_shape_full:
  * @item_text: valid UTF-8 text to shape.
  * @item_length: the length (in bytes) of @item_text. -1 means nul-terminated text.
- * @paragraph_text: (allow-none): text of the paragraph (see details).  May be %NULL.
+ * @paragraph_text: (nullable): text of the paragraph (see details).  May be %NULL.
  * @paragraph_length: the length (in bytes) of @paragraph_text. -1 means nul-terminated text.
  * @analysis: `PangoAnalysis` structure from [func@itemize].
  * @glyphs: glyph string in which to store results.
@@ -156,7 +156,7 @@ fallback_shape (const char          *text,
  * @item_text: valid UTF-8 text to shape
  * @item_length: the length (in bytes) of @item_text.
  *     -1 means nul-terminated text.
- * @paragraph_text: (allow-none): text of the paragraph (see details).
+ * @paragraph_text: (nullable): text of the paragraph (see details).
  *     May be %NULL.
  * @paragraph_length: the length (in bytes) of @paragraph_text.
  *     -1 means nul-terminated text.