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.

1 files changed, 57 insertions, 30 deletions

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)