[glib/wip/doc-fixes: 1/8] docs: Describe GCompletion item memory management

[Ryan Lortie <ryanl src gnome org>]

commit fee9ae67da947d6ddfbc86dae2b74dfe6beddbd7
Author: David King <amigadave amigadave com>
Date:   Fri Feb 17 11:15:08 2012 +0000

    docs: Describe GCompletion item memory management
    
    https://bugzilla.gnome.org/show_bug.cgi?id=600751

 glib/deprecated/gcompletion.c |   20 +++++++++++++-------
 1 files changed, 13 insertions(+), 7 deletions(-)
---
diff --git a/glib/deprecated/gcompletion.c b/glib/deprecated/gcompletion.c
index 620af0e..7f7d7be 100644
--- a/glib/deprecated/gcompletion.c
+++ b/glib/deprecated/gcompletion.c
@@ -138,7 +138,7 @@ g_completion_new (GCompletionFunc func)
 /**
  * g_completion_add_items:
  * @cmp: the #GCompletion.
- * @items: the list of items to add.
+ * @items: (transfer none): the list of items to add.
  *
  * Adds items to the #GCompletion.
  *
@@ -176,9 +176,11 @@ g_completion_add_items (GCompletion* cmp,
 /**
  * g_completion_remove_items:
  * @cmp: the #GCompletion.
- * @items: the items to remove.
+ * @items: (transfer none): the items to remove.
  *
- * Removes items from a #GCompletion.
+ * Removes items from a #GCompletion. The items are not freed, so if the memory
+ * was dynamically allocated, free @items with g_list_free_full() after calling
+ * this function.
  *
  * Deprecated: 2.26: Rarely used API
  **/
@@ -209,7 +211,9 @@ g_completion_remove_items (GCompletion* cmp,
  * g_completion_clear_items:
  * @cmp: the #GCompletion.
  *
- * Removes all items from the #GCompletion.
+ * Removes all items from the #GCompletion. The items are not freed, so if the
+ * memory was dynamically allocated, it should be freed after calling this
+ * function.
  *
  * Deprecated: 2.26: Rarely used API
  **/
@@ -332,8 +336,8 @@ g_completion_complete_utf8 (GCompletion  *cmp,
  *              common to all items that matched @prefix, or %NULL if
  *              no items matched @prefix.  This string should be freed
  *              when no longer needed.
- * @Returns: the list of items whose strings begin with @prefix. This
- *           should not be changed.
+ * @Returns: (transfer none): the list of items whose strings begin with
+ *           @prefix. This should not be changed.
  *
  * Attempts to complete the string @prefix using the #GCompletion
  * target items.
@@ -406,7 +410,9 @@ g_completion_complete (GCompletion* cmp,
  * g_completion_free:
  * @cmp: the #GCompletion.
  *
- * Frees all memory used by the #GCompletion.
+ * Frees all memory used by the #GCompletion. The items are not freed, so if
+ * the memory was dynamically allocated, it should be freed after calling this
+ * function.
  *
  * Deprecated: 2.26: Rarely used API
  **/