[glib: 1/2] glist: Add docs examples of how to combine with g_steal_pointer()

[Sebastian Dröge <sdroege src gnome org>]

commit 6bd29c2db93654f29c95ad3089456fb8bca25bb2
Author: Philip Withnall <withnall endlessm com>
Date:   Fri Feb 7 14:09:41 2020 +0000

    glist: Add docs examples of how to combine with g_steal_pointer()
    
    As suggested by Simon McVittie and triggered by Marco Trevisan.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    See: https://gitlab.gnome.org/GNOME/glib/merge_requests/818

 glib/glist.c  | 16 ++++++++++++++++
 glib/gslist.c | 16 ++++++++++++++++
 2 files changed, 32 insertions(+)
---
diff --git a/glib/glist.c b/glib/glist.c
index 7b64ba1d6..474331ab5 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -175,6 +175,13 @@ g_list_alloc (void)
  *
  * If list elements contain dynamically-allocated memory, you should
  * either use g_list_free_full() or free them manually first.
+ *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling:
+ * |[<!-- language="C" -->
+ * GList *list_of_borrowed_things = …;  /<!-- -->* (transfer container) *<!-- -->/
+ * g_list_free (g_steal_pointer (&list_of_borrowed_things));
+ * ]|
  */
 void
 g_list_free (GList *list)
@@ -214,6 +221,15 @@ g_list_free_1 (GList *list)
  * @free_func must not modify the list (eg, by removing the freed
  * element from it).
  *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling ­— this also has the nice property that the head pointer
+ * is cleared before any of the list elements are freed, to prevent double frees
+ * from @free_func:
+ * |[<!-- language="C" -->
+ * GList *list_of_owned_things = …;  /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
+ * g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
+ * ]|
+ *
  * Since: 2.28
  */
 void
diff --git a/glib/gslist.c b/glib/gslist.c
index ef711f634..15b7936c6 100644
--- a/glib/gslist.c
+++ b/glib/gslist.c
@@ -130,6 +130,13 @@ g_slist_alloc (void)
  * If list elements contain dynamically-allocated memory,
  * you should either use g_slist_free_full() or free them manually
  * first.
+ *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling:
+ * |[<!-- language="C" -->
+ * GSList *list_of_borrowed_things = …;  /<!-- -->* (transfer container) *<!-- -->/
+ * g_slist_free (g_steal_pointer (&list_of_borrowed_things));
+ * ]|
  */
 void
 g_slist_free (GSList *list)
@@ -168,6 +175,15 @@ g_slist_free_1 (GSList *list)
  * @free_func must not modify the list (eg, by removing the freed
  * element from it).
  *
+ * It can be combined with g_steal_pointer() to ensure the list head pointer
+ * is not left dangling ­— this also has the nice property that the head pointer
+ * is cleared before any of the list elements are freed, to prevent double frees
+ * from @free_func:
+ * |[<!-- language="C" -->
+ * GSList *list_of_owned_things = …;  /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
+ * g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
+ * ]|
+ *
  * Since: 2.28
  **/
 void