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/pango-ot-buffer.c
        pango/pango-ot-info.c, pango/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 f0cb1b3d..712ce948 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/pango-ot-buffer.c
+	pango/pango-ot-info.c, pango/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-30  Behdad Esfahbod  <behdad@gnome.org>
 
 	* === Released 1.11.3 ===
diff --git a/pango/fonts.c b/pango/fonts.c
index 4835a198..98d1fae1 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -80,8 +80,8 @@ static const PangoFontDescription pfd_defaults = {
  * 
  * 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)
@@ -591,8 +591,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)
@@ -619,8 +619,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 53a529a0..fc677c3a 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -30,7 +30,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)
@@ -95,7 +96,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)
@@ -116,7 +118,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/pango-attributes.c b/pango/pango-attributes.c
index b89e5c6c..05d50528 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -57,7 +57,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.
  * 
@@ -77,7 +77,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)
@@ -171,7 +172,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)
@@ -215,7 +217,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)
@@ -293,7 +296,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,
@@ -318,7 +322,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,
@@ -471,7 +476,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)
@@ -485,7 +491,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
  **/
@@ -501,7 +508,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)
@@ -522,7 +530,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)
@@ -543,7 +552,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)
@@ -564,7 +574,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)
@@ -614,7 +625,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)
@@ -640,7 +652,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)
@@ -665,7 +678,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
  **/
@@ -690,7 +704,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)
@@ -715,7 +730,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
  **/
@@ -741,7 +757,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)
@@ -763,7 +780,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)
@@ -790,7 +808,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
  **/
@@ -814,7 +833,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
  **/
@@ -890,7 +910,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
  **/
@@ -934,7 +955,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,
@@ -963,9 +985,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)
@@ -1037,9 +1060,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)
@@ -1453,9 +1478,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)
@@ -1565,7 +1591,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 0e552d28..8bb4aef8 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -49,7 +49,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 e3651120..c47cf9ab 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -112,7 +112,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 6e34f802..c8f79d89 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -52,8 +52,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)
@@ -75,7 +77,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 f40330b2..dee12de4 100644
--- a/pango/pango-fontset.c
+++ b/pango/pango-fontset.c
@@ -234,7 +234,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 89744df1..6cfd3826 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -31,7 +31,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
@@ -43,9 +43,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 7cf3bebe..844cd098 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -29,7 +29,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)
@@ -45,7 +46,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)
@@ -124,7 +126,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 77a266fd..dd92b944 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -204,7 +204,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)
@@ -229,7 +231,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-ot-buffer.c b/pango/pango-ot-buffer.c
index c4828a55..275cce6a 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -32,7 +32,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/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 975ea5d2..e50b2a1e 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -99,7 +99,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-script.c b/pango/pango-script.c
index d0a35920..4435f393 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -146,7 +146,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 c5d727ae..d2821b5b 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -64,7 +64,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,
@@ -109,7 +110,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,
@@ -172,7 +174,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 5ae1246f..eae158f9 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 d5c55dac..6eb4a63b 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -78,8 +78,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 90257be4..301d8b2f 100644
--- a/pango/pangox-fontcache.c
+++ b/pango/pangox-fontcache.c
@@ -89,8 +89,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 953db916..3df15245 100644
--- a/pango/pangoxft-render.c
+++ b/pango/pangoxft-render.c
@@ -799,8 +799,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
  **/