doc apiref: Enhancements

Constructors are described more clearly and return values on error
situations more compehensively. Also add an example of the object
iteration protocol.

doc/apiref.rst

@@ -99,17 +99,18 @@ functions:
                json_is_null(const json_t *json)
 
    These functions (actually macros) return true (non-zero) for values
-   of the given type, and false (zero) for values of other types.
+   of the given type, and false (zero) for values of other types and
+   for *NULL*.
 
 .. cfunction:: json_is_number(const json_t *json)
 
    Returns true for values of types :const:`JSON_INTEGER` and
-   :const:`JSON_REAL`, and false for other types.
+   :const:`JSON_REAL`, and false for other types and for *NULL*.
 
 .. cfunction:: json_is_boolean(const json_t *json)
 
    Returns true for types :const:`JSON_TRUE` and :const:`JSON_FALSE`,
-   and false for values of other types.
+   and false for values of other types and for *NULL*.
 
 
 Reference Count
@@ -127,7 +128,8 @@ The following functions are used to manipulate the reference count.
 
 .. cfunction:: json_t *json_incref(json_t *json)
 
-   Increment the reference count of *json*. Returns *json*.
+   Increment the reference count of *json* if it's not non-*NULL*.
+   Returns *json*.
 
 .. cfunction:: void json_decref(json_t *json)
 
@@ -145,7 +147,7 @@ the value is no longer needed, :cfunc:`json_decref` should be called
 to release the reference.
 
 Normally, all functions accepting a JSON value as an argument will
-manage the reference, i.e. increase and decrease the reference count
+nmanage 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
@@ -160,26 +162,26 @@ argument.
 True, False and Null
 ====================
 
+These values are implemented as singletons, so each of these functions
+returns the same value each time.
+
 .. cfunction:: json_t *json_true(void)
 
    .. refcounting:: new
 
-   Returns a value of the type :const:`JSON_TRUE`, or *NULL* on
+   Returns the JSON true value.
-   error.
 
 .. cfunction:: json_t *json_false(void)
 
    .. refcounting:: new
 
-   Returns a value of the type :const:`JSON_FALSE`, or *NULL* on
+   Returns the JSON false value.
-   error.
 
 .. cfunction:: json_t *json_null(void)
 
    .. refcounting:: new
 
-   Returns a value of the type :const:`JSON_NULL`, or *NULL* on
+   Returns the JSON null value.
-   error.
 
 
 String
@@ -189,13 +191,14 @@ String
 
    .. refcounting:: new
 
-   Returns a new value of the type :const:`JSON_STRING`, or *NULL* on
+   Returns a new JSON string, or *NULL* on error. *value* must be a
-   error. *value* must be a valid UTF-8 encoded Unicode string.
+   valid UTF-8 encoded Unicode string.
 
 .. cfunction:: const char *json_string_value(const json_t *json)
 
-   Returns the associated value of a :const:`JSON_STRING` value as a
+   Returns the associated value of the JSON string *json* as a null
-   null terminated UTF-8 encoded string.
+   terminated UTF-8 encoded string, or *NULL* if *json* is not a JSON
+   string.
 
 
 Number
@@ -205,33 +208,32 @@ Number
 
    .. refcounting:: new
 
-   Returns a new value of the type :const:`JSON_INTEGER`, or *NULL* on
+   Returns a new JSON integer, or *NULL* on error.
-   error.
 
 .. cfunction:: int json_integer_value(const json_t *json)
 
-   Returns the associated integer value of values of the type
+   Returns the associated value the JSON integer *json*. If *json* is
-   :const:`JSON_INTEGER`, or 0 for values of other types.
+   *NULL* or not a JSON integer, 0 is returned.
 
 .. cfunction:: json_t *json_real(double value)
 
    .. refcounting:: new
 
-   Returns a new value of the type :const:`JSON_REAL`, or *NULL* on
+   Returns a new JSON real, or *NULL* on error.
-   error.
 
 .. cfunction:: double json_real_value(const json_t *json)
 
-   Returns the associated real value of values of the type
+   Returns the associated value of the JSON real *json*. If *json* is
-   :const:`JSON_INTEGER`, or 0 for values of other types.
+   *NULL* or not a JSON real, 0.0 is returned.
 
 In addition to the functions above, there's a common query function
 for integers and reals:
 
 .. cfunction:: double json_number_value(const json_t *json)
 
-   Returns the value of either ``JSON_INTEGER`` or ``JSON_REAL``, cast
+   Returns the associated value of the JSON integer or JSON real
-   to double regardless of the actual type.
+   *json*, cast to double regardless of the actual type. If *json* is
+   neither JSON real nor JSON integer, 0.0 is returned.
 
 
 Array
@@ -243,27 +245,30 @@ A JSON array is an ordered collection of other JSON values.
 
    .. refcounting:: new
 
-   Returns a new value of the type :const:`JSON_ARRAY`, or *NULL* on
+   Returns a new JSON array, or *NULL* on error. Initially, the array
-   error. Initially, the array is empty.
+   is empty.
 
 .. cfunction:: unsigned int json_array_size(const json_t *array)
 
-   Returns the number of elements in *array*.
+   Returns the number of elements in *array*, or 0 if *array* is NULL
+   or not a JSON array.
 
 .. cfunction:: json_t *json_array_get(const json_t *array, unsigned int index)
 
    .. refcounting:: borrow
 
-   Returns the element in *array* at position *index*, or *NULL* if
+   Returns the element in *array* at position *index*. The valid range
-   *index* is out of range. The valid range for *index* is from 0 to
+   for *index* is from 0 to the return value of
-   the return value of :cfunc:`json_array_size()` minus 1.
+   :cfunc:`json_array_size()` minus 1. If *array* is not a JSON array,
+   if *array* is *NULL*, or if *index* is out of range, *NULL* is
+   returned.
 
 .. cfunction:: int json_array_set(json_t *array, unsigned int index, json_t *value)
 
    Replaces the element in *array* at position *index* with *value*.
-   Returns 0 on success, or -1 if *index* is out of range. The valid
+   The valid range for *index* is from 0 to the return value of
-   range for *index* is from 0 to the return value of
+   :cfunc:`json_array_size()` minus 1. Returns 0 on success and -1 on
-   :cfunc:`json_array_size()` minus 1.
+   error.
 
 .. cfunction:: int json_array_set_new(json_t *array, unsigned int index, json_t *value)
 
@@ -297,8 +302,8 @@ Unicode string and the value is any JSON value.
 
    .. refcounting:: new
 
-   Returns a new value of the type :const:`JSON_OBJECT`, or *NULL* on
+   Returns a new JSON object, or *NULL* on error. Initially, the
-   error. Initially, the object is empty.
+   object is empty.
 
 .. cfunction:: json_t *json_object_get(const json_t *object, const char *key)
 
@@ -351,6 +356,20 @@ The following functions implement an iteration protocol for objects:
 
    Extract the associated value from *iter*.
 
+The iteration protocol can be used for example as follows::
+
+   /* obj is a JSON object */
+   const char *key;
+   json_t *value;
+   void *iter = json_object_iter(obj);
+   while(iter)
+   {
+       key = json_object_iter_key(iter);
+       value = json_object_iter_value(iter);
+       /* use key and value ... */
+       iter = json_object_iter_next(obj, iter);
+   }
+
 
 Encoding
 ========