Improve documentation for functions allocating memory, on how the object

2006-01-31  Behdad Esfahbod  <behdad@gnome.org>

        * pango/fonts.c, pango/glyphstring.c pango/pango-attributes.c
        pango/pango-color.c, pango/pango-context.c
        pango/pango-coverage.c, pango/pango-fontset.c
        pango/pango-glyph-item.c, pango/pango-item.c
        pango/pango-layout.c, pango/opentype/pango-ot-buffer.c
        pango/opentype/pango-ot-info.c, pango/opentype/pango-ot-ruleset.c
        pango/pango-script.c, pango/pango-tabs.c pango/pango-utils.c
        pango/pangocairo-fcfontmap.c, pango/pangocairo-fontmap.c
        pango/pangox-fontcache.c, pango/pangoxft-render.c:
        Improve documentation for functions allocating memory,
        on how the object should be freed.

19 files changed, 132 insertions, 67 deletions

diff --git a/ChangeLog b/ChangeLog
index 4094d013..e7e00f44 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2006-01-31  Behdad Esfahbod  <behdad@gnome.org>
+
+	* pango/fonts.c, pango/glyphstring.c pango/pango-attributes.c
+	pango/pango-color.c, pango/pango-context.c
+	pango/pango-coverage.c, pango/pango-fontset.c
+	pango/pango-glyph-item.c, pango/pango-item.c
+	pango/pango-layout.c, pango/opentype/pango-ot-buffer.c
+	pango/opentype/pango-ot-info.c, pango/opentype/pango-ot-ruleset.c
+	pango/pango-script.c, pango/pango-tabs.c pango/pango-utils.c
+	pango/pangocairo-fcfontmap.c, pango/pangocairo-fontmap.c
+	pango/pangox-fontcache.c, pango/pangoxft-render.c:
+	Improve documentation for functions allocating memory,
+	on how the object should be freed.
+
 2006-01-28  Behdad Esfahbod  <behdad@gnome.org>
 
 	* doc/tmpl/opentype.sgml: Document PangoOTBuffer and PangoOTGlyph.
diff --git a/pango/fonts.c b/pango/fonts.c
index 89f81dfd..885ba993 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -62,8 +62,8 @@ pango_font_description_get_type (void)
  * 
  * Creates a new font description structure with all fields unset.
  * 
- * Return value: the newly-created #PangoFontDescription. Use
- * pango_font_description_free() to free the result.
+ * Return value: the newly allocated #PangoFontDescription, which
+ *               should be freed using pango_font_description_free().
  **/
 PangoFontDescription *
 pango_font_description_new (void)
