X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fapiref.rst;h=bacd7569993233698a9986044439aad31ffc528f;hb=dec3ad498ee52c3b2860b14b4bbe626cd0f8f495;hp=ebe00eabde95aff49d193e979ab77a628a29ae1a;hpb=782acfe378b8d6dddb307029ba97688943312340;p=jansson.git

diff --git a/doc/apiref.rst b/doc/apiref.rst
index ebe00ea..bacd756 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -154,9 +154,31 @@ Normally, all functions accepting a JSON value as an argument will
 manage the reference, i.e. increase and decrease the reference count
 as needed. However, some functions **steal** the reference, i.e. they
 have the same result as if the user called :cfunc:`json_decref()` on
-the argument right after calling the function. These are usually
-convenience functions for adding new references to containers and not
-to worry about the reference count.
+the argument right after calling the function. These functions are
+suffixed with ``_new`` or have ``_new_`` somewhere in their name.
+
+For example, the following code creates a new JSON array and appends
+an integer to it::
+
+  json_t *array, *integer;
+
+  array = json_array();
+  integer = json_integer(42);
+
+  json_array_append(array, integer);
+  json_decref(integer);
+
+Note how the caller has to release the reference to the integer value
+by calling :cfunc:`json_decref()`. By using a reference stealing
+function :cfunc:`json_array_append_new()` instead of
+:cfunc:`json_array_append()`, the code becomes much simpler::
+
+  json_t *array = json_array();
+  json_array_append_new(array, json_integer(42));
+
+In this case, the user doesn't have to explicitly release the
+reference to the integer value, as :cfunc:`json_array_append_new()`
+steals the reference when appending the value to the array.
 
 In the following sections it is clearly documented whether a function
 will return a new or borrowed reference or steal a reference to its