Documentation fixes

[jansson.git] / doc / apiref.rst

diff --git a/doc/apiref.rst b/doc/apiref.rst
index df20a3a..7d69004 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -703,9 +703,9 @@ can be ORed together to obtain *flags*.
 ``JSON_INDENT(n)``
    Pretty-print the result, using newlines between array and object
    items, and indenting with *n* spaces. The valid range for *n* is
-   between 0 and 32, other values result in an undefined output. If
-   ``JSON_INDENT`` is not used or *n* is 0, no newlines are inserted
-   between array and object items.
+   between 0 and 31 (inclusive), other values result in an undefined
+   output. If ``JSON_INDENT`` is not used or *n* is 0, no newlines are
+   inserted between array and object items.
 
 ``JSON_COMPACT``
    This flag enables a compact representation, i.e. sets the separator
@@ -779,12 +779,16 @@ is in UTF-8.
    On error, the function should return -1 to stop the encoding
    process. On success, it should return 0.
 
+   .. versionadded:: 2.2
+
 .. 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.
    Returns 0 on success and -1 on error.
 
+   .. versionadded:: 2.2
+
 
 .. _apiref-decoding:
 
@@ -855,6 +859,16 @@ The following functions perform the actual JSON decoding.
    filled with information about the error. *flags* is described
    above.
 
+   This function will start reading the input from whatever position
+   the input file was, without attempting to seek first. If an error
+   occurs, the file position will be left indeterminate. On success,
+   the file position will be at EOF, unless ``JSON_DISABLE_EOF_CHECK``
+   flag was used. In this case, the file position will be at the first
+   character after the last ``]`` or ``}`` in the JSON input. This
+   allows calling :func:`json_loadf()` on the same ``FILE`` object
+   multiple times, if the input consists of consecutive JSON texts,
+   possibly separated by whitespace.
+
 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
 
    .. refcounting:: new
@@ -993,7 +1007,9 @@ type whose address should be passed.
 
 ``s`` (string) [const char \*]
     Convert a JSON string to a pointer to a NULL terminated UTF-8
-    string.
+    string. The resulting string is extracted by using
+    :func:`json_string_value()` internally, so it exists as long as
+    there are still references to the corresponding JSON string.
 
 ``n`` (null)
     Expect a JSON null value. Nothing is extracted.
@@ -1067,6 +1083,20 @@ The following functions compose the parsing and validation API:
    behaviour of the unpacker, see below for the flags. Returns 0 on
    success and -1 on failure.
 
+.. note::
+
+   The first argument of all unpack functions is ``json_t *root``
+   instead of ``const json_t *root``, because the use of ``O`` format
+   character causes the reference count of ``root``, or some value
+   reachable from ``root``, to be increased. Furthermore, the ``o``
+   format character may be used to extract a value as-is, which allows
+   modifying the structure or contents of a value reachable from
+   ``root``.
+
+   If the ``O`` and ``o`` format character are not used, it's
+   perfectly safe to cast a ``const json_t *`` variable to plain
+   ``json_t *`` when used with these functions.
+
 The following unpacking flags are available:
 
 ``JSON_STRICT``
@@ -1171,6 +1201,8 @@ copied in a recursive fashion.
    Returns a deep copy of *value*, or *NULL* on error.
 
 
+.. _apiref-custom-memory-allocation:
+
 Custom Memory Allocation
 ========================
 
@@ -1239,5 +1271,5 @@ JSON structures by zeroing all memory when freed::
 For more information about the issues of storing sensitive data in
 memory, see
 http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/protect-secrets.html.
-The page also examplains the :func:`guaranteed_memset()` function used
+The page also explains the :func:`guaranteed_memset()` function used
 in the example and gives a sample implementation for it.