[pango/docs-cleanup: 1/2] introspection: Stop using allow-none

[Matthias Clasen <matthiasc src gnome org>]

commit 75eee838a91bad404d211b002f26e9af3033f0d5
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed May 19 07:39:39 2021 -0400

    introspection: Stop using allow-none
    
    The allow-none annotation has been deprecated for a long
    time already. Instead use optional and nullable everywhere.

 pango/fonts.c            | 14 +++++------
 pango/glyphstring.c      |  4 ++--
 pango/pango-attributes.c |  8 +++----
 pango/pango-context.c    | 10 ++++----
 pango/pango-language.c   |  6 ++---
 pango/pango-layout.c     | 62 ++++++++++++++++++++++++------------------------
 pango/pango-layout.h     |  4 ++--
 pango/pango-markup.c     | 12 +++++-----
 pango/pango-matrix.c     | 10 ++++----
 pango/pango-renderer.c   |  6 ++---
 pango/pango-script.c     |  6 ++---
 pango/pango-tabs.c       |  8 +++----
 pango/pango-utils.c      | 10 ++++----
 pango/shape.c            |  4 ++--
 14 files changed, 82 insertions(+), 82 deletions(-)
---
diff --git a/pango/fonts.c b/pango/fonts.c
index b199e785..a0f67e7c 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -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,9 +1803,9 @@ 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
+ * @ink_rect: (out) (optional): 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
+ * @logical_rect: (out) (optional): rectangle used to store the logical extents of
  *            the glyph or %NULL to indicate that the result is not needed.
  *
  * Gets the logical and ink extents of a glyph within a font.
@@ -1851,7 +1851,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.
  *
@@ -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.
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index 6c2338f1..6d54d246 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -264,9 +264,9 @@ 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
+ * @ink_rect: (out) (optional): 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
+ * @logical_rect: (out) (optional): rectangle used to store the logical extents of the
  *            glyph string or %NULL to indicate that the result is not needed.
  *
  * Compute the logical and ink extents of a glyph string.
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 225dc654..ff776ef2 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -968,9 +968,9 @@ 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
+ * @copy_func: (nullable): 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
+ * @destroy_func: (nullable): function to free @data when the
  *   attribute is freed, or %NULL
  *
  * Creates a new shape attribute.
