[glib/refcount-box] Improve the RcBox and ArcBox documentation

[Emmanuele Bassi <ebassi src gnome org>]

commit d01774c6fcdede98117dffdf21289a181f3435f6
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Jun 12 09:23:32 2018 +0100

    Improve the RcBox and ArcBox documentation
    
    Use better examples, split up into sections, and mention use with
    g_autoptr().

 glib/garcbox.c | 74 ++++++++++++++++++++++++++++++++++------------------
 glib/grcbox.c  | 82 +++++++++++++++++++++++++++++++++++++++-------------------
 2 files changed, 105 insertions(+), 51 deletions(-)
---
diff --git a/glib/garcbox.c b/glib/garcbox.c
index aaa2c8b56..01e0f1c56 100644
--- a/glib/garcbox.c
+++ b/glib/garcbox.c
@@ -44,25 +44,25 @@
  *
  * ArcBox is useful if you have a plain old data type, like a structure
  * typically placed on the stack, and you wish to provide additional API
- * to use it on the heap, without necessarily implementing copy/free
- * semantics, or your own reference counting.
+ * to use it on the heap; or if you want to implement a new type to be
+ * passed around by reference without necessarily implementing copy/free
+ * semantics or your own reference counting.
  *
  * The typical use is:
  *
  * |[<!-- language="C" -->
  * typedef struct {
- *   float x, y;
- * } Point;
+ *   char *name;
+ *   char *address;
+ *   char *city;
+ *   char *state;
+ *   int age;
+ * } Person;
  *
- * Point *
- * point_new (float x, float y)
+ * Person *
+ * person_new (void)
  * {
- *   Point *res = g_arc_box_new (Point);
- *
- *   res->x = x;
- *   res->y = y;
- *
- *   return res;
+ *   return g_arc_box_new0 (Person);
  * }
  * ]|
  *
@@ -71,15 +71,20 @@
  * you should call g_arc_box_release():
  *
  * |[<!-- language="C" -->
- * Point *
- * point_ref (Point *p)
+ * // Add a Person to the Database; the Database acquires ownership
+ * // of the Person instance
+ * void
+ * add_person_to_database (Database *db, Person *p)
  * {
- *   return g_arc_box_acquire (p);
+ *   db->persons = g_list_prepend (db->persons, g_arc_box_acquire (p));
  * }
  *
+ * // Removes a Person from the Database; the reference acquired by
+ * // add_person_to_database() is released here
  * void
- * point_unref (Point *p)
+ * remove_person_from_database (Database *db, Person *p)
  * {
+ *   db->persons = g_list_remove (db->persons, p);
  *   g_arc_box_release (p);
  * }
  * ]|
@@ -89,14 +94,6 @@
  * will be called if the reference released was the last:
  *
  * |[<!-- language="C" -->
- * typedef struct {
- *   char *name;
- *   char *address;
- *   char *city;
- *   char *state;
- *   int age;
- * } Person;
- *
  * void
  * person_clear (Person *p)
  * {
@@ -107,8 +104,9 @@
  * }
  *
  * void
- * person_unref (Person *p)
+ * remove_person_from_database (Database *db, Person *p)
  * {
+ *   db->persons = g_list_remove (db->persons, p);
  *   g_arc_box_release_full (p, (GDestroyNotify) person_clear);
  * }
  * ]|
@@ -124,12 +122,38 @@
  *   add_person_to_database (db, g_steal_pointer (&p));
  * ]|
  *
+ * ## Thread safety
+ *
  * The reference counting operations on data allocated using g_arc_box_alloc(),
  * g_arc_box_new(), and g_arc_box_dup() are guaranteed to be atomic, and thus
  * can be safely be performed by different threads. It is important to note that
  * only the reference acquisition and release are atomic; changes to the content
  * of the data are your responsibility.
  *
+ * ## Automatic pointer clean up
+ *
+ * If you want to add g_autoptr() support to your plain old data type through
+ * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
+ * g_arc_box_release():
+ *
+ * |[<!-- language="C" -->
+ * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_arc_box_release)
+ * ]|
+ *
+ * If you need to clear the contents of the data, you will need to use an
+ * ancillary function that calls g_rc_box_release_full():
+ *
+ * |[<!-- laguage="C" -->
+ * static void
+ * my_data_struct_release (MyDataStruct *data)
+ * {
+ *   // my_data_struct_clear() is defined elsewhere
+ *   g_arc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
+ * }
+ *
+ * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_clear)
+ * ]|
+ *
  * Since: 2.58.
  */
 