@@ -609,8 +609,8 @@ pango_font_description_better_match (const PangoFontDescription *desc,
  * 
  * Make a copy of a #PangoFontDescription.
  * 
- * Return value: a newly-allocated #PangoFontDescription. This value
- *               must be freed using pango_font_description_free().
+ * Return value: the newly allocated #PangoFontDescription, which should
+ *               be freed with pango_font_description_free().
  **/
 PangoFontDescription *
 pango_font_description_copy  (const PangoFontDescription  *desc)
@@ -634,8 +634,8 @@ pango_font_description_copy  (const PangoFontDescription  *desc)
  * be used until @desc is modififed or freed. This is meant to be used
  * when the copy is only needed temporarily.
  * 
- * Return value: a newly-allocated #PangoFontDescription. This value
- *               must be freed using pango_font_description_free().
+ * Return value: the newly allocated #PangoFontDescription, which should
+ *               be freed with pango_font_description_free().
  **/
 PangoFontDescription *
 pango_font_description_copy_static (const PangoFontDescription *desc)
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index 4c10f56e..3a9b236c 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -28,7 +28,8 @@
  *
  * Create a new PangoGlyphString.
  *
- * Returns the new PangoGlyphString
+ * Return value: the newly allocated #PangoGlyphString, which
+ *               should be freed with pango_glyph_string_free().
  */
 PangoGlyphString *
 pango_glyph_string_new (void)
@@ -90,7 +91,8 @@ pango_glyph_string_get_type (void)
  *
  *  Copy a glyph string and associated storage.
  *
- * Returns the copied PangoGlyphString
+ * Return value: the newly allocated #PangoGlyphString, which
+ *               should be freed with pango_glyph_string_free().
  */
 PangoGlyphString *
 pango_glyph_string_copy (PangoGlyphString *string)
@@ -111,7 +113,7 @@ pango_glyph_string_copy (PangoGlyphString *string)
  * pango_glyph_string_free:
  * @string:    a PangoGlyphString.
  *
- *  Free a glyph string and associated storage.
+ * Free a glyph string and associated storage.
  */
 void
 pango_glyph_string_free (PangoGlyphString *string)
diff --git a/pango/opentype/pango-ot-buffer.c b/pango/opentype/pango-ot-buffer.c
index 448024dd..00014dbd 100644
--- a/pango/opentype/pango-ot-buffer.c
+++ b/pango/opentype/pango-ot-buffer.c
@@ -30,7 +30,8 @@
  *
  * Creates a new #PangoOTBuffer for the given OpenType font.
  *
- * Return value: the new #PangoOTBuffer
+ * Return value: the newly allocated #PangoOTBuffer, which should
+ *               be freed with pango_ot_buffer_destroy().
  *
  * Since: 1.4
  **/ 
diff --git a/pango/opentype/pango-ot-ruleset.c b/pango/opentype/pango-ot-ruleset.c
index 071cdd61..002369dd 100644
--- a/pango/opentype/pango-ot-ruleset.c
+++ b/pango/opentype/pango-ot-ruleset.c
@@ -96,7 +96,8 @@ pango_ot_ruleset_finalize (GObject *object)
  *
  * Creates a new #PangoOTRuleset for the given OpenType info.
  *
- * Return value: a new #PangoOTRuleset.
+ * Return value: the newly allocated #PangoOTRuleset, which
+ *               should be freed with g_object_unref().
  **/
 PangoOTRuleset *
 pango_ot_ruleset_new (PangoOTInfo *info)
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 0aabcda4..3dedf500 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -56,7 +56,7 @@ static PangoAttribute *pango_attr_size_new_internal (int                   size,
 
 /**
  * pango_attr_type_register:
- * @name: an identifier for the type. (Currently unused.)
+ * @name: an identifier for the type (currently unused.)
  * 
  * Allocate a new attribute type ID.
  * 
@@ -76,7 +76,8 @@ pango_attr_type_register (const gchar *name)
  * 
  * Make a copy of an attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attribute_copy (const PangoAttribute *attr)
@@ -168,7 +169,8 @@ pango_attr_string_new (const PangoAttrClass *klass,
  * 
  * Create a new font family attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_family_new (const char *family)
@@ -210,7 +212,8 @@ pango_attr_language_equal (const PangoAttribute *attr1,
  * 
  * Create a new language tag attribute. 
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_language_new (PangoLanguage *language)
@@ -286,7 +289,8 @@ pango_attr_color_new (const PangoAttrClass *klass,
  * 
  * Create a new foreground color attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_foreground_new (guint16 red,
@@ -311,7 +315,8 @@ pango_attr_foreground_new (guint16 red,
  * 
  * Create a new background color attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_background_new (guint16 red,
@@ -458,7 +463,8 @@ pango_attr_size_new_internal (int size,
  * 
  * Create a new font-size attribute in fractional points.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_size_new (int size)
@@ -472,7 +478,8 @@ pango_attr_size_new (int size)
  * 
  * Create a new font-size attribute in device units.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  *
  * Since: 1.8
  **/
@@ -488,7 +495,8 @@ pango_attr_size_new_absolute (int size)
  * 
  * Create a new font slant style attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_style_new (PangoStyle style)
@@ -509,7 +517,8 @@ pango_attr_style_new (PangoStyle style)
  * 
  * Create a new font weight attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_weight_new (PangoWeight weight)
@@ -530,7 +539,8 @@ pango_attr_weight_new (PangoWeight weight)
  *
  * Create a new font variant attribute (normal or small caps)
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_variant_new (PangoVariant variant)
@@ -551,7 +561,8 @@ pango_attr_variant_new (PangoVariant variant)
  * 
  * Create a new font stretch attribute
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_stretch_new (PangoStretch  stretch)
@@ -601,7 +612,8 @@ pango_attr_font_desc_equal (const PangoAttribute *attr1,
  * allows setting family, style, weight, variant, stretch,
  * and size simultaneously.
  * 
- * Return value:  the new #PangoAttribute.
+ * Return value:  the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_font_desc_new (const PangoFontDescription *desc)
@@ -627,7 +639,8 @@ pango_attr_font_desc_new (const PangoFontDescription *desc)
  * 
  * Create a new underline-style attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_underline_new (PangoUnderline underline)
@@ -652,7 +665,8 @@ pango_attr_underline_new (PangoUnderline underline)
  * modifies the color of underlines. If not set, underlines
  * will use the foreground color.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  *
  * Since: 1.8
  **/
@@ -677,7 +691,8 @@ pango_attr_underline_color_new (guint16 red,
  * 
  * Create a new strike-through attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_strikethrough_new (gboolean strikethrough)
@@ -702,7 +717,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 new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  *
  * Since: 1.8
  **/
@@ -728,7 +744,8 @@ pango_attr_strikethrough_color_new (guint16 red,
  * 
  * Create a new baseline displacement attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_rise_new (int rise)
@@ -750,7 +767,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 new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute*
 pango_attr_scale_new (double scale_factor)
@@ -777,7 +795,8 @@ pango_attr_scale_new (double scale_factor)
  * other fonts on the system that might contain the characters in the
  * text.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  *
  * Since: 1.4
  **/
@@ -801,7 +820,8 @@ pango_attr_fallback_new (gboolean enable_fallback)
  * 
  * Create a new letter-spacing attribute.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  *
  * Since: 1.6
  **/
@@ -877,7 +897,8 @@ pango_attr_shape_equal (const PangoAttribute *attr1,
  * provided; this pointer can be accessed when later
  * rendering the glyph.
  * 
- * Return value: the new #PangoAttribute.
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  *
  * Since: 1.8
  **/
@@ -921,7 +942,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 new #PangoAttribute
+ * Return value: the newly allocated #PangoAttribute, which should be
+ *               freed with pango_attribute_destroy().
  **/
 PangoAttribute *
 pango_attr_shape_new (const PangoRectangle *ink_rect,
@@ -950,9 +972,10 @@ pango_attr_list_get_type (void)
 /**
  * pango_attr_list_new:
  * 
- * Create a new empty attribute list with a reference count of 1.
+ * Create a new empty attribute list with a reference count of one.
  * 
- * Return value: new #PangoAttrList.
+ * Return value: the newly allocated #PangoAttrList, which should
+ *               be freed with pango_attr_list_unref().
  **/
 PangoAttrList *
 pango_attr_list_new (void)
@@ -1024,9 +1047,11 @@ pango_attr_list_unref (PangoAttrList *list)
  * pango_attr_list_copy:
  * @list: a #PangoAttrList
  * 
- * Copy @list and return an identical, new list.
+ * Copy @list and return an identical new list.
  *
- * Return value: new attribute list
+ * Return value: the newly allocated #PangoAttrList, with a
+ *               reference count of one, which should
+ *               be freed with pango_attr_list_unref().
  **/
 PangoAttrList *
 pango_attr_list_copy (PangoAttrList *list)
@@ -1440,9 +1465,10 @@ pango_attr_list_splice (PangoAttrList *list,
  * @list: a #PangoAttrList
  * 
  * Create a iterator initialized to the beginning of the list.
+ * @list must not be modified until this iterator is freed.
  * 
- * Return value: a new #PangoIterator. @list must not be modified
- *               until this iterator is freed with pango_attr_iterator_destroy().
+ * Return value: the newly allocated #PangoAttrIterator, which should
+ *               be freed with pango_attr_iterator_destroy().
  **/
 PangoAttrIterator *
 pango_attr_list_get_iterator (PangoAttrList  *list)
@@ -1552,7 +1578,8 @@ pango_attr_iterator_next (PangoAttrIterator *iterator)
  * 
  * Copy a #PangoAttrIterator
  *
- * Return value: Copy of @iterator
+ * Return value: the newly allocated #PangoAttrIterator, which should
+ *               be freed with pango_attr_iterator_destroy().
  **/
 PangoAttrIterator *
 pango_attr_iterator_copy (PangoAttrIterator *iterator)
diff --git a/pango/pango-color.c b/pango/pango-color.c
index 3c0c8a1a..cf88b81c 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -47,7 +47,8 @@ pango_color_get_type (void)
  * not that useful otherwise (since colors can just be copied
  * by assignment in C).
  * 
- * Return value: the new #PangoColor
+ * Return value: the newly allocated #PangoColor, which should
+ *               be freed with pango_color_free().
  **/
 PangoColor*
 pango_color_copy (const PangoColor *src)
diff --git a/pango/pango-context.c b/pango/pango-context.c
index f53d2ef9..917db80d 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -111,7 +111,8 @@ pango_context_finalize (GObject *object)
  * gdk_pango_context_get_for_screen(), and 
  * gtk_widget_get_pango_context().
  * 
- * Return value: the new #PangoContext
+ * Return value: the newly allocated #PangoContext, which should
+ *               be freed with g_object_unref().
  **/
 PangoContext *
 pango_context_new (void)
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index 86be76a3..f7e82077 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -51,8 +51,10 @@ struct _PangoCoverage
  * 
  * Create a new #PangoCoverage
  * 
- * Return value: a new PangoCoverage object, initialized to %PANGO_COVERAGE_NONE
- *               with a reference count of 0.
+ * Return value: the newly allocated #PangoCoverage,
+ *               initialized to %PANGO_COVERAGE_NONE
+ *               with a reference count of one, which
+ *               should be freed with pango_coverage_unref().
  **/
 PangoCoverage *
 pango_coverage_new (void)
@@ -74,7 +76,9 @@ pango_coverage_new (void)
  * since we refcount the structure. Mail otaylor@redhat.com if you
  * use it.)
  * 
- * Return value: a copy of @coverage with a reference count of 1
+ * Return value: the newly allocated #PangoCoverage,
+ *               with a reference count of one, which
+ *               should be freed with pango_coverage_unref().
  **/
 PangoCoverage *
 pango_coverage_copy (PangoCoverage *coverage)
diff --git a/pango/pango-fontset.c b/pango/pango-fontset.c
index 66df6552..3c95bfc4 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -232,7 +232,8 @@ static PangoFontsetClass *simple_parent_class;	/* Parent class structure for Pan
  * 
  * Creates a new #PangoFontsetSimple for the given language.
  *
- * Return value: a newly-allocated #PangoFontsetSimple.
+ * Return value: the newly allocated #PangoFontsetSimple, which should
+ *               be freed with g_object_unref().
  **/
 PangoFontsetSimple *
 pango_fontset_simple_new (PangoLanguage *language)
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 73386dbb..090ddfbf 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -30,7 +30,7 @@
 /**
  * pango_glyph_item_split:
  * @orig: a #PangoItem
- * @text: text to which positions in @orig apply.
+ * @text: text to which positions in @orig apply
  * @split_index: byte index of position to split item, relative to the start of the item
  * 
  * Modifies @orig to cover only the text after @split_index, and
@@ -42,9 +42,11 @@
  * zero-length item).
  *
  * This function is similar in function to pango_item_split() (and uses
- * it internally)
+ * it internally.)
  * 
- * Return value: new item representing text before @split_index
+ * Return value: the newly allocated item representing text before
+ *               @split_index, which should be freed
+ *               with pango_glyph_item_free().
  *
  * Since: 1.2
  **/
diff --git a/pango/pango-item.c b/pango/pango-item.c
index a8b5aae0..eed378c5 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -27,7 +27,8 @@
  * 
  * Creates a new #PangoItem structure initialized to default values.
  * 
- * Return value: the new #PangoItem
+ * Return value: the newly allocated #PangoItem, which should
+ *               be freed with pango_item_free().
  **/
 PangoItem *
 pango_item_new (void)
@@ -43,7 +44,8 @@ pango_item_new (void)
  * 
  * Copy an existing #PangoItem structure.
  * 
- * Return value: the new #PangoItem
+ * Return value: the newly allocated #PangoItem, which should
+ *               be freed with pango_item_free().
  **/
 PangoItem *
 pango_item_copy (PangoItem *item)
@@ -122,7 +124,8 @@ pango_item_get_type (void)
  * item isn't available, so pango_item_split() can't count the char
  * length of the split items itself.
  * 
- * Return value: new item representing text before @split_index
+ * Return value: new item representing text before @split_index, which
+ *               should be freed with pango_item_free().
  **/
 PangoItem*
 pango_item_split (PangoItem  *orig,
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 6558c775..6b86e4d2 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -202,7 +202,9 @@ pango_layout_finalize (GObject *object)
  * Create a new #PangoLayout object with attributes initialized to
  * default values for a particular #PangoContext.
  * 
- * Return value: the new #PangoLayout, with a reference count of one.
+ * Return value: the newly allocated #PangoLayout, with a reference
+ *               count of one, which should be freed with
+ *               g_object_unref().
  **/
 PangoLayout *
 pango_layout_new (PangoContext *context)
@@ -227,7 +229,9 @@ pango_layout_new (PangoContext *context)
  * tab array, and text from the original layout are all copied by
  * value.
  * 
- * Return value: the new #PangoLayout.
+ * Return value: the newly allocated #PangoLayout, with a reference
+ *               count of one, which should be freed with
+ *               g_object_unref().
  **/
 PangoLayout*
 pango_layout_copy (PangoLayout *src)
diff --git a/pango/pango-script.c b/pango/pango-script.c
index cde37b80..2d754dc2 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -128,7 +128,8 @@ pango_script_for_unichar (gunichar ch)
  * the iterator is freed with pango_script_iter_free ().x
  * 
  * Return value: the new script iterator, initialized
- *  to point at the first range in the text. If the string is
+ *  to point at the first range in the text, which should be
+ *  freed with pango_script_iter_free(). If the string is
  *  empty, it will point at an empty range.
  *
  * Since: 1.4
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 5728733b..6b470687 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -62,7 +62,8 @@ init_tabs (PangoTabArray *array, gint start, gint end)
  * pixel units if @positions_in_pixels is %TRUE, otherwise in Pango
  * units. All stops are initially at position 0.
  * 
- * Return value: the new #PangoTabArray
+ * Return value: the newly allocated #PangoTabArray, which should
+ *               be freed with pango_tab_array_free().
  **/
 PangoTabArray*
 pango_tab_array_new (gint initial_size,
@@ -107,7 +108,8 @@ pango_tab_array_new (gint initial_size,
  * tab stop. You <emphasis>must</emphasis> provide an alignment
  * and position for @size tab stops.
  * 
- * Return value: the new #PangoTabArray
+ * Return value: the newly allocated #PangoTabArray, which should
+ *               be freed with pango_tab_array_free().
  **/
 PangoTabArray  *
 pango_tab_array_new_with_positions (gint           size,
@@ -170,7 +172,8 @@ pango_tab_array_get_type (void)
  * 
  * Copies a #PangoTabArray
  * 
- * Return value: the new #PangoTabArray.
+ * Return value: the newly allocated #PangoTabArray, which should
+ *               be freed with pango_tab_array_free().
  **/
 PangoTabArray*
 pango_tab_array_copy (PangoTabArray *src)
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 799af7a2..5000f489 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -1015,8 +1015,8 @@ pango_matrix_get_type (void)
  * 
  * Copies a #PangoMatrix.
  * 
- * Return value: a copy of @matrix. The result must be freed with
- *  pango_matrix_free().
+ * Return value: the newly allocated #PangoMatrix, which should
+ *               be freed with pango_matrix_free().
  *
  * Since: 1.6
  **/
diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c
index 9b7a4c83..052d3899 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -74,8 +74,8 @@ pango_cairo_font_map_get_type (void)
  * You generally should only use the #PangoFontMap and
  * #PangoCairoFontMap interfaces on the returned object.
  * 
- * Return value: the newly created fontmap object. Free
- * with g_object_unref().
+ * Return value: the newly allocated #PangoFontMap, which should
+ *               be freed with g_object_unref().
  *
  * Since: 1.10
  **/
diff --git a/pango/pangox-fontcache.c b/pango/pangox-fontcache.c
index b1e3ae60..31aea761 100644
--- a/pango/pangox-fontcache.c
+++ b/pango/pangox-fontcache.c
@@ -86,8 +86,8 @@ pango_x_font_cache_free (PangoXFontCache *cache)
  * 
  * Creates a font cache for the specified display.
  * 
- * Return value: The new font cache. This must be freed with
- * pango_x_font_cache_free().
+ * Return value: The newly allocated #PangoXFontCache, which should be
+ *               freed with pango_x_font_cache_free().
  **/
 PangoXFontCache *
 pango_x_font_cache_new (Display *display)
diff --git a/pango/pangoxft-render.c b/pango/pangoxft-render.c
index 79163e51..3b554b51 100644
--- a/pango/pangoxft-render.c
+++ b/pango/pangoxft-render.c
@@ -798,8 +798,8 @@ pango_xft_picture_render (Display          *display,
  * with the Xft library. You must call pango_xft_renderer_set_draw() before
  * using the renderer.
  *
- * Return value: the newly created #PangoXftRenderer object. Unref
- * with g_object_unref() when you are finished with it.
+ * Return value: the newly created #PangoXftRenderer, which should
+ *               be freed with g_object_unref().
  *
  * Since: 1.8
  **/