introspection: assorted fixes to avoid regressions in Vala bindings

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

12 files changed, 141 insertions, 121 deletions

diff --git a/pango/break.c b/pango/break.c
index 8acf3fa3..58d57d4b 100644
--- a/pango/break.c
+++ b/pango/break.c
@@ -1683,7 +1683,8 @@ tailor_break (const gchar   *text,
  * @text:      the text to process
  * @length:    length of @text in bytes (may be -1 if @text is nul-terminated)
  * @analysis:  #PangoAnalysis structure from pango_itemize()
- * @attrs:     an array to store character information in
+ * @attrs:     (array length=attrs_len): an array to store character
+ *             information in
  * @attrs_len: size of the array passed as @attrs
  *
  * Determines possible line, word, and character breaks
@@ -1708,8 +1709,10 @@ pango_break (const gchar   *text,
  * pango_find_paragraph_boundary:
  * @text: UTF-8 text
  * @length: length of @text in bytes, or -1 if nul-terminated
- * @paragraph_delimiter_index: return location for index of delimiter
- * @next_paragraph_start: return location for start of next paragraph
+ * @paragraph_delimiter_index: (out): return location for index of
+ *   delimiter
+ * @next_paragraph_start: (out): return location for start of next
+ *   paragraph
  *
  * Locates a paragraph boundary in @text. A boundary is caused by
  * delimiter characters, such as a newline, carriage return, carriage
@@ -1843,7 +1846,8 @@ tailor_segment (const char      *range_start,
  * @length: length in bytes of @text
  * @level: embedding level, or -1 if unknown
  * @language: language tag
- * @log_attrs: array with one #PangoLogAttr per character in @text, plus one extra, to be filled in
+ * @log_attrs: (array length=attrs_len): array with one #PangoLogAttr
+ *   per character in @text, plus one extra, to be filled in
  * @attrs_len: length of @log_attrs array
  *
  * Computes a #PangoLogAttr for each character in @text. The @log_attrs
diff --git a/pango/fonts.c b/pango/fonts.c
index b11da44a..384b57f3 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -1357,7 +1357,8 @@ parse_field (const char *what,
 /**
  * pango_parse_style:
  * @str: a string to parse.
- * @style: a #PangoStyle to store the result in.
+ * @style: (out caller-allocates): a #PangoStyle to store the result
+ *   in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
  * Parses a font style. The allowed values are "normal",
@@ -1377,7 +1378,8 @@ pango_parse_style (const char *str,
 /**
  * pango_parse_variant:
  * @str: a string to parse.
- * @variant: a #PangoVariant to store the result in.
+ * @variant: (out caller-allocates): a #PangoVariant to store the
+ *   result in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
  * Parses a font variant. The allowed values are "normal"
@@ -1397,7 +1399,8 @@ pango_parse_variant (const char   *str,
 /**
  * pango_parse_weight:
  * @str: a string to parse.
- * @weight: a #PangoWeight to store the result in.
+ * @weight: (out caller-allocates): a #PangoWeight to store the result
+ *   in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
  * Parses a font weight. The allowed values are "heavy",
@@ -1417,7 +1420,8 @@ pango_parse_weight (const char  *str,
 /**
  * pango_parse_stretch:
  * @str: a string to parse.
- * @stretch: a #PangoStretch to store the result in.
+ * @stretch: (out caller-allocates): a #PangoStretch to store the
+ *   result in.
  * @warn: if %TRUE, issue a g_warning() on bad input.
  *
  * Parses a font stretch. The allowed values are
@@ -1506,7 +1510,8 @@ pango_font_describe_with_absolute_size (PangoFont      *font)
  *
  * Computes the coverage map for a given font and language tag.
  *
- * Return value: a newly-allocated #PangoCoverage object.
+ * Return value: (transfer full): a newly-allocated #PangoCoverage
+ *   object.
  **/
 PangoCoverage *
 pango_font_get_coverage (PangoFont     *font,
@@ -2053,8 +2058,9 @@ pango_font_face_get_face_name (PangoFontFace *face)
 /**
  * pango_font_face_list_sizes:
  * @face: a #PangoFontFace.
- * @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): 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 58a30043..651907a2 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -149,10 +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: 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: 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): 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.
  *
  * 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
@@ -311,10 +313,10 @@ pango_glyph_string_get_width (PangoGlyphString *glyphs)
  * @text: the text corresponding to the glyphs
  * @length: the length of @text, in bytes
  * @embedding_level: the embedding level of the string
- * @logical_widths: an array whose length is the number of characters in
- *                  text (equal to g_utf8_strlen (text, length) unless
- *                  text has NUL bytes)
- *                  to be filled in with the resulting character widths.
+ * @logical_widths: (array): an array whose length is the number of
+ *                  characters in text (equal to g_utf8_strlen (text,
+ *                  length) unless text has NUL bytes) to be filled in
+ *                  with the resulting character widths.
  *
  * Given a #PangoGlyphString resulting from pango_shape() and the corresponding
  * text, determine the screen width corresponding to each character. When
@@ -359,7 +361,7 @@ pango_glyph_string_get_logical_widths (PangoGlyphString *glyphs,
  * @index_:    the byte index within @text
  * @trailing:  whether we should compute the result for the beginning (%FALSE)
  *             or end (%TRUE) of the character.
- * @x_pos:     location to store result
+ * @x_pos:     (out): location to store result
  *
  * Converts from character position to x position. (X position
  * is measured from the left edge of the run). Character positions
@@ -485,8 +487,8 @@ pango_glyph_string_index_to_x (PangoGlyphString *glyphs,
  * @length:    the number of bytes (not characters) in text.
  * @analysis:  the analysis information return from pango_itemize()
  * @x_pos:     the x offset (in Pango units)
- * @index_:    location to store calculated byte index within @text
- * @trailing:  location to store a boolean indicating
+ * @index_:    (out): location to store calculated byte index within @text
+ * @trailing:  (out): location to store a boolean indicating
  *             whether the user clicked on the leading or trailing
  *             edge of the character.
  *
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 4b9d5071..e76cb71d 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -139,8 +139,8 @@ pango_attribute_init (PangoAttribute       *attr,
  *
  * Make a copy of an attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attribute_copy (const PangoAttribute *attr)
@@ -233,8 +233,8 @@ pango_attr_string_new (const PangoAttrClass *klass,
  *
  * Create a new font family attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_family_new (const char *family)
@@ -278,8 +278,8 @@ pango_attr_language_equal (const PangoAttribute *attr1,
  *
  * Create a new language tag attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_language_new (PangoLanguage *language)
@@ -354,8 +354,8 @@ pango_attr_color_new (const PangoAttrClass *klass,
  *
  * Create a new foreground color attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_foreground_new (guint16 red,
@@ -380,8 +380,8 @@ pango_attr_foreground_new (guint16 red,
  *
  * Create a new background color attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_background_new (guint16 red,
@@ -534,8 +534,8 @@ pango_attr_size_new_internal (int size,
  *
  * Create a new font-size attribute in fractional points.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_size_new (int size)
@@ -566,8 +566,8 @@ pango_attr_size_new_absolute (int size)
  *
  * Create a new font slant style attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_style_new (PangoStyle style)
@@ -588,8 +588,8 @@ pango_attr_style_new (PangoStyle style)
  *
  * Create a new font weight attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_weight_new (PangoWeight weight)
@@ -610,8 +610,8 @@ pango_attr_weight_new (PangoWeight weight)
  *
  * Create a new font variant attribute (normal or small caps)
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_variant_new (PangoVariant variant)
@@ -632,8 +632,8 @@ pango_attr_variant_new (PangoVariant variant)
  *
  * Create a new font stretch attribute
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_stretch_new (PangoStretch  stretch)
@@ -685,8 +685,8 @@ pango_attr_font_desc_equal (const PangoAttribute *attr1,
  * allows setting family, style, weight, variant, stretch,
  * and size simultaneously.
  *
- * Return value:  the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_font_desc_new (const PangoFontDescription *desc)
@@ -712,8 +712,8 @@ pango_attr_font_desc_new (const PangoFontDescription *desc)
  *
  * Create a new underline-style attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_underline_new (PangoUnderline underline)
@@ -738,8 +738,8 @@ pango_attr_underline_new (PangoUnderline underline)
  * modifies the color of underlines. If not set, underlines
  * will use the foreground color.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  *
  * Since: 1.8
  **/
@@ -764,8 +764,8 @@ pango_attr_underline_color_new (guint16 red,
  *
  * Create a new strike-through attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_strikethrough_new (gboolean strikethrough)
@@ -790,8 +790,8 @@ pango_attr_strikethrough_new (gboolean strikethrough)
  * modifies the color of strikethrough lines. If not set, strikethrough
  * lines will use the foreground color.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  *
  * Since: 1.8
  **/
@@ -817,8 +817,8 @@ pango_attr_strikethrough_color_new (guint16 red,
  *
  * Create a new baseline displacement attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_rise_new (int rise)
@@ -840,8 +840,8 @@ pango_attr_rise_new (int rise)
  * Create a new font size scale attribute. The base font for the
  * affected text will have its size multiplied by @scale_factor.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute*
 pango_attr_scale_new (double scale_factor)
@@ -868,8 +868,8 @@ pango_attr_scale_new (double scale_factor)
  * other fonts on the system that might contain the characters in the
  * text.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  *
  * Since: 1.4
  **/
@@ -893,8 +893,8 @@ pango_attr_fallback_new (gboolean enable_fallback)
  *
  * Create a new letter-spacing attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  *
  * Since: 1.6
  **/
@@ -1015,8 +1015,8 @@ pango_attr_shape_new_with_data (const PangoRectangle  *ink_rect,
  * particular glyph. This might be used, for instance, for
  * embedding a picture or a widget inside a #PangoLayout.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_shape_new (const PangoRectangle *ink_rect,
@@ -1035,8 +1035,8 @@ pango_attr_shape_new (const PangoRectangle *ink_rect,
  *
  * Create a new gravity attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  *
  * Since: 1.16
  **/
@@ -1061,8 +1061,8 @@ pango_attr_gravity_new (PangoGravity gravity)
  *
  * Create a new gravity hint attribute.
  *
- * Return value: the newly allocated #PangoAttribute, which should be
- *               freed with pango_attribute_destroy().
+ * Return value: (transfer full): the newly allocated #PangoAttribute,
+ *               which should be freed with pango_attribute_destroy().
  *
  * Since: 1.16
  **/
@@ -1093,8 +1093,8 @@ G_DEFINE_BOXED_TYPE (PangoAttrList, pango_attr_list,
  *
  * Create a new empty attribute list with a reference count of one.
  *
- * Return value: the newly allocated #PangoAttrList, which should
- *               be freed with pango_attr_list_unref().
+ * Return value: (transfer full): the newly allocated #PangoAttrList,
+ *               which should be freed with pango_attr_list_unref().
  **/
 PangoAttrList *
 pango_attr_list_new (void)
@@ -1259,8 +1259,8 @@ pango_attr_list_insert_internal (PangoAttrList  *list,
 /**
  * pango_attr_list_insert:
  * @list: a #PangoAttrList
- * @attr: the attribute to insert. Ownership of this value is
- *        assumed by the list.
+ * @attr: (transfer full): the attribute to insert. Ownership of this
+ *        value is assumed by the list.
  *
  * Insert the given attribute into the #PangoAttrList. It will
  * be inserted after all other attributes with a matching
@@ -1279,8 +1279,8 @@ pango_attr_list_insert (PangoAttrList  *list,
 /**
  * pango_attr_list_insert_before:
  * @list: a #PangoAttrList
- * @attr: the attribute to insert. Ownership of this value is
- *        assumed by the list.
+ * @attr: (transfer full): the attribute to insert. Ownership of this
+ *        value is assumed by the list.
  *
  * Insert the given attribute into the #PangoAttrList. It will
  * be inserted before all other attributes with a matching
@@ -1299,8 +1299,8 @@ pango_attr_list_insert_before (PangoAttrList  *list,
 /**
  * pango_attr_list_change:
  * @list: a #PangoAttrList
- * @attr: the attribute to insert. Ownership of this value is
- *        assumed by the list.
+ * @attr: (transfer full): the attribute to insert. Ownership of this
+ *        value is assumed by the list.
  *
  * Insert the given attribute into the #PangoAttrList. It will
  * replace any attributes of the same type on that segment
@@ -1592,7 +1592,7 @@ pango_attr_list_splice (PangoAttrList *list,
  * Create a iterator initialized to the beginning of the list.
  * @list must not be modified until this iterator is freed.
  *
- * Return value: the newly allocated #PangoAttrIterator, which should
+ * Return value: (transfer full): the newly allocated #PangoAttrIterator, which should
  *               be freed with pango_attr_iterator_destroy().
  **/
 PangoAttrIterator *
@@ -1618,8 +1618,8 @@ pango_attr_list_get_iterator (PangoAttrList  *list)
 /**
  * pango_attr_iterator_range:
  * @iterator: a #PangoAttrIterator
- * @start: location to store the start of the range
- * @end: location to store the end of the range
+ * @start: (out): location to store the start of the range
+ * @end: (out): location to store the end of the range
  *
  * Get the range of the current segment. Note that the
  * stored return values are signed, not unsigned like
@@ -1703,8 +1703,9 @@ pango_attr_iterator_next (PangoAttrIterator *iterator)
  *
  * Copy a #PangoAttrIterator
  *
- * Return value: the newly allocated #PangoAttrIterator, which should
- *               be freed with pango_attr_iterator_destroy().
+ * Return value: (transfer full): the newly allocated
+ *               #PangoAttrIterator, which should be freed with
+ *               pango_attr_iterator_destroy().
  **/
 PangoAttrIterator *
 pango_attr_iterator_copy (PangoAttrIterator *iterator)
@@ -1747,8 +1748,8 @@ 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
+ * Return value: the current attribute of the given type, or %NULL if
+ *               no attribute of that type applies to the current
  *               location.
  **/
 PangoAttribute *
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index 59f97a3a..e22970de 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -112,9 +112,9 @@ struct _PangoAttribute
 };
 
 typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute,
-					 gpointer        data);
+					 gpointer        user_data);
 
-typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer data);
+typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
 
 struct _PangoAttrClass
 {
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index 7637117d..d84a5cd3 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -75,9 +75,9 @@ pango_coverage_new (void)
  * Copy an existing #PangoCoverage. (This function may now be unnecessary
  * since we refcount the structure. File a bug if you use it.)
  *
- * Return value: the newly allocated #PangoCoverage,
- *               with a reference count of one, which
- *               should be freed with pango_coverage_unref().
+ * Return value: (transfer full): the newly allocated #PangoCoverage,
+ *               with a reference count of one, which should be freed
+ *               with pango_coverage_unref().
  **/
 PangoCoverage *
 pango_coverage_copy (PangoCoverage *coverage)
@@ -352,8 +352,9 @@ pango_coverage_max (PangoCoverage *coverage,
 /**
  * pango_coverage_to_bytes:
  * @coverage: a #PangoCoverage
- * @bytes: location to store result (must be freed with g_free())
- * @n_bytes: location to store size of result
+ * @bytes: (out) (array length=n_bytes) (element-type guint8):
+ *   location to store result (must be freed with g_free())
+ * @n_bytes: (out): location to store size of result
  *
  * Convert a #PangoCoverage structure into a flat binary format
  **/
@@ -439,14 +440,15 @@ pango_coverage_get_uint32 (guchar **ptr)
 
 /**
  * pango_coverage_from_bytes:
- * @bytes: binary data representing a #PangoCoverage
+ * @bytes: (array length=n_bytes) (element-type guint8): binary data
+ *   representing a #PangoCoverage
  * @n_bytes: the size of @bytes in bytes
  *
  * Convert data generated from pango_converage_to_bytes() back
  * to a #PangoCoverage
  *
- * Return value: a newly allocated #PangoCoverage, or %NULL if
- *               the data was invalid.
+ * Return value: (transfer full): a newly allocated #PangoCoverage, or
+ *               %NULL if the data was invalid.
  **/
 PangoCoverage *
 pango_coverage_from_bytes (guchar *bytes,
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index 9f69ef69..282c2cd9 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -45,7 +45,7 @@ typedef struct _PangoFontset        PangoFontset;
  * PangoFontsetForeachFunc:
  * @fontset: a #PangoFontset
  * @font: a font from @fontset
- * @data: callback data
+ * @user_data: callback data
  *
  * A callback function used by pango_fontset_foreach() when enumerating
  * the fonts in a fontset.
@@ -56,7 +56,7 @@ typedef struct _PangoFontset        PangoFontset;
  **/
 typedef gboolean (*PangoFontsetForeachFunc) (PangoFontset  *fontset,
 					     PangoFont     *font,
-					     gpointer       data);
+					     gpointer       user_data);
 
 PangoFont *       pango_fontset_get_font    (PangoFontset           *fontset,
 					     guint                   wc);
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 9c13e8d4..98b06b8b 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -701,8 +701,8 @@ pango_glyph_item_apply_attrs (PangoGlyphItem   *glyph_item,
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
  *    start of @text)
- * @log_attrs: logical attributes for the item (the
- *   first logical attribute refers to the position
+ * @log_attrs: (array): logical attributes for the item
+ *   (the first logical attribute refers to the position
  *   before the first character in the item)
  * @letter_spacing: amount of letter spacing to add
  *   in Pango units. May be negative, though too large
@@ -774,9 +774,10 @@ pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
  * @text: text that @glyph_item corresponds to
  *   (glyph_item->item->offset is an offset from the
  *    start of @text)
- * @logical_widths: an array whose length is the number of characters in
- *                  glyph_item (equal to glyph_item->item->num_chars)
- *                  to be filled in with the resulting character widths.
+ * @logical_widths: (array): an array whose length is the number of
+ *                  characters in glyph_item (equal to
+ *                  glyph_item->item->num_chars) to be filled in with
+ *                  the resulting character widths.
  *
  * Given a #PangoGlyphItem and the corresponding
  * text, determine the screen width corresponding to each character. When
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 9ec4ab30..399abc78 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -244,8 +244,8 @@ _pango_get_lc_ctype (void)
  * functions automatically (by calling gtk_set_locale()).
  * See <literal>man setlocale</literal> for more details.
  *
- * Return value: the default language as a #PangoLanguage, must not be
- *               freed.
+ * Return value: (transfer none): the default language as a
+ *               #PangoLanguage, must not be freed.
  *
  * Since: 1.16
  **/
@@ -280,9 +280,10 @@ 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: 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.
+ * Return value: (transfer none): an opaque pointer to a
+ *               #PangoLanguage structure, or %NULL if @language was
+ *               %NULL.  The returned pointer will be valid forever
+ *               after, and should not be freed.
  **/
 PangoLanguage *
 pango_language_from_string (const char *language)
@@ -591,12 +592,12 @@ pango_language_get_sample_string (PangoLanguage *language)
  * The pango_language_includes_script() function uses this function
  * internally.
  *
- * Return value: 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): 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
  **/
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 91e0c6e6..16ecc4a2 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -625,7 +625,7 @@ pango_layout_set_attributes (PangoLayout   *layout,
  *
  * Gets the attribute list for the layout, if any.
  *
- * Return value: a #PangoAttrList.
+ * Return value: (transfer none): a #PangoAttrList.
  **/
 PangoAttrList*
 pango_layout_get_attributes (PangoLayout *layout)
@@ -1269,7 +1269,7 @@ pango_layout_context_changed (PangoLayout *layout)
  * @attrs: (out)(array length=n_attrs)(transfer container):
  *         location to store a pointer to an array of logical attributes
  *         This value must be freed with g_free().
- * @n_attrs: location to store the number of the attributes in the
+ * @n_attrs: (out): location to store the number of the attributes in the
  *           array. (The stored value will be one more than the total number
  *           of characters in the layout, since there need to be attributes
  *           corresponding to both the position before the first character
@@ -1300,7 +1300,8 @@ pango_layout_get_log_attrs (PangoLayout    *layout,
 /**
  * pango_layout_get_log_attrs_readonly:
  * @layout: a #PangoLayout
- * @n_attrs: location to store the number of the attributes in the array
+ * @n_attrs: (out): location to store the number of the attributes in
+ *   the array
  *
  * Retrieves an array of logical attributes for each character in
  * the @layout.
@@ -1314,7 +1315,7 @@ pango_layout_get_log_attrs (PangoLayout    *layout,
  * need to be attributes corresponding to both the position before
  * the first character and the position after the last character.
  *
- * Returns: an array of logical attributes
+ * Returns: (array length=n_attrs): an array of logical attributes
  *
  * Since: 1.30
  */
@@ -5699,7 +5700,8 @@ pango_layout_iter_get_line (PangoLayoutIter *iter)
  * but the user is not expected
  * to modify the contents of the line (glyphs, glyph widths, etc.).
  *
- * Return value: the current line, that should not be modified.
+ * Return value: (transfer none): the current line, that should not be
+ * modified.
  *
  * Since: 1.16
  **/
@@ -6003,7 +6005,8 @@ pango_layout_iter_next_line (PangoLayoutIter *iter)
 /**
  * pango_layout_iter_get_char_extents:
  * @iter: a #PangoLayoutIter
- * @logical_rect: rectangle to fill with logical extents
+ * @logical_rect: (out caller-allocates): rectangle to fill with
+ *   logical extents
  *
  * Gets the extents of the current character, in layout coordinates
  * (origin is the top left of the entire layout). Only logical extents
diff --git a/pango/pango-renderer.c b/pango/pango-renderer.c
index e17bcbe7..54161448 100644
--- a/pango/pango-renderer.c
+++ b/pango/pango-renderer.c
@@ -1391,8 +1391,8 @@ pango_renderer_get_layout (PangoRenderer *renderer)
  * The returned layout line should not be modified while still being
  * rendered.
  *
- * Return value: the layout line, or %NULL if no layout line is being
- *  rendered using @renderer at this time.
+ * Return value: (transfer none): 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-tabs.c b/pango/pango-tabs.c
index 6c4a7f31..751538cd 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -309,10 +309,10 @@ 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 stop
- *                                  alignments, or %NULL
- * @locations: (out) (allow-none): location to store an array of tab positions,
- *                                 or %NULL
+ * @alignments: (out) (allow-none): location to store an array of tab
+ *   stop alignments, or %NULL
+ * @locations: (out) (allow-none) (array): location to store an array
+ *   of tab positions, or %NULL
  *
  * If non-%NULL, @alignments and @locations are filled with allocated
  * arrays of length pango_tab_array_get_size(). You must free the