Merge pull request #290 from Thynix/documentation

Polish API documentation

1 files changed, 29 insertions, 56 deletions

diff --git a/doc/apiref.rst b/doc/apiref.rst
index e9551aa..ae0feed 100644
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -90,9 +90,6 @@ also cause errors.
 Type
 ----
 
-The type of a JSON value is queried and tested using the following
-functions:
-
 .. type:: enum json_type
 
    The type of a JSON value. The following members are defined:
@@ -171,8 +168,6 @@ no longer needed, the reference count is decremented. When the
 reference count drops to zero, there are no references left, and the
 value can be destroyed.
 
-The following functions are used to manipulate the reference count.
-
 .. function:: json_t *json_incref(json_t *json)
 
    Increment the reference count of *json* if it's not *NULL*.
@@ -448,9 +443,6 @@ information, see :ref:`rfc-conformance`.
    Sets the associated value of *real* to *value*. Returns 0 on
    success and -1 if *real* is not a JSON real.
 
-In addition to the functions above, there's a common query function
-for integers and reals:
-
 .. function:: double json_number_value(const json_t *json)
 
    Returns the associated value of the JSON integer or JSON real
@@ -538,9 +530,6 @@ A JSON array is an ordered collection of other JSON values.
    Appends all elements in *other_array* to the end of *array*.
    Returns 0 on success and -1 on error.
 
-The following macro can be used to iterate through all elements
-in an array.
-
 .. function:: json_array_foreach(array, index, value)
 
    Iterate over every element of ``array``, running the block
@@ -562,8 +551,7 @@ in an array.
    preprocessing, so its performance is equivalent to that of
    hand-written code using the array access functions.
    The main advantage of this macro is that it abstracts
-   away the complexity, and makes for shorter, more
-   concise code.
+   away the complexity, and makes for more concise and readable code.
 
    .. versionadded:: 2.5
 
@@ -656,9 +644,6 @@ allowed in object keys.
 
    .. versionadded:: 2.3
 
-The following macro can be used to iterate through all key-value pairs
-in an object.
-
 .. function:: json_object_foreach(object, key, value)
 
    Iterate over every key-value pair of ``object``, running the block
@@ -684,8 +669,8 @@ in an object.
    preprocessing, so its performance is equivalent to that of
    hand-written iteration code using the object iteration protocol
    (see below). The main advantage of this macro is that it abstracts
-   away the complexity behind iteration, and makes for shorter, more
-   concise code.
+   away the complexity behind iteration, and makes for more concise and
+   readable code.
 
    .. versionadded:: 2.3
 
@@ -699,10 +684,10 @@ in an object.
    .. versionadded:: 2.8
 
 
-The following functions implement an iteration protocol for objects,
-allowing to iterate through all key-value pairs in an object. The
-items are not returned in any particular order, as this would require
-sorting due to the internal hashtable implementation.
+The following functions can be used to iterate through all key-value
+pairs in an object. The items are not returned in any particular order,
+as this would require sorting due to the internal hashtable
+implementation.
 
 .. function:: void *json_object_iter(json_t *object)
 
@@ -749,25 +734,23 @@ sorting due to the internal hashtable implementation.
    Like :func:`json_object_iter_at()`, but much faster. Only works for
    values returned by :func:`json_object_iter_key()`. Using other keys
    will lead to segfaults. This function is used internally to
-   implement :func:`json_object_foreach`.
+   implement :func:`json_object_foreach`. Example::
+
+     /* 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);
+     }
 
    .. versionadded:: 2.3
 
-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);
-   }
-
 .. function:: void json_object_seed(size_t seed)
 
     Seed the hash function used in Jansson's hashtable implementation.
@@ -910,7 +893,7 @@ can be ORed together to obtain *flags*.
 ``JSON_ENCODE_ANY``
    Specifying this flag makes it possible to encode any JSON value on
    its own. Without it, only objects and arrays can be passed as the
-   *root* value to the encoding functions.
+   *json* value to the encoding functions.
 
    **Note:** Encoding any value may be useful in some scenarios, but
    it's generally discouraged as it violates strict compatibility with
@@ -934,18 +917,17 @@ can be ORed together to obtain *flags*.
 
    .. versionadded:: 2.7
 
-The following functions perform the actual JSON encoding. The result
-is in UTF-8.
+These functions output UTF-8:
 
-.. function:: char *json_dumps(const json_t *root, size_t flags)
+.. function:: char *json_dumps(const json_t *json, size_t flags)
 
-   Returns the JSON representation of *root* as a string, or *NULL* on
+   Returns the JSON representation of *json* as a string, or *NULL* on
    error. *flags* is described above. The return value must be freed
    by the caller using :func:`free()`.
 
-.. function:: int json_dumpf(const json_t *root, FILE *output, size_t flags)
+.. function:: int json_dumpf(const json_t *json, FILE *output, size_t flags)
 
-   Write the JSON representation of *root* to the stream *output*.
+   Write the JSON representation of *json* to the stream *output*.
    *flags* is described above. Returns 0 on success and -1 on error.
    If an error occurs, something may have already been written to
    *output*. In this case, the output is undefined and most likely not
@@ -953,7 +935,7 @@ is in UTF-8.
 
 .. function:: int json_dump_file(const json_t *json, const char *path, size_t flags)
 
-   Write the JSON representation of *root* to the file *path*. If
+   Write the JSON representation of *json* to the file *path*. If
    *path* already exists, it is overwritten. *flags* is described
    above. Returns 0 on success and -1 on error.
 
@@ -976,7 +958,7 @@ is in UTF-8.
 .. function:: int json_dump_callback(const json_t *json, json_dump_callback_t callback, void *data, size_t flags)
 
    Call *callback* repeatedly, passing a chunk of the JSON
-   representation of *root* each time. *flags* is described above.
+   representation of *json* each time. *flags* is described above.
    Returns 0 on success and -1 on error.
 
    .. versionadded:: 2.2
@@ -1076,8 +1058,6 @@ its ``position`` field. This is especially useful when using
 
 If no error or position information is needed, you can pass *NULL*.
 
-The following functions perform the actual JSON decoding.
-
 .. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
 
    .. refcounting:: new
@@ -1266,8 +1246,6 @@ arguments.
 
 Whitespace, ``:`` and ``,`` are ignored.
 
-The following functions compose the value building API:
-
 .. function:: json_t *json_pack(const char *fmt, ...)
 
    .. refcounting:: new
@@ -1407,8 +1385,6 @@ type whose address should be passed.
 
 Whitespace, ``:`` and ``,`` are ignored.
 
-The following functions compose the parsing and validation API:
-
 .. function:: int json_unpack(json_t *root, const char *fmt, ...)
 
    Validate and unpack the JSON value *root* according to the format
@@ -1510,9 +1486,6 @@ only if they are exactly the same value, but also if they have equal
   if their types are equal. (Because these values are singletons,
   their equality can actually be tested with ``==``.)
 
-The following function can be used to test whether two JSON values are
-equal.
-
 .. function:: int json_equal(json_t *value1, json_t *value2)
 
    Returns 1 if *value1* and *value2* are equal, as defined above.