Bug 500361 – Improve docs for g_array_free() and g_ptr_array_free()

2007-11-29  Behdad Esfahbod  <behdad@gnome.org>

        Bug 500361 – Improve docs for g_array_free() and g_ptr_array_free()

        * glib/tmpl/arrays.sgml:
        * glib/tmpl/arrays_pointer.sgml:
        Document how to free the return value.

svn path=/trunk/; revision=5998

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f3e2813..f6fd996 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,11 @@
+2007-11-29  Behdad Esfahbod  <behdad@gnome.org>
+
+       Bug 500361 – Improve docs for g_array_free() and g_ptr_array_free()
+
+       * glib/tmpl/arrays.sgml:
+       * glib/tmpl/arrays_pointer.sgml:
+       Document how to free the return value.
+
 2007-11-28  Matthias Clasen  <mclasen@redhat.com>
 
        * gio/gio-sections.txt: More cleanup

diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml
index 1e55049..c3aa40e 100644 (file)
--- a/docs/reference/glib/tmpl/arrays.sgml
+++ b/docs/reference/glib/tmpl/arrays.sgml
@@ -298,12 +298,13 @@ the underlying array for use elsewhere.
 <note>
 <para>
 If array elements contain dynamically-allocated memory, they should be freed
-first.
+separately.
 </para>
 </note>
 
 @array: a #GArray.
 @free_segment: if %TRUE the actual element data is freed as well.
-@Returns: the element data if @free_segment is %FALSE, otherwise %NULL
+@Returns: the element data if @free_segment is %FALSE, otherwise %NULL.
+       The element data should be freed using g_free().
 
 

diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml
index 8612b8b..25ae824 100644 (file)
--- a/docs/reference/glib/tmpl/arrays_pointer.sgml
+++ b/docs/reference/glib/tmpl/arrays_pointer.sgml
@@ -227,14 +227,22 @@ Returns the pointer at the given index of the pointer array.
 
 <!-- ##### FUNCTION g_ptr_array_free ##### -->
 <para>
-Frees all of the memory allocated for the pointer array.
+Frees the memory allocated for the #GPtrArray.
+If @free_segment is %TRUE it frees the memory block holding the elements
+as well. Pass %FALSE if you want to free the #GPtrArray wrapper but preserve
+the underlying array for use elsewhere.
 </para>
+<note>
+<para>
+If array contents point to dynamically-allocated memory, they should be freed
+separately.
+</para>
+</note>
 
 @array: a #GPtrArray.
-@free_seg: if %TRUE the array of pointers (@pdata) is freed.
-@Returns: %NULL if @free_seg is %TRUE, otherwise the array of 
-pointers (@pdata) is returned.
-
+@free_seg: if %TRUE the actual pointer array is freed as well.
+@Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
+       The pointer array should be freed using g_free().
 
 <!-- ##### FUNCTION g_ptr_array_foreach ##### -->
 <para>