@@ -2167,9 +2167,9 @@ pango_attr_iterator_get (PangoAttrIterator *iterator,
  *   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
+ * @language: (out) (optional): if non-%NULL, location to store language tag
  *   for item, or %NULL if none is found.
- * @extra_attrs: (allow-none) (element-type Pango.Attribute) (transfer full):
+ * @extra_attrs: (out) (optional) (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
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-language.c b/pango/pango-language.c
index 2f79acec..7ab90fe8 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -306,7 +306,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`.
  *
@@ -618,8 +618,8 @@ 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
+ * @language: (nullable): a `PangoLanguage`, or %NULL
+ * @num_scripts: (out caller-allocates) (optional): location to
  *   return number of scripts, or %NULL
  *
  * Determines the scripts used to to write @language.
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index ca70ebe5..b0afc275 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -665,7 +665,7 @@ 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, can be %NULL
  *
  * Sets the text attributes for a layout object.
  * References @attrs, so the caller can unref its reference.
@@ -722,7 +722,7 @@ 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`, or %NULL
  *   to unset the current font description
  *
  * Sets the default font description for the layout.
@@ -919,7 +919,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`, or %NULL
  *
  * Sets the tabs to use for @layout, overriding the default tabs.
  *
@@ -1255,7 +1255,7 @@ pango_layout_set_markup (PangoLayout *layout,
  * @length: length of marked-up text in bytes, or -1 if @markup is
  *   null-terminated
  * @accel_marker: marker for accelerators in the text
- * @accel_char: (out caller-allocates) (allow-none): return location
+ * @accel_char: (out caller-allocates) (optional): return location
  *   for first located accelerator, or %NULL
  *
  * Sets the layout text and attribute list from marked-up text.
@@ -1813,9 +1813,9 @@ pango_layout_index_to_line_and_extents (PangoLayout     *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
+ * @line: (out) (optional): 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
+ * @x_pos: (out) (optional): location to store resulting position within line
  *   (%PANGO_SCALE units per device unit), or %NULL
  *
  * Converts from byte @index_ within the @layout to line and X position.
@@ -2416,9 +2416,9 @@ 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
+ * @strong_pos: (out) (optional): location to store the strong
  *   cursor position (may be %NULL)
- * @weak_pos: (out) (allow-none): location to store the weak cursor
+ * @weak_pos: (out) (optional): location to store the weak cursor
  *   position (may be %NULL)
  *
  * Given an index within a layout, determines the positions that of the
@@ -2858,9 +2858,9 @@ 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
+ * @ink_rect: (out) (optional): 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
+ * @logical_rect: (out) (optional):rectangle used to store the logical
  *   extents of the layout or %NULL to indicate that the result is not needed.
  *
  * Computes the logical and ink extents of @layout.
@@ -2887,9 +2887,9 @@ 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
+ * @ink_rect: (out) (optional): 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
+ * @logical_rect: (out) (optional): rectangle used to store the logical
  *   extents of the layout or %NULL to indicate that the result is not needed.
  *
  * Computes the logical and ink extents of @layout in device units.
@@ -2914,8 +2914,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, or %NULL
+ * @height: (out) (optional): location to store the logical height, or %NULL
  *
  * Determines the logical width and height of a `PangoLayout` in Pango
  * units.
@@ -2940,8 +2940,8 @@ 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, or %NULL
+ * @height: (out) (optional): location to store the logical height, or %NULL
  *
  * Determines the logical width and height of a `PangoLayout` in device
  * units.
@@ -5240,9 +5240,9 @@ 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
@@ -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,9 +5294,9 @@ 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
+ * @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 @layout_line in device units.
@@ -6791,8 +6791,8 @@ 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, or %NULL
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents, or %NULL
  *
  * Gets the extents of the current cluster, in layout coordinates
  * (origin is the top left of the entire layout).
@@ -6838,8 +6838,8 @@ 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, or %NULL
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents, or %NULL
  *
  * Gets the extents of the current run in layout coordinates
  * (origin is the top left of the entire layout).
@@ -6894,8 +6894,8 @@ 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
+ * @ink_rect: (out) (optional): rectangle to fill with ink extents, or %NULL
+ * @logical_rect: (out) (optional): 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
@@ -6933,8 +6933,8 @@ 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, or %NULL
+ * @y1_: (out) (optional): end of line, or %NULL
  *
  * Divides the vertical space in the `PangoLayout` being iterated over
  * between the lines in the layout, and returns the space belonging to
@@ -7007,8 +7007,8 @@ 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, or %NULL
+ * @logical_rect: (out) (optional): rectangle to fill with logical extents, or %NULL
  *
  * Obtains the extents of the `PangoLayout` being iterated over.
  * @ink_rect or @logical_rect can be %NULL if you aren't interested in them.
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 4a464230..9f2a10df 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -100,10 +100,10 @@ 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
+ * @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-renderer.c b/pango/pango-renderer.c
index 8f3c9846..fc68f8e8 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -801,7 +801,7 @@ 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.
@@ -1288,7 +1288,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 +1552,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-script.c b/pango/pango-script.c
index 7116a0a4..f201b3aa 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -170,9 +170,9 @@ 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
+ * @start: (out) (optional): location to store start position of the range, or %NULL
+ * @end: (out) (optional): location to store end position of the range, or %NULL
+ * @script: (out) (optional): location to store script for range, or %NULL
  *
  * Gets information about the range to which @iter currently points.
  * The range is the set of locations p where *start <= p < *end.
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-utils.c b/pango/pango-utils.c
index 5283da35..56d610c5 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -673,10 +673,10 @@ 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.
+ * @str: (nullable): string to parse.  May be %NULL.
+ * @value: (out) (optional): 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.
+ * @possible_values: (out) (optional): place to store list of possible values on failure, or %NULL.
  *
  * Parses an enum type and stores the result in @value.
  *
@@ -1016,8 +1016,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, or %NULL.
+ * @nearest: (nullable): rectangle to round to nearest pixels, or %NULL.
  *
  * Converts extents from Pango units to device units.
  *
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.