Add many missing nullability annotations.

https://bugzilla.gnome.org/show_bug.cgi?id=731022

37 files changed, 241 insertions, 218 deletions

diff --git a/pango/break.c b/pango/break.c
index 5f3c339a..1f4aafd7 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -468,7 +468,7 @@ typedef enum
  * pango_default_break:
  * @text: text to break
  * @length: length of text in bytes (may be -1 if @text is nul-terminated)
- * @analysis: a #PangoAnalysis for the @text
+ * @analysis: (nullable): a #PangoAnalysis for the @text
  * @attrs: logical attributes to fill in
  * @attrs_len: size of the array passed as @attrs
  *
diff --git a/pango/fonts.c b/pango/fonts.c
index d92a9033..52ef72df 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -164,9 +164,10 @@ pango_font_description_set_family_static (PangoFontDescription *desc,
  * Gets the family name field of a font description. See
  * pango_font_description_set_family().
  *
- * Return value: the family name field for the font description, or
- *               %NULL if not previously set.  This has the same life-time
- *               as the font description itself and should not be freed.
+ * Return value: (nullable): the family name field for the font
+ *               description, or %NULL if not previously set.  This
+ *               has the same life-time as the font description itself
+ *               and should not be freed.
  **/
 const char *
 pango_font_description_get_family (const PangoFontDescription *desc)
@@ -669,13 +670,14 @@ pango_font_description_better_match (const PangoFontDescription *desc,
 
 /**
  * pango_font_description_copy:
- * @desc: a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a #PangoFontDescription, may be %NULL
  *
  * Make a copy of a #PangoFontDescription.
  *
- * Return value: the newly allocated #PangoFontDescription, which should
- *               be freed with pango_font_description_free(), or %NULL
- *               if @desc was %NULL.
+ * Return value: (nullable): the newly allocated
+ *               #PangoFontDescription, which should be freed with
+ *               pango_font_description_free(), or %NULL if @desc was
+ *               %NULL.
  **/
 PangoFontDescription *
 pango_font_description_copy  (const PangoFontDescription  *desc)
@@ -700,16 +702,17 @@ pango_font_description_copy  (const PangoFontDescription  *desc)
 
 /**
  * pango_font_description_copy_static:
- * @desc: a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a #PangoFontDescription, may be %NULL
  *
  * Like pango_font_description_copy(), but only a shallow copy is made
  * of the family name and other allocated fields. The result can only
  * be used until @desc is modified or freed. This is meant to be used
  * when the copy is only needed temporarily.
  *
- * Return value: the newly allocated #PangoFontDescription, which should
- *               be freed with pango_font_description_free(), or %NULL
- *               if @desc was %NULL.
+ * Return value: (nullable): the newly allocated
+ *               #PangoFontDescription, which should be freed with
+ *               pango_font_description_free(), or %NULL if @desc was
+ *               %NULL.
  **/
 PangoFontDescription *
 pango_font_description_copy_static (const PangoFontDescription *desc)
@@ -810,7 +813,7 @@ pango_font_description_hash (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_free:
- * @desc: a #PangoFontDescription, may be %NULL
+ * @desc: (nullable): a #PangoFontDescription, may be %NULL
  *
  * Frees a font description.
  **/
@@ -1564,7 +1567,7 @@ pango_font_find_shaper (PangoFont     *font,
 
 /**
  * pango_font_get_glyph_extents:
- * @font: a #PangoFont
+ * @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.
@@ -1612,7 +1615,7 @@ pango_font_get_glyph_extents  (PangoFont      *font,
 
 /**
  * pango_font_get_metrics:
- * @font: a #PangoFont
+ * @font: (nullable): a #PangoFont
  * @language: (allow-none): language tag used to determine which script to get the metrics
  *            for, or %NULL to indicate to get the metrics for the entire font.
  *
@@ -1652,7 +1655,7 @@ pango_font_get_metrics (PangoFont        *font,
 
 /**
  * pango_font_get_font_map:
- * @font: a #PangoFont, or %NULL
+ * @font: (nullable): a #PangoFont, or %NULL
  *
  * Gets the font map for which the font was created.
  *
@@ -1664,8 +1667,8 @@ pango_font_get_metrics (PangoFont        *font,
  * alive.  In most uses this is not an issue as a #PangoContext holds
  * a reference to the font map.
  *
- * Return value: (transfer none): the #PangoFontMap for the font, or %NULL
- *               if @font is %NULL.
+ * Return value: (transfer none) (nullable): the #PangoFontMap for the
+ *               font, or %NULL if @font is %NULL.
  *
  * Since: 1.10
  **/
@@ -1706,11 +1709,11 @@ pango_font_metrics_new (void)
 
 /**
  * pango_font_metrics_ref:
- * @metrics: a #PangoFontMetrics structure, may be %NULL
+ * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL
  *
  * Increase the reference count of a font metrics structure by one.
  *
- * Return value: @metrics
+ * Return value: (nullable): @metrics
  **/
 PangoFontMetrics *
 pango_font_metrics_ref (PangoFontMetrics *metrics)
@@ -1725,7 +1728,7 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_unref:
- * @metrics: a #PangoFontMetrics structure, may be %NULL
+ * @metrics: (nullable): a #PangoFontMetrics structure, may be %NULL
  *
  * Decrease the reference count of a font metrics structure by one. If
  * the result is zero, frees the structure and any associated
@@ -2073,9 +2076,9 @@ pango_font_face_get_face_name (PangoFontFace *face)
 /**
  * pango_font_face_list_sizes:
  * @face: a #PangoFontFace.
- * @sizes: (out) (array length=n_sizes): location to store a pointer
- *         to an array of int. This array should be freed with
- *         g_free().
+ * @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().
  * @n_sizes: location to store the number of elements in @sizes
  *
  * List the available sizes for a font. This is only applicable to bitmap
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index 651907a2..007f8a34 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -97,12 +97,12 @@ G_DEFINE_BOXED_TYPE (PangoGlyphString, pango_glyph_string,
 
 /**
  * pango_glyph_string_copy:
- * @string: a #PangoGlyphString, may be %NULL
+ * @string: (nullable): a #PangoGlyphString, may be %NULL
  *
  * Copy a glyph string and associated storage.
  *
- * Return value: the newly allocated #PangoGlyphString, which
- *               should be freed with pango_glyph_string_free(),
+ * Return value: (nullable): the newly allocated #PangoGlyphString,
+ *               which should be freed with pango_glyph_string_free(),
  *               or %NULL if @string was %NULL.
  */
 PangoGlyphString *
@@ -127,7 +127,7 @@ pango_glyph_string_copy (PangoGlyphString *string)
 
 /**
  * pango_glyph_string_free:
- * @string: a #PangoGlyphString, may be %NULL
+ * @string: (nullable): a #PangoGlyphString, may be %NULL
  *
  * Free a glyph string and associated storage.
  */
@@ -149,12 +149,12 @@ pango_glyph_string_free (PangoGlyphString *string)
  * @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): rectangle used to store the
- *            extents of the glyph string range as drawn or %NULL to
- *            indicate that the result is not needed.
- * @logical_rect: (out caller-allocates): rectangle used to store the
- *            logical extents of the glyph string range or %NULL to
- *            indicate that the result is not needed.
+ * @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.
+ * @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.
  *
  * Computes the extents of a sub-portion of a glyph string. The extents are
  * relative to the start of the glyph string range (the origin of their
diff --git a/pango/modules.c b/pango/modules.c
index 73935bdc..d8ff79c1 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -734,8 +734,8 @@ build_map (PangoMapInfo *info)
  *
  * Returns the best engine listed in the map for a given script
  *
- * Return value: the best engine, if one is listed for the script,
- *    or %NULL. The lookup may cause the engine to be loaded;
+ * Return value: (nullable): the best engine, if one is listed for the
+ *    script, or %NULL. The lookup may cause the engine to be loaded;
  *    once an engine is loaded, it won't be unloaded. If multiple
  *    engines are exact for the script, the choice of which is
  *    returned is arbitrary.
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 9059b1de..09dcbbde 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -110,8 +110,8 @@ pango_attr_type_register (const gchar *name)
  * The returned value is an interned string (see g_intern_string() for what
  * that means) that should not be modified or freed.
  *
- * Return value: 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
  **/
@@ -1132,7 +1132,7 @@ pango_attr_list_new (void)
 
 /**
  * pango_attr_list_ref:
- * @list: a #PangoAttrList, may be %NULL
+ * @list: (nullable): a #PangoAttrList, may be %NULL
  *
  * Increase the reference count of the given attribute list by one.
  *
@@ -1153,7 +1153,7 @@ pango_attr_list_ref (PangoAttrList *list)
 
 /**
  * pango_attr_list_unref:
- * @list: a #PangoAttrList, may be %NULL
+ * @list: (nullable): a #PangoAttrList, may be %NULL
  *
  * Decrease the reference count of the given attribute list by one.
  * If the result is zero, free the attribute list and the attributes
@@ -1188,11 +1188,11 @@ pango_attr_list_unref (PangoAttrList *list)
 
 /**
  * pango_attr_list_copy:
- * @list: a #PangoAttrList, may be %NULL
+ * @list (nullable): a #PangoAttrList, may be %NULL
  *
  * Copy @list and return an identical new list.
  *
- * Return value: the newly allocated #PangoAttrList, with a
+ * Return value: (nullable): the newly allocated #PangoAttrList, with a
  *               reference count of one, which should
  *               be freed with pango_attr_list_unref().
  *               Returns %NULL if @list was %NULL.
@@ -1770,9 +1770,9 @@ pango_attr_iterator_destroy (PangoAttrIterator *iterator)
  * the attribute whose range starts closest to the current location
  * is used.
  *
- * Return value: the current attribute of the given type, or %NULL if
- *               no attribute of that type applies to the current
- *               location.
+ * Return value: (nullable): 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,
@@ -1966,8 +1966,8 @@ pango_attr_iterator_get_font (PangoAttrIterator     *iterator,
  * of @list for which @func returns %TRUE and inserts them into
  * a new list.
  *
- * Return value: (transfer full): 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
  **/
diff --git a/pango/pango-color.c b/pango/pango-color.c
index e54eb0d3..47a98236 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -33,16 +33,16 @@ G_DEFINE_BOXED_TYPE (PangoColor, pango_color,
 
 /**
  * pango_color_copy:
- * @src: color to copy, may be %NULL
+ * @src: (nullable): color to copy, may be %NULL
  *
  * Creates a copy of @src, which 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).
  *
- * Return value: the newly allocated #PangoColor, which should
- *               be freed with pango_color_free(), or %NULL
- *               if @src was %NULL.
+ * Return value: (nullable): the newly allocated #PangoColor, which
+ *               should be freed with pango_color_free(), or %NULL if
+ *               @src was %NULL.
  **/
 PangoColor*
 pango_color_copy (const PangoColor *src)
@@ -61,7 +61,7 @@ pango_color_copy (const PangoColor *src)
 
 /**
  * pango_color_free:
- * @color: an allocated #PangoColor, may be %NULL
+ * @color: (nullable): an allocated #PangoColor, may be %NULL
  *
  * Frees a color allocated by pango_color_copy().
  **/
@@ -207,7 +207,8 @@ hex (const char *spec,
 
 /**
  * pango_color_parse:
- * @color: a #PangoColor structure in which to store the result, or %NULL
+ * @color: (nullable): a #PangoColor structure in which to store the
+ *   result, or %NULL
  * @spec: a string specifying the new color
  *
  * Fill in the fields of a color from a string specification. The
diff --git a/pango/pango-context.c b/pango/pango-context.c
index ff95b5c2..6f72653b 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -203,10 +203,9 @@ pango_context_set_matrix (PangoContext       *context,
  * Gets the transformation matrix that will be applied when
  * rendering with this context. See pango_context_set_matrix().
  *
- * Return value: the matrix, or %NULL if no matrix has been set
- *  (which is the same as the identity matrix). The returned
- *  matrix is owned by Pango and must not be modified or
- *  freed.
+ * Return value: (nullable): the matrix, or %NULL if no matrix has
+ *  been set (which is the same as the identity matrix). The returned
+ *  matrix is owned by Pango and must not be modified or freed.
  *
  * Since: 1.6
  **/
@@ -309,8 +308,8 @@ pango_context_list_families (PangoContext          *context,
  * Loads the font in one of the fontmaps in the context
  * that is the closest match for @desc.
  *
- * Returns: (transfer full): the newly allocated #PangoFont that
- *          was loaded, or %NULL if no font matched.
+ * Returns: (transfer full) (nullable): the newly allocated #PangoFont
+ *          that was loaded, or %NULL if no font matched.
  **/
 PangoFont *
 pango_context_load_font (PangoContext               *context,
@@ -331,8 +330,8 @@ pango_context_load_font (PangoContext               *context,
  * Load a set of fonts in the context that can be used to render
  * a font matching @desc.
  *
- * Returns: (transfer full): the newly allocated #PangoFontset loaded,
- *          or %NULL if no font matched.
+ * Returns: (transfer full) (nullable): the newly allocated
+ *          #PangoFontset loaded, or %NULL if no font matched.
  **/
 PangoFontset *
 pango_context_load_fontset (PangoContext               *context,
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index eccd4f99..80fded2b 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -457,8 +457,8 @@ pango_coverage_get_uint32 (guchar **ptr)
  * Convert data generated from pango_coverage_to_bytes() back
  * to a #PangoCoverage
  *
- * Return value: (transfer full): a newly allocated #PangoCoverage, or
- *               %NULL if the data was invalid.
+ * Return value: (transfer full) (nullable): a newly allocated
+ *               #PangoCoverage, or %NULL if the data was invalid.
  **/
 PangoCoverage *
 pango_coverage_from_bytes (guchar *bytes,
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 0b8abbe3..dc146c00 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -114,12 +114,12 @@ struct _PangoEngineLang
 
 /**
  * PangoEngineLangClass:
- * @script_break: Provides a custom implementation of pango_break().
- * If %NULL, pango_default_break() is used instead. If not %NULL, for
- * Pango versions before 1.16 (module interface version before 1.6.0),
- * this was called instead of pango_default_break(), but in newer versions,
- * pango_default_break() is always called and this is called after that to
- * allow tailoring the breaking results.
+ * @script_break: (nullable): Provides a custom implementation of
+ * pango_break().  If %NULL, pango_default_break() is used instead. If
+ * not %NULL, for Pango versions before 1.16 (module interface version
+ * before 1.6.0), this was called instead of pango_default_break(),
+ * 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
  **/
@@ -347,8 +347,8 @@ prefix ## _register_type (GTypeModule *module)				  \
  * PANGO_ENGINE_LANG_DEFINE_TYPE:
  * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
  * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
- * @class_init: Class initialization function for the new type, or %NULL
- * @instance_init: Instance initialization function for the new type, or %NULL
+ * @class_init: (nullable): Class initialization function for the new type, or %NULL
+ * @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
@@ -377,8 +377,8 @@ prefix ## _register_type (GTypeModule *module)				  \
  * PANGO_ENGINE_SHAPE_DEFINE_TYPE:
  * @name: Name of the the type to register (for example:, <literal>ArabicEngineFc</literal>
  * @prefix: Prefix for symbols that will be defined (for example:, <literal>arabic_engine_fc</literal>
- * @class_init: Class initialization function for the new type, or %NULL
- * @instance_init: Instance initialization function for the new type, or %NULL
+ * @class_init: (nullable): Class initialization function for the new type, or %NULL
+ * @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
diff --git a/pango/pango-fontmap.c b/pango/pango-fontmap.c
index 50e23df0..2a2804b6 100644
--- a/pango/pango-fontmap.c
+++ b/pango/pango-fontmap.c
@@ -82,8 +82,8 @@ pango_font_map_create_context (PangoFontMap *fontmap)
  *
  * Load the font in the fontmap that is the closest match for @desc.
  *
- * Returns: (transfer full): the newly allocated #PangoFont loaded,
- *          or %NULL if no font matched.
+ * Returns: (transfer full) (nullable): the newly allocated #PangoFont
+ *          loaded, or %NULL if no font matched.
  **/
 PangoFont *
 pango_font_map_load_font  (PangoFontMap               *fontmap,
@@ -124,8 +124,8 @@ pango_font_map_list_families (PangoFontMap      *fontmap,
  * Load a set of fonts in the fontmap that can be used to render
  * a font matching @desc.
  *
- * Returns: (transfer full): the newly allocated #PangoFontset
- *          loaded, or %NULL if no font matched.
+ * Returns: (transfer full) (nullable): the newly allocated
+ *          #PangoFontset loaded, or %NULL if no font matched.
  **/
 PangoFontset *
 pango_font_map_load_fontset (PangoFontMap                 *fontmap,
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 647a31f3..1d4ff8ea 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -131,11 +131,11 @@ pango_glyph_item_split (PangoGlyphItem *orig,
 
 /**
  * pango_glyph_item_copy:
- * @orig: a #PangoGlyphItem, may be %NULL
+ * @orig: (nullable): a #PangoGlyphItem, may be %NULL
  *
  * Make a deep copy of an existing #PangoGlyphItem structure.
  *
- * Return value: the newly allocated #PangoGlyphItem, which should
+ * Return value: (nullable): the newly allocated #PangoGlyphItem, which should
  *               be freed with pango_glyph_item_free(), or %NULL
  *               if @orig was %NULL.
  *
@@ -159,7 +159,7 @@ pango_glyph_item_copy  (PangoGlyphItem *orig)
 
 /**
  * pango_glyph_item_free:
- * @glyph_item: a #PangoGlyphItem, may be %NULL
+ * @glyph_item: (nullable): a #PangoGlyphItem, may be %NULL
  *
  * Frees a #PangoGlyphItem and resources to which it points.
  *
@@ -186,11 +186,11 @@ G_DEFINE_BOXED_TYPE (PangoGlyphItem, pango_glyph_item,
 
 /**
  * pango_glyph_item_iter_copy:
- * @orig: a #PangoGlyphItemIter, may be %NULL
+ * @orig: (nullable): a #PangoGlyphItemIter, may be %NULL
  *
  * Make a shallow copy of an existing #PangoGlyphItemIter structure.
  *
- * Return value: the newly allocated #PangoGlyphItemIter, which should
+ * Return value: (nullable): the newly allocated #PangoGlyphItemIter, which should
  *               be freed with pango_glyph_item_iter_free(), or %NULL
  *               if @orig was %NULL.
  *
@@ -213,7 +213,7 @@ pango_glyph_item_iter_copy  (PangoGlyphItemIter *orig)
 
 /**
  * pango_glyph_item_iter_free:
- * @iter: a #PangoGlyphItemIter, may be %NULL
+ * @iter: (nullable): a #PangoGlyphItemIter, may be %NULL
  *
  * Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy().
  *
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index a72b67bc..ebaf17e6 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -120,7 +120,7 @@ pango_gravity_to_rotation (PangoGravity gravity)
 
 /**
  * pango_gravity_get_for_matrix:
- * @matrix: a #PangoMatrix
+ * @matrix: (nullable): a #PangoMatrix
  *
  * Finds the gravity that best matches the rotation component
  * in a #PangoMatrix.
diff --git a/pango/pango-item.c b/pango/pango-item.c
index 0437d9ce..8c368874 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -42,13 +42,13 @@ pango_item_new (void)
 
 /**
  * pango_item_copy:
- * @item: a #PangoItem, may be %NULL
+ * @item: (nullable): a #PangoItem, may be %NULL
  *
  * Copy an existing #PangoItem structure.
  *
- * Return value: the newly allocated #PangoItem, which should
- *               be freed with pango_item_free(), or %NULL if
- *               @item was NULL.
+ * Return value: (nullable): the newly allocated #PangoItem, which
+ *               should be freed with pango_item_free(), or %NULL if
+ *               @item was %NULL.
  **/
 PangoItem *
 pango_item_copy (PangoItem *item)
@@ -84,7 +84,7 @@ pango_item_copy (PangoItem *item)
 
 /**
  * pango_item_free:
- * @item: a #PangoItem, may be %NULL
+ * @item: (nullable): a #PangoItem, may be %NULL
  *
  * Free a #PangoItem and all associated memory.
  **/
diff --git a/pango/pango-language.c b/pango/pango-language.c
index e9c9d1f4..1247ae72 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -301,7 +301,7 @@ pango_language_get_default (void)
  * Use pango_language_get_default() if you want to get the #PangoLanguage for
  * the current locale of the process.
  *
- * Return value: (transfer none): an opaque pointer to a
+ * 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.
@@ -368,7 +368,7 @@ const char *
 
 /**
  * pango_language_matches:
- * @language: a language tag (see pango_language_from_string()),
+ * @language: (nullable): a language tag (see pango_language_from_string()),
  *            %NULL is allowed and matches nothing but '*'
  * @range_list: a list of language ranges, separated by ';', ':',
  *   ',', or space characters.
@@ -542,7 +542,7 @@ static const LangInfo lang_texts[] = {
 
 /**
  * pango_language_get_sample_string:
- * @language: a #PangoLanguage, or %NULL
+ * @language: (nullable): a #PangoLanguage, or %NULL
  *
  * Get a string that is representative of the characters needed to
  * render a particular language.
@@ -619,12 +619,12 @@ pango_language_get_sample_string (PangoLanguage *language)
  * The pango_language_includes_script() function uses this function
  * internally.
  *
- * Return value: (array length=num_scripts): 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: (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.
  
  * Since: 1.22
  **/
@@ -663,7 +663,7 @@ pango_language_get_scripts (PangoLanguage *language,
 
 /**
  * pango_language_includes_script:
- * @language: a #PangoLanguage, or %NULL
+ * @language: (nullable): a #PangoLanguage, or %NULL
  * @script: a #PangoScript
  *
  * Determines if @script is one of the scripts used to
@@ -846,7 +846,7 @@ out:
  * choose a default language for %PANGO_SCRIPT_HAN when setting
  * context language is not feasible.
  *
- * Return value: a #PangoLanguage that is representative
+ * Return value: (nullable): a #PangoLanguage that is representative
  * of the script, or %NULL if no such language exists.
  *
  * Since: 1.4
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 607a5f0e..68c50f0a 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -727,10 +727,10 @@ pango_layout_set_font_description (PangoLayout                 *layout,
  *
  * Gets the font description for the layout, if any.
  *
- * Return value: 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: (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
  **/
@@ -923,7 +923,8 @@ pango_layout_set_tabs (PangoLayout   *layout,
  * and %NULL is returned. Default tabs are every 8 spaces.
  * The return value should be freed with pango_tab_array_free().
  *
- * Return value: a copy of the tabs for this layout, or %NULL.
+ * Return value: (nullable): a copy of the tabs for this layout, or
+ * %NULL.
  **/
 PangoTabArray*
 pango_layout_get_tabs (PangoLayout *layout)
@@ -1532,10 +1533,11 @@ pango_layout_get_lines_readonly (PangoLayout *layout)
  * Use the faster pango_layout_get_line_readonly() if you do not plan
  * to modify the contents of the line (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none): 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: (transfer none) (nullable): 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.
  **/
 PangoLayoutLine *
 pango_layout_get_line (PangoLayout *layout,
@@ -1574,11 +1576,11 @@ pango_layout_get_line (PangoLayout *layout,
  * but the user is not expected
  * to modify the contents of the line (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none): 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.
- *               No changes should be made to the line.
+ * Return value: (transfer none) (nullable): 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.  No changes should be made to the line.
  *
  * Since: 1.16
  **/
@@ -4062,7 +4064,7 @@ pango_layout_check_lines (PangoLayout *layout)
 
 /**
  * pango_layout_line_ref:
- * @line: a #PangoLayoutLine, may be %NULL
+ * @line: (nullable): a #PangoLayoutLine, may be %NULL
  *
  * Increase the reference count of a #PangoLayoutLine by one.
  *
@@ -5592,13 +5594,13 @@ update_run (PangoLayoutIter *iter,
 
 /**
  * pango_layout_iter_copy:
- * @iter: a #PangoLayoutIter, may be %NULL
+ * @iter: (nullable): a #PangoLayoutIter, may be %NULL
  *
  * Copies a #PangoLayoutIter.
  *
- * Return value: the newly allocated #PangoLayoutIter, which should
- *               be freed with pango_layout_iter_free(), or %NULL if
- *               @iter was %NULL.
+ * Return value: (nullable): the newly allocated #PangoLayoutIter,
+ *               which should be freed with pango_layout_iter_free(),
+ *               or %NULL if @iter was %NULL.
  *
  * Since: 1.20
  **/
@@ -5711,7 +5713,7 @@ pango_layout_get_iter (PangoLayout *layout)
 
 /**
  * pango_layout_iter_free:
- * @iter: a #PangoLayoutIter, may be %NULL
+ * @iter: (nullable): a #PangoLayoutIter, may be %NULL
  *
  * Frees an iterator that's no longer in use.
  **/
@@ -5760,7 +5762,7 @@ pango_layout_iter_get_index (PangoLayoutIter *iter)
  * Use the faster pango_layout_iter_get_run_readonly() if you do not plan
  * to modify the contents of the run (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none): the current run.
+ * Return value: (transfer none) (nullable): the current run.
  **/
 PangoLayoutRun*
 pango_layout_iter_get_run (PangoLayoutIter *iter)
@@ -5786,7 +5788,8 @@ pango_layout_iter_get_run (PangoLayoutIter *iter)
  * but the user is not expected
  * to modify the contents of the run (glyphs, glyph widths, etc.).
  *
- * Return value: (transfer none): the current run, that should not be modified.
+ * Return value: (transfer none) (nullable): the current run, that
+ * should not be modified.
  *
  * Since: 1.16
  **/
diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c
index 50a4c800..b4c27d71 100644
--- a/pango/pango-matrix.c
+++ b/pango/pango-matrix.c
@@ -32,12 +32,12 @@ G_DEFINE_BOXED_TYPE (PangoMatrix, pango_matrix,
 
 /**
  * pango_matrix_copy:
- * @matrix: a #PangoMatrix, may be %NULL
+ * @matrix: (nullable): a #PangoMatrix, may be %NULL
  *
  * Copies a #PangoMatrix.
  *
- * Return value: the newly allocated #PangoMatrix, which should
- *               be freed with pango_matrix_free(), or %NULL if
+ * Return value: (nullable): the newly allocated #PangoMatrix, which
+ *               should be freed with pango_matrix_free(), or %NULL if
  *               @matrix was %NULL.
  *
  * Since: 1.6
@@ -59,7 +59,7 @@ pango_matrix_copy (const PangoMatrix *matrix)
 
 /**
  * pango_matrix_free:
- * @matrix: a #PangoMatrix, may be %NULL
+ * @matrix: (nullable): a #PangoMatrix, may be %NULL
  *
  * Free a #PangoMatrix created with pango_matrix_copy().
  *
@@ -243,7 +243,7 @@ pango_matrix_get_font_scale_factor (const PangoMatrix *matrix)
 
 /**
  * pango_matrix_transform_distance:
- * @matrix: a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a #PangoMatrix, or %NULL
  * @dx: (inout): in/out X component of a distance vector
  * @dy: (inout): in/out Y component of a distance vector
  *
@@ -283,7 +283,7 @@ pango_matrix_transform_distance (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_point:
- * @matrix: a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a #PangoMatrix, or %NULL
  * @x: (inout): in/out X position
  * @y: (inout): in/out Y position
  *
@@ -307,7 +307,7 @@ pango_matrix_transform_point (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_rectangle:
- * @matrix: a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a #PangoMatrix, or %NULL
  * @rect: (inout) (allow-none): in/out bounding box in Pango units, or %NULL
  *
  * First transforms @rect using @matrix, then calculates the bounding box
@@ -387,7 +387,7 @@ pango_matrix_transform_rectangle (const PangoMatrix *matrix,
 
 /**
  * pango_matrix_transform_pixel_rectangle:
- * @matrix: a #PangoMatrix, or %NULL
+ * @matrix: (nullable): a #PangoMatrix, or %NULL
  * @rect: (inout) (allow-none): in/out bounding box in device units, or %NULL
  *
  * First transforms the @rect using @matrix, then calculates the bounding box
diff --git a/pango/pango-ot-buffer.c b/pango/pango-ot-buffer.c
index 35d66bce..142b2f17 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -134,8 +134,10 @@ pango_ot_buffer_set_zero_width_marks (PangoOTBuffer     *buffer,
 /**
  * pango_ot_buffer_get_glyphs
  * @buffer: a #PangoOTBuffer
- * @glyphs: location to store the array of glyphs, or %NULL
- * @n_glyphs: location to store the number of glyphs, or %NULL
+ * @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
  *
  * 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
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index d494d7f4..28f5dbc9 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -123,7 +123,8 @@ get_hb_table_type (PangoOTTableType table_type)
  * @info: a #PangoOTInfo.
  * @table_type: the table type to obtain information about.
  * @script_tag: the tag of the script to find.
- * @script_index: location to store the index of the script, or %NULL.
+ * @script_index: (out) (optional): location to store the index of the
+ *   script, or %NULL.
  *
  * 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.
@@ -156,9 +157,10 @@ pango_ot_info_find_script (PangoOTInfo      *info,
  * @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: location to store the index of the language, or %NULL.
- * @required_feature_index: location to store the required feature index of
- *    the language, or %NULL.
+ * @language_index: (out) (optional): location to store the index of
+ *   the language, or %NULL.
+ * @required_feature_index: (out) (optional): location to store the
+ *    required feature index of the language, or %NULL.
  *
  * Finds the index of a language and its required feature index.
  * If the language is not found, sets @language_index to
@@ -205,7 +207,8 @@ pango_ot_info_find_language (PangoOTInfo      *info,
  * @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.
- * @feature_index: location to store the index of the feature, or %NULL.
+ * @feature_index: (out) (optional): location to store the index of
+ *   the feature, or %NULL.
  *
  * 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
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 2d8f1503..40e46254 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -267,8 +267,10 @@ pango_ot_ruleset_maybe_add_features (PangoOTRuleset          *ruleset,
 /**
  * pango_ot_ruleset_get_feature_count:
  * @ruleset: a #PangoOTRuleset.
- * @n_gsub_features: location to store number of GSUB features, or %NULL.
- * @n_gpos_features: location to store number of GPOS features, or %NULL.
+ * @n_gsub_featuresL: (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.
  *
  * Gets the number of GSUB and GPOS features in the ruleset.
  *
diff --git a/pango/pango-ot-tag.c b/pango/pango-ot-tag.c
index 711e36eb..610b59d7 100644
--- a/pango/pango-ot-tag.c
+++ b/pango/pango-ot-tag.c
@@ -81,7 +81,7 @@ pango_ot_tag_to_script (PangoOTTag script_tag)
 
 /**
  * pango_ot_tag_from_language:
- * @language: A #PangoLanguage, or %NULL
+ * @language: (nullable): A #PangoLanguage, or %NULL
  *
  * Finds the OpenType language-system tag best describing @language.
  *
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index a27ed201..c60c3014 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -212,13 +212,16 @@ struct _PangoOTFeatureMap
  * PangoOTRulesetDescription:
  * @script: a #PangoScript.
  * @language: a #PangoLanguage.
- * @static_gsub_features: static map of GSUB features, or %NULL.
+ * @static_gsub_features: (nullable): static map of GSUB features,
+ * or %NULL.
  * @n_static_gsub_features: length of @static_gsub_features, or 0.
- * @static_gpos_features: static map of GPOS features, or %NULL.
+ * @static_gpos_features: (nullable): static map of GPOS features,
+ * or %NULL.
  * @n_static_gpos_features: length of @static_gpos_features, or 0.
- * @other_features: 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.
+ * @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.
  * @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 e30af474..d7dfa037 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -1181,9 +1181,9 @@ pango_renderer_set_color (PangoRenderer    *renderer,
  *
  * Gets the current rendering color for the specified part.
  *
- * Return value: (transfer none): the color for the specified part, or
- *  %NULL if it hasn't been set and should be inherited from the
- *  environment.
+ * Return value: (transfer none) (nullable): the color for the
+ *   specified part, or %NULL if it hasn't been set and should be
+ *   inherited from the environment.
  *
  * Since: 1.8
  **/
@@ -1340,10 +1340,9 @@ pango_renderer_set_matrix (PangoRenderer     *renderer,
  * Gets the transformation matrix that will be applied when
  * rendering. See pango_renderer_set_matrix().
  *
- * Return value: the matrix, or %NULL if no matrix has been set
- *  (which is the same as the identity matrix). The returned
- *  matrix is owned by Pango and must not be modified or
- *  freed.
+ * Return value: (nullable): the matrix, or %NULL if no matrix has
+ *  been set (which is the same as the identity matrix). The returned
+ *  matrix is owned by Pango and must not be modified or freed.
  *
  * Since: 1.8
  **/
@@ -1366,8 +1365,8 @@ pango_renderer_get_matrix (PangoRenderer *renderer)
  * The returned layout should not be modified while still being
  * rendered.
  *
- * Return value: (transfer none): the layout, or %NULL if no layout is being
- *  rendered using @renderer at this time.
+ * Return value: (transfer none) (nullable): the layout, or %NULL if
+ *  no layout is being rendered using @renderer at this time.
  *
  * Since: 1.20
  **/
@@ -1391,8 +1390,8 @@ pango_renderer_get_layout (PangoRenderer *renderer)
  * The returned layout line should not be modified while still being
  * rendered.
  *
- * Return value: (transfer none): the layout line, or %NULL if no
- *   layout line is being rendered using @renderer at this time.
+ * Return value: (transfer none) (nullable): the layout line, or %NULL
+ *   if no layout line is being rendered using @renderer at this time.
  *
  * Since: 1.20
  **/
diff --git a/pango/pango-renderer.h b/pango/pango-renderer.h
index 5410a9fe..63d9e656 100644
--- a/pango/pango-renderer.h
+++ b/pango/pango-renderer.h
@@ -59,8 +59,9 @@ typedef enum
 
 /**
  * PangoRenderer:
- * @matrix: the current transformation matrix for the Renderer; may
- *    be %NULL, which should be treated the same as the identity matrix.
+ * @matrix: (nullable): the current transformation matrix for
+ *    the Renderer; may be %NULL, which should be treated the
+ *    same as the identity matrix.
  *
  * #PangoRenderer is a base class for objects that are used to
  * render Pango objects such as #PangoGlyphString and
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 3dfcebde..591ac5bd 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -128,10 +128,10 @@ pango_version_string (void)
  *
  * For compile-time version checking use PANGO_VERSION_CHECK().
  *
- * Return value: %NULL if the Pango library is compatible with the
- *   given version, or a string describing the version mismatch.
- *   The returned string is owned by Pango and should not be modified
- *   or freed.
+ * Return value: (nullable): %NULL if the Pango library is compatible
+ *   with the given version, or a string describing the version
+ *   mismatch.  The returned string is owned by Pango and should not
+ *   be modified or freed.
  *
  * Since: 1.16
  **/
@@ -666,8 +666,8 @@ read_config (void)
  * Looks up a key, consulting only the Pango system config database
  * in $sysconfdir/pango/pangorc.
  *
- * Return value: the value, if found, otherwise %NULL. The value is a
- * newly-allocated string and must be freed with g_free().
+ * Return value: (nullable): the value, if found, otherwise %NULL. The
+ * value is a newly-allocated string and must be freed with g_free().
  **/
 char *
 pango_config_key_get_system (const char *key)
@@ -692,8 +692,8 @@ pango_config_key_get_system (const char *key)
  * (pseudo-win.ini style, read from $sysconfdir/pango/pangorc,
  *  $XDG_CONFIG_HOME/pango/pangorc, and getenv (PANGO_RC_FILE).)
  *
- * Return value: the value, if found, otherwise %NULL. The value is a
- * newly-allocated string and must be freed with g_free().
+ * Return value: (nullable): the value, if found, otherwise %NULL. The
+ * value is a newly-allocated string and must be freed with g_free().
  **/
 char *
 pango_config_key_get (const char *key)
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 9750fb03..9dd02351 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -218,8 +218,8 @@ pango_cairo_context_get_resolution (PangoContext *context)
 /**
  * pango_cairo_context_set_font_options:
  * @context: a #PangoContext, from a pangocairo font map
- * @options: a #cairo_font_options_t, or %NULL to unset any previously set
- *           options. A copy is made.
+ * @options: (nullable): a #cairo_font_options_t, or %NULL to unset
+ *           any previously set options. A copy is made.
  *
  * Sets the font options used when rendering text with this context.
  * These options override any options that pango_cairo_update_context()
@@ -263,9 +263,9 @@ pango_cairo_context_set_font_options (PangoContext               *context,
  * pango_cairo_context_set_font_options(). This function does not report options
  * that are derived from the target surface by pango_cairo_update_context()
  *
- * Return value: the font options previously set on the context, or %NULL
- *   if no options have been set. This value is owned by the context
- *   and must not be modified or freed.
+ * Return value: (nullable): the font options previously set on the
+ *   context, or %NULL if no options have been set. This value is
+ *   owned by the context and must not be modified or freed.
  *
  * Since: 1.10
  **/
@@ -316,8 +316,8 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
 /**
  * pango_cairo_context_set_shape_renderer:
  * @context: a #PangoContext, from a pangocairo font map
- * @func: Callback function for rendering attributes of type
- * %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
+ * @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.
@@ -361,8 +361,9 @@ pango_cairo_context_set_shape_renderer (PangoContext                *context,
  * attributes of type %PANGO_ATTR_SHAPE as set by
  * pango_cairo_context_set_shape_renderer(), if any.
  *
- * Return value: the shape rendering callback previously set on the context, or %NULL
- *   if no shape rendering callback have been set.
+ * Return value: (nullable): the shape rendering callback previously
+ *   set on the context, or %NULL if no shape rendering callback have
+ *   been set.
  *
  * Since: 1.18
  */
diff --git a/pango/pangocairo-font.c b/pango/pangocairo-font.c
index 97281012..8164840e 100644
--- a/pango/pangocairo-font.c
+++ b/pango/pangocairo-font.c
@@ -142,7 +142,7 @@ done:
  * The scaled font can be referenced and kept using
  * cairo_scaled_font_reference().
  *
- * Return value: the #cairo_scaled_font_t used by @font,
+ * Return value: (nullable): the #cairo_scaled_font_t used by @font,
  *               or %NULL if @font is %NULL.
  *
  * Since: 1.18
diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c
index 1a529fca..177dbbce 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -121,10 +121,10 @@ pango_cairo_font_map_new (void)
  * or in fact in most of those cases, just use
  * @pango_cairo_font_map_get_default().
  *
- * Return value: (transfer full) : the newly allocated #PangoFontMap
- *               of suitable type which should be freed with
- *               g_object_unref(), or %NULL if the requested cairo
- *               font backend is not supported / compiled in.
+ * Return value: (transfer full) (nullable): the newly allocated
+ *               #PangoFontMap of suitable type which should be freed
+ *               with g_object_unref(), or %NULL if the requested
+ *               cairo font backend is not supported / compiled in.
  *
  * Since: 1.18
  **/
@@ -196,7 +196,7 @@ pango_cairo_font_map_get_default (void)
 
 /**
  * pango_cairo_font_map_set_default:
- * @fontmap: The new default font map, or %NULL
+ * @fontmap: (nullable): The new default font map, or %NULL
  *
  * Sets a default #PangoCairoFontMap to use with Cairo.
  *
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 7056bca9..9ae2f56c 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -958,8 +958,10 @@ get_per_char (FT_Face      face,
  * @fcfont: a #PangoFcFont
  * @load_flags: flags to pass to FT_Load_Glyph()
  * @glyph: the glyph index to load
- * @ink_rect: location to store ink extents of the glyph, or %NULL
- * @logical_rect: location to store logical extents of the glyph or %NULL
+ * @ink_rect: (out) (optional): location to store ink extents of the
+ *   glyph, or %NULL
+ * @logical_rect: (out) (optional): location to store logical extents
+ *   of the glyph or %NULL
  *
  * Gets the extents of a single glyph from a font. The extents are in
  * user space; that is, they are not transformed by any matrix in effect
diff --git a/pango/pangofc-font.h b/pango/pangofc-font.h
index e9738295..51a6e952 100644
--- a/pango/pangofc-font.h
+++ b/pango/pangofc-font.h
@@ -93,13 +93,12 @@ struct _PangoFcFont
  *   corresponding to the specified character.
  * @get_glyph: Gets the glyph that corresponds to the given
  *   Unicode character.
- * @get_unknown_glyph: Gets the glyph that should be used to
- *   display an unknown-glyph indication for the specified
- *   Unicode character.
- *   May be %NULL.
- * @shutdown: Performs any font-specific shutdown code that
- *   needs to be done when pango_fc_font_map_shutdown is called.
- *   May be %NULL.
+ * @get_unknown_glyph: (nullable): Gets the glyph that
+ *   should be used to display an unknown-glyph indication
+ *   for the specified Unicode character.  May be %NULL.
+ * @shutdown: (nullable): Performs any font-specific
+ *   shutdown code that needs to be done when
+ *   pango_fc_font_map_shutdown is called.  May be %NULL.
  *
  * Class structure for #PangoFcFont.
  **/
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index e7034589..d12ead6c 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -1190,8 +1190,8 @@ pango_fc_font_map_add_decoder_find_func (PangoFcFontMap        *fcfontmap,
  * Finds the decoder to use for @pattern.  Decoders can be added to
  * a font map using pango_fc_font_map_add_decoder_find_func().
  *
- * Returns: a newly created #PangoFcDecoder object or %NULL if
- *          no decoder is set for @pattern.
+ * Returns: (nullable): a newly created #PangoFcDecoder object or
+ *          %NULL if no decoder is set for @pattern.
  *
  * Since: 1.26
  **/
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 3948b1f1..612996c8 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -102,10 +102,10 @@ struct _PangoFcFontMap
 
 /**
  * PangoFcFontMapClass:
- * @default_substitute: Substitutes in default values for
- *  unspecified fields in a #FcPattern. This will be called
- *  prior to creating a font for the pattern. May be %NULL.
- *  Deprecated in favor of @font_key_substitute().
+ * @default_substitute: (nullable): Substitutes in default
+ *  values for unspecified fields in a #FcPattern. This will
+ *  be called prior to creating a font for the pattern. May be
+ *  %NULL.  Deprecated in favor of @font_key_substitute().
  * @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
@@ -128,17 +128,17 @@ struct _PangoFcFontMap
  *  @context_key_copy.
  * @context_key_hash: Gets a hash value for a context key
  * @context_key_equal: Compares two context keys for equality.
- * @fontset_key_substitute: Substitutes in default values for
- *  unspecified fields in a #FcPattern. This will be called
- *  prior to creating a font for the pattern. May be %NULL.
- *  (Since: 1.24)
- * @create_font: 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 you call
- *  g_object_new().  If %NULL, new_font() is used.
+ * @fontset_key_substitute: (nullable): Substitutes in
+ *  default values for unspecified fields in a
+ *  #FcPattern. This will be called prior to creating a font
+ *  for the pattern. May be %NULL.  (Since: 1.24)
+ * @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
+ *  you call g_object_new().  If %NULL, new_font() is used.
  *  (Since: 1.24)
  *
  * Class structure for #PangoFcFontMap.
diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c
index 2b0ebd53..131b1da7 100644
--- a/pango/pangoft2-render.c
+++ b/pango/pangoft2-render.c
@@ -699,7 +699,8 @@ 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:  a #PangoMatrix, or %NULL to use an identity transformation
+ * @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)
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index 3ada81c9..186424d4 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -169,8 +169,9 @@ set_transform (PangoFT2Font *ft2font)
  * face from pango_fc_font_lock_face() you must call
  * pango_fc_font_unlock_face().
  *
- * Return value: a pointer to a <type>FT_Face</type> structure, with the size set correctly,
- *               or %NULL if @font is %NULL.
+ * Return value: (nullable): a pointer to a <type>FT_Face</type>
+ *               structure, with the size set correctly, or %NULL if
+ *               @font is %NULL.
  **/
 FT_Face
 pango_ft2_font_get_face (PangoFont *font)
diff --git a/pango/pangowin32-fontcache.c b/pango/pangowin32-fontcache.c
index a7cfec69..b8bc92dc 100644
--- a/pango/pangowin32-fontcache.c
+++ b/pango/pangowin32-fontcache.c
@@ -185,8 +185,8 @@ cache_entry_unref (PangoWin32FontCache *cache,
  * result may be newly loaded, or it may have been previously
  * stored
  *
- * Return value: The font structure, or %NULL if the font could
- * not be loaded. In order to free this structure, you must call
+ * 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().
  **/
 HFONT
@@ -215,8 +215,8 @@ pango_win32_font_cache_load (PangoWin32FontCache *cache,
  * result may be newly loaded, or it may have been previously
  * stored
  *
- * Return value: The font structure, or %NULL if the font could
- * not be loaded. In order to free this structure, you must call
+ * 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().
  *
  * Since: 1.16
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index 6948037f..be64f7dc 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -382,7 +382,8 @@ pango_win32_render (HDC               hdc,
 /**
  * pango_win32_render_transformed:
  * @hdc:     a windows device context
- * @matrix:  a #PangoMatrix, or %NULL to use an identity transformation
+ * @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
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 4e5dcb7b..91856304 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -501,11 +501,12 @@ pango_xft_font_real_shutdown (PangoFcFont *fcfont)
 
 /**
  * pango_xft_font_get_font:
- * @font: a #PangoFont.
+ * @font: (nullable): a #PangoFont.
  *
  * Returns the XftFont of a font.
  *
- * Return value: the XftFont associated to @font, or %NULL if @font is %NULL.
+ * Return value: (nullable): the XftFont associated to @font, or %NULL
+ * if @font is %NULL.
  **/
 XftFont *
 pango_xft_font_get_font (PangoFont *font)
diff --git a/pango/pangoxft-render.c b/pango/pangoxft-render.c
index 855d3328..9b3c936f 100644
--- a/pango/pangoxft-render.c
+++ b/pango/pangoxft-render.c
@@ -786,7 +786,8 @@ pango_xft_render_layout_line (XftDraw         *draw,
  * @draw:    an #XftDraw
  * @color:   the color in which to draw the glyphs
  * @font:    the font in which to draw the string
- * @matrix:  a #PangoMatrix, or %NULL to use an identity transformation
+ * @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)