Add support for the cleanup attribute in GCC/Clang

The new json_auto_t macro allows easy declaration of json_t types that
automatically decrement at the end of their scope.

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 0ab2348..2a090e4 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -253,6 +253,24 @@ other. Moreover, trying to encode the values with any of the encoding
 functions will fail. The encoder detects circular references and
 returns an error status.
 
+Scope Dereferencing
+-------------------
+
+It is possible to use the ``json_auto_t`` type to automatically
+dereference a value at the end of a scope. For example::
+
+  void function(void) {
+    json_auto_t *value = NULL;
+    value = json_string("foo");
+    /* json_decref(value) is automatically called. */
+  }
+
+This feature is only available on GCC and Clang. So if your project
+has a portability requirement for other compilers, you should avoid
+this feature.
+
+Additionally, as always, care should be taken when passing values to
+functions that steal references.
 
 True, False and Null
 ====================