diff --git a/glib/grcbox.c b/glib/grcbox.c
index d65f4c919..d09c3b7fa 100644
--- a/glib/grcbox.c
+++ b/glib/grcbox.c
@@ -42,25 +42,25 @@
  *
  * RcBox is useful if you have a plain old data type, like a structure
  * typically placed on the stack, and you wish to provide additional API
- * to use it on the heap, without necessarily implementing copy/free
- * semantics, or your own reference counting.
+ * to use it on the heap; or if you want to implement a new type to be
+ * passed around by reference without necessarily implementing copy/free
+ * semantics or your own reference counting.
  *
  * The typical use is:
  *
  * |[<!-- language="C" -->
  * typedef struct {
- *   float x, y;
- * } Point;
+ *   char *name;
+ *   char *address;
+ *   char *city;
+ *   char *state;
+ *   int age;
+ * } Person;
  *
- * Point *
- * point_new (float x, float y)
+ * Person *
+ * person_new (void)
  * {
- *   Point *res = g_rc_box_new (Point);
- *
- *   res->x = x;
- *   res->y = y;
- *
- *   return res;
+ *   return g_rc_box_new0 (Person);
  * }
  * ]|
  *
@@ -69,15 +69,20 @@
  * you should call g_rc_box_release():
  *
  * |[<!-- language="C" -->
- * Point *
- * point_ref (Point *p)
+ * // Add a Person to the Database; the Database acquires ownership
+ * // of the Person instance
+ * void
+ * add_person_to_database (Database *db, Person *p)
  * {
- *   return g_rc_box_acquire (p);
+ *   db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p));
  * }
  *
+ * // Removes a Person from the Database; the reference acquired by
+ * // add_person_to_database() is released here
  * void
- * point_unref (Point *p)
+ * remove_person_from_database (Database *db, Person *p)
  * {
+ *   db->persons = g_list_remove (db->persons, p);
  *   g_rc_box_release (p);
  * }
  * ]|
@@ -87,14 +92,6 @@
  * will be called if the reference released was the last:
  *
  * |[<!-- language="C" -->
- * typedef struct {
- *   char *name;
- *   char *address;
- *   char *city;
- *   char *state;
- *   int age;
- * } Person;
- *
  * void
  * person_clear (Person *p)
  * {
@@ -105,8 +102,9 @@
  * }
  *
  * void
- * person_unref (Person *p)
+ * remove_person_from_database (Database *db, Person *p)
  * {
+ *   db->persons = g_list_remove (db->persons, p);
  *   g_rc_box_release_full (p, (GDestroyNotify) person_clear);
  * }
  * ]|
@@ -117,16 +115,48 @@
  * |[<!-- language="C" -->
  *   Person *p = g_rc_box_new (Person);
  *
+ *   // fill_person_details() is defined elsewhere
  *   fill_person_details (p);
  *
- *   add_person_to_database (db, g_steal_pointer (&p));
+ *   // add_person_to_database_no_ref() is defined elsewhere; it adds
+ *   // a Person to the Database without taking a reference
+ *   add_person_to_database_no_ref (db, g_steal_pointer (&p));
  * ]|
  *
+ * ## Thread safety
+ *
  * The reference counting operations on data allocated using g_rc_box_alloc(),
  * g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's
  * responsibility to ensure that references are acquired are released on the
  * same thread.
  *
+ * If you need thread safe reference counting, see the [atomic reference counted
+ * data][arcbox] API.
+ *
+ * ## Automatic pointer clean up
+ *
+ * If you want to add g_autoptr() support to your plain old data type through
+ * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and
+ * g_rc_box_release():
+ *
+ * |[<!-- language="C" -->
+ * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release)
+ * ]|
+ *
+ * If you need to clear the contents of the data, you will need to use an
+ * ancillary function that calls g_rc_box_release_full():
+ *
+ * |[<!-- laguage="C" -->
+ * static void
+ * my_data_struct_release (MyDataStruct *data)
+ * {
+ *   // my_data_struct_clear() is defined elsewhere
+ *   g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
+ * }
+ *
+ * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_clear)
+ * ]|
+ *
  * Since: 2.58.
  */