From 42edc2780fc31719f90326febb5b44d2a7f58001 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Thu, 20 May 2021 21:03:11 -0400
Subject: docs: Reduce redundancy

Remove a boatload of "or %NULL" from nullable parameters
and return values. gi-docgen generates suitable text from
the annotation that we don't need to duplicate.
---
 pango/glyphstring.c        |  2 --
 pango/pango-context.c      |  4 ++--
 pango/pango-coverage.c     |  7 +++----
 pango/pango-engine.h       |  8 ++++----
 pango/pango-glyph-item.c   |  8 ++------
 pango/pango-item.c         |  6 ++----
 pango/pango-language.c     |  9 ++++-----
 pango/pango-layout.c       |  6 ++----
 pango/pango-markup.c       | 16 ++++++++--------
 pango/pango-matrix.c       | 24 +++++++++++-------------
 pango/pango-ot.h           | 11 ++++-------
 pango/pango-renderer.c     |  6 +++---
 pango/pango-tabs.c         |  8 ++++----
 pango/pangocairo-font.c    |  4 ++--
 pango/pangocairo-fontmap.c |  2 +-
 pango/pangofc-font.c       |  4 ++--
 pango/pangofc-fontmap.c    |  2 +-
 pango/pangoxft-font.c      |  3 +--
 18 files changed, 56 insertions(+), 74 deletions(-)

diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index f6e59016..87c8a069 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -102,8 +102,6 @@ G_DEFINE_BOXED_TYPE (PangoGlyphString, pango_glyph_string,
  * 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.
  */
 PangoGlyphString *
 pango_glyph_string_copy (PangoGlyphString *string)
diff --git a/pango/pango-context.c b/pango/pango-context.c
index 0db09459..561f55bf 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -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: (nullable): Cached attribute iterator, or %NULL
+ * @cached_iter: (nullable): Cached attribute iterator
  *
  * 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: (nullable): Cached attribute iterator, or %NULL
+ * @cached_iter: (nullable): Cached attribute iterator
  *
  * Breaks a piece of text into segments with consistent directional
  * level and font.
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index 0bc6187b..331cd1dc 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -238,11 +238,10 @@ pango_coverage_to_bytes (PangoCoverage  *coverage,
  *   representing a `PangoCoverage`
  * @n_bytes: the size of @bytes in bytes
  *
- * Convert data generated from pango_coverage_to_bytes() back
- * to a `PangoCoverage`.
+ * Convert data generated from pango_coverage_to_bytes()
+ * back to a `PangoCoverage`.
  *
- * Return value: (transfer full) (nullable): a newly allocated
- *   `PangoCoverage`, or %NULL if the data was invalid.
+ * Return value: (transfer full) (nullable): a newly allocated `PangoCoverage`
  *
  * Deprecated: 1.44: This returns %NULL
  */
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index b634fd88..faa683a4 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -370,8 +370,8 @@ prefix ## _register_type (GTypeModule *module)				  \
  * PANGO_ENGINE_LANG_DEFINE_TYPE:
  * @name: Name of the the type to register (for example:, ArabicEngineFc)
  * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
- * @class_init: (nullable): Class initialization function for the new type, or %NULL
- * @instance_init: (nullable): Instance initialization function for the new type, or %NULL
+ * @class_init: (nullable): Class initialization function for the new type
+ * @instance_init: (nullable): Instance initialization function for the new type
  *
  * Outputs the necessary code for GObject type registration for a
  * `PangoEngineLang` class defined in a module. Two static symbols
@@ -401,8 +401,8 @@ prefix ## _register_type (GTypeModule *module)				  \
  * PANGO_ENGINE_SHAPE_DEFINE_TYPE:
  * @name: Name of the the type to register (for example:, ArabicEngineFc)
  * @prefix: Prefix for symbols that will be defined (for example:, arabic_engine_fc)
- * @class_init: (nullable): Class initialization function for the new type, or %NULL
- * @instance_init: (nullable): Instance initialization function for the new type, or %NULL
+ * @class_init: (nullable): Class initialization function for the new type
+ * @instance_init: (nullable): Instance initialization function for the new type
  *
  * Outputs the necessary code for GObject type registration for a
  * `PangoEngineShape` class defined in a module. Two static symbols
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index cbda8f09..5e6ca7b6 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -138,9 +138,7 @@ pango_glyph_item_split (PangoGlyphItem *orig,
  *
  * 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`
  *
  * Since: 1.20
  */
@@ -193,9 +191,7 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
  *
  * Make a shallow copy of an existing `PangoGlyphItemIter` structure.
  *
- * Return value: (nullable): the newly allocated `PangoGlyphItemIter`,
- *   which should be freed with pango_glyph_item_iter_free(), or %NULL
- *   if @orig was %NULL.
+ * Return value: (nullable): the newly allocated `PangoGlyphItemIter`
  *
  * Since: 1.22
  */
diff --git a/pango/pango-item.c b/pango/pango-item.c
index d1caa771..ce38e6d2 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -42,13 +42,11 @@ pango_item_new (void)
 
 /**
  * pango_item_copy:
- * @item: (nullable): a `PangoItem`, may be %NULL
+ * @item: (nullable): a `PangoItem`
  *
  * Copy an existing `PangoItem` structure.
  *
- * Return value: (nullable): the newly allocated `PangoItem`, which
- *   should be freed with [method@Pango.Item.free], or %NULL if
- *   @item was %NULL.
+ * Return value: (nullable): the newly allocated `PangoItem`
  */
 PangoItem *
 pango_item_copy (PangoItem *item)
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 355b9b99..410550db 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -305,7 +305,7 @@ pango_language_get_default (void)
 
 /**
  * pango_language_from_string:
- * @language: (nullable): a string representing a language tag, or %NULL
+ * @language: (nullable): a string representing a language tag
  *
  * Convert a language tag to a `PangoLanguage`.
  *
@@ -320,8 +320,7 @@ pango_language_get_default (void)
  * 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
+ * Return value: (transfer none) (nullable): a `PangoLanguage`
  */
 PangoLanguage *
 pango_language_from_string (const char *language)
@@ -559,7 +558,7 @@ static const LangInfo lang_texts[] = {
 
 /**
  * pango_language_get_sample_string:
- * @language: (nullable): a `PangoLanguage`, or %NULL
+ * @language: (nullable): a `PangoLanguage`
  *
  * Get a string that is representative of the characters needed to
  * render a particular language.
@@ -684,7 +683,7 @@ pango_language_get_scripts (PangoLanguage *language,
 
 /**
  * pango_language_includes_script:
- * @language: (nullable): a `PangoLanguage`, or %NULL
+ * @language: (nullable): a `PangoLanguage`
  * @script: a `PangoScript`
  *
  * Determines if @script is one of the scripts used to
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 1ac44986..a59e0ac0 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -753,8 +753,6 @@ pango_layout_set_font_description (PangoLayout                *layout,
  * 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
  */
@@ -5240,9 +5238,9 @@ pango_layout_line_get_extents_and_height (PangoLayoutLine *line,
  * pango_layout_line_get_extents:
  * @line: a `PangoLayoutLine`
  * @ink_rect: (out) (optional): rectangle used to store the extents of
- *   the glyph string as drawn, or %NULL
+ *   the glyph string as drawn
  * @logical_rect: (out) (optional): rectangle used to store the logical
- *   extents of the glyph string, or %NULL
+ *   extents of the glyph string
  *
  * Computes the logical and ink extents of a layout line.
  *
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index 3728d3b3..258ca717 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -602,10 +602,10 @@ 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) (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
+ * @attr_list: (out) (optional): address of return location for a `PangoAttrList`
+ * @text: (out) (optional): address of return location for text with tags stripped
+ * @accel_char: (out) (optional): address of return location for accelerator char
+ * @error: address of return location for errors
  *
  * Parses marked-up text to create a plain-text string and an attribute list.
  *
@@ -726,10 +726,10 @@ 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) (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
+ * @attr_list: (out) (optional): address of return location for a `PangoAttrList`
+ * @text: (out) (optional): address of return location for text with tags stripped
+ * @accel_char: (out) (optional): address of return location for accelerator char
+ * @error: address of return location for errors
  *
  * Finishes parsing markup.
  *
diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c
index 471a5e51..666fe55a 100644
--- a/pango/pango-matrix.c
+++ b/pango/pango-matrix.c
@@ -32,13 +32,11 @@ G_DEFINE_BOXED_TYPE (PangoMatrix, pango_matrix,
 
 /**
  * pango_matrix_copy:
- * @matrix: (nullable): a `PangoMatrix`, may be %NULL
+ * @matrix: (nullable): a `PangoMatrix`
  *
  * Copies a `PangoMatrix`.
  *
- * Return value: (nullable): the newly allocated `PangoMatrix`, which
- *   should be freed with [method@Pango.Matrix.free], or %NULL if
- *   @matrix was %NULL.
+ * Return value: (nullable): the newly allocated `PangoMatrix`
  *
  * Since: 1.6
  */
@@ -211,9 +209,9 @@ pango_matrix_get_font_scale_factor (const PangoMatrix *matrix)
 
 /**
  * pango_matrix_get_font_scale_factors:
- * @matrix: (nullable): a `PangoMatrix`, 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
+ * @matrix: (nullable): a `PangoMatrix`
+ * @xscale: (out) (optional): output scale factor in the x direction
+ * @yscale: (out) (optional): output scale factor perpendicular to the x direction
  *
  * Calculates the scale factor of a matrix on the width and height of the font.
  *
@@ -266,7 +264,7 @@ pango_matrix_get_font_scale_factors (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_distance:
- * @matrix: (nullable): a `PangoMatrix`, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`
  * @dx: (inout): in/out X component of a distance vector
  * @dy: (inout): in/out Y component of a distance vector
  *
@@ -307,7 +305,7 @@ pango_matrix_transform_distance (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_point:
- * @matrix: (nullable): a `PangoMatrix`, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`
  * @x: (inout): in/out X position
  * @y: (inout): in/out Y position
  *
@@ -331,8 +329,8 @@ pango_matrix_transform_point (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_rectangle:
- * @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @rect: (inout) (optional): in/out bounding box in Pango units, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`
+ * @rect: (inout) (optional): in/out bounding box in Pango units
  *
  * First transforms @rect using @matrix, then calculates the bounding box
  * of the transformed rectangle.
@@ -411,8 +409,8 @@ pango_matrix_transform_rectangle (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_pixel_rectangle:
- * @matrix: (nullable): a `PangoMatrix`, or %NULL
- * @rect: (inout) (optional): in/out bounding box in device units, or %NULL
+ * @matrix: (nullable): a `PangoMatrix`
+ * @rect: (inout) (optional): in/out bounding box in device units
  *
  * First transforms the @rect using @matrix, then calculates the bounding box
  * of the transformed rectangle.
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index 37380e71..2d7b87c0 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -215,16 +215,13 @@ struct _PangoOTFeatureMap
  * PangoOTRulesetDescription:
  * @script: a `PangoScript`
  * @language: a `PangoLanguage`
- * @static_gsub_features: (nullable): static map of GSUB features,
- * or %NULL.
+ * @static_gsub_features: (nullable): static map of GSUB features
  * @n_static_gsub_features: length of @static_gsub_features, or 0.
- * @static_gpos_features: (nullable): static map of GPOS features,
- * or %NULL.
+ * @static_gpos_features: (nullable): static map of GPOS features
  * @n_static_gpos_features: length of @static_gpos_features, or 0.
  * @other_features: (nullable): map of extra features to add to both
- * GSUB and GPOS, or %NULL.  Unlike the static maps, this pointer
- * need not live beyond the life of function calls taking this
- * struct.
+ *   GSUB and GPOS. Unlike the static maps, this pointer need not
+ *   live beyond the life of function calls taking this struct.
  * @n_other_features: length of @other_features, or 0.
  *
  * The `PangoOTRuleset` structure holds all the information needed
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index c36f1921..49eec91d 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -801,12 +801,12 @@ pango_renderer_default_draw_glyphs (PangoRenderer    *renderer,
 /**
  * pango_renderer_draw_glyph_item:
  * @renderer: a `PangoRenderer`
- * @text: (nullable): the UTF-8 text that @glyph_item refers to, or %NULL
+ * @text: (nullable): the UTF-8 text that @glyph_item refers to
  * @glyph_item: a `PangoGlyphItem`
  * @x: X position of left edge of baseline, in user space coordinates
- *   in Pango units.
+ *   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
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 1bb65621..0792cd5a 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) (optional): location to store alignment, or %NULL
- * @location: (out) (optional): location to store tab position, or %NULL
+ * @alignment: (out) (optional): location to store alignment
+ * @location: (out) (optional): location to store tab position
  *
  * Gets the alignment and position of a tab stop.
  */
@@ -318,9 +318,9 @@ pango_tab_array_get_tab (PangoTabArray *tab_array,
  * pango_tab_array_get_tabs:
  * @tab_array: a `PangoTabArray`
  * @alignments: (out) (optional): location to store an array of tab
- *   stop alignments, or %NULL
+ *   stop alignments
  * @locations: (out) (optional) (array): location to store an array
- *   of tab positions, or %NULL
+ *   of tab positions
  *
  * If non-%NULL, @alignments and @locations are filled with allocated
  * arrays.
diff --git a/pango/pangocairo-font.c b/pango/pangocairo-font.c
index c4155f68..69c375c3 100644
--- a/pango/pangocairo-font.c
+++ b/pango/pangocairo-font.c
@@ -137,14 +137,14 @@ done:
 
 /**
  * pango_cairo_font_get_scaled_font:
- * @font: a `PangoFont` from a `PangoCairoFontMap`
+ * @font: (nullable): a `PangoFont` from a `PangoCairoFontMap`
  *
  * Gets the `cairo_scaled_font_t` used by @font.
  * The scaled font can be referenced and kept using
  * cairo_scaled_font_reference().
  *
  * Return value: (transfer none) (nullable): the `cairo_scaled_font_t`
- *   used by @font, or %NULL if @font is %NULL.
+ *   used by @font
  *
  * Since: 1.18
  */
diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c
index 524102ba..f16c3869 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -189,7 +189,7 @@ pango_cairo_font_map_get_default (void)
 
 /**
  * pango_cairo_font_map_set_default:
- * @fontmap: (nullable): The new default font map, or %NULL
+ * @fontmap: (nullable): The new default font map
  *
  * Sets a default `PangoCairoFontMap` to use with Cairo.
  *
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 2bd84276..cd063854 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -748,9 +748,9 @@ _pango_fc_font_set_font_key (PangoFcFont    *fcfont,
  * @fcfont: a `PangoFcFont`
  * @glyph: the glyph index to load
  * @ink_rect: (out) (optional): location to store ink extents of the
- *   glyph, or %NULL
+ *   glyph
  * @logical_rect: (out) (optional): location to store logical extents
- *   of the glyph or %NULL
+ *   of the glyph
  *
  * Gets the extents of a single glyph from a font.
  *
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 7c307bfb..77a7177b 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -2280,7 +2280,7 @@ pango_fc_font_map_config_changed (PangoFcFontMap *fcfontmap)
 /**
  * pango_fc_font_map_set_config: (skip)
  * @fcfontmap: a `PangoFcFontMap`
- * @fcconfig: (nullable): a `FcConfig`, or %NULL
+ * @fcconfig: (nullable): a `FcConfig`
  *
  * Set the `FcConfig` for this font map to use.
  *
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 1e1fff6f..d7ba539b 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -474,8 +474,7 @@ pango_xft_font_real_shutdown (PangoFcFont *fcfont)
  *
  * Returns the `XftFont` of a font.
  *
- * Return value: (nullable): the `XftFont` associated to @font,
- *   or %NULL if @font is %NULL.
+ * Return value: (nullable): the `XftFont` associated to @font
  */
 XftFont *
 pango_xft_font_get_font (PangoFont *font)
-- 
cgit v1.2.1