summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog14
-rw-r--r--pango/fonts.c12
-rw-r--r--pango/glyphstring.c8
-rw-r--r--pango/pango-attributes.c87
-rw-r--r--pango/pango-color.c3
-rw-r--r--pango/pango-context.c3
-rw-r--r--pango/pango-coverage.c10
-rw-r--r--pango/pango-fontset.c3
-rw-r--r--pango/pango-glyph-item.c8
-rw-r--r--pango/pango-item.c9
-rw-r--r--pango/pango-layout.c8
-rw-r--r--pango/pango-ot-buffer.c3
-rw-r--r--pango/pango-ot-ruleset.c3
-rw-r--r--pango/pango-script.c3
-rw-r--r--pango/pango-tabs.c9
-rw-r--r--pango/pango-utils.c4
-rw-r--r--pango/pangocairo-fontmap.c4
-rw-r--r--pango/pangox-fontcache.c4
-rw-r--r--pango/pangoxft-render.c4
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
**/