Move json_error_t documentation to its own section

json_error_t is used in the decoder and in the pack and unpack API's,
so it's better to have a separate section for it.

diff --git a/doc/apiref.rst b/doc/apiref.rst
index 17af036..79693fb 100644 (file)
--- a/doc/apiref.rst
+++ b/doc/apiref.rst
@@ -620,6 +620,62 @@ The iteration protocol can be used for example as follows::
    }
 
 
    }
 
 

+Error reporting
+===============
+
+Jansson uses a single struct type to pass error information to the
+user. See sections :ref:`apiref-decoding`, :ref:`apiref-pack` and
+:ref:`apiref-unpack` for functions that pass error information using
+this struct.
+
+.. type:: json_error_t
+
+   .. member:: char text[]
+
+      The error message (in UTF-8), or an empty string if a message is
+      not available.
+
+   .. member:: char source[]
+
+      Source of the error. This can be (a part of) the file name or a
+      special identifier in angle brackers (e.g. ``<string>``).
+
+   .. member:: int line
+
+      The line number on which the error occurred.
+
+   .. member:: int column
+
+      The column on which the error occurred. Note that this is the
+      *character column*, not the byte column, i.e. a multibyte UTF-8
+      character counts as one column.
+
+   .. member:: size_t position
+
+      The position in bytes from the start of the input. This is
+      useful for debugging Unicode encoding problems.
+
+The normal use of :type:`json_error_t` is to allocate it on the stack,
+and pass a pointer to a function. Example::
+
+   int main() {
+       json_t *json;
+       json_error_t error;
+
+       json = json_load_file("/path/to/file.json", 0, &error);
+       if(!json) {
+           /* the error variable contains error information */
+       }
+       ...
+   }
+
+Also note that if the call succeeded (``json != NULL`` in the above
+example), the contents of ``error`` are unspecified.
+
+All functions also accept *NULL* as the :type:`json_error_t` pointer,
+in which case no error information is returned to the caller.
+
+

 Encoding
 ========
 
 Encoding
 ========
 


@@ -690,6 +746,8 @@ is in UTF-8.
    above. Returns 0 on success and -1 on error.
 
 
    above. Returns 0 on success and -1 on error.
 
 

+.. _apiref-decoding:
+

 Decoding
 ========
 
 Decoding
 ========
 


@@ -710,9 +768,8 @@ affect especially the behavior of the decoder.
 
    Decodes the JSON string *input* and returns the array or object it
    contains, or *NULL* on error, in which case *error* is filled with
 
    Decodes the JSON string *input* and returns the array or object it
    contains, or *NULL* on error, in which case *error* is filled with

-   information about the error. See above for discussion on the
-   *error* parameter. *flags* is currently unused, and should be set
-   to 0.
+   information about the error. *flags* is currently unused, and
+   should be set to 0.

 
 .. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
 
 
 .. function:: json_t *json_loadf(FILE *input, size_t flags, json_error_t *error)
 


@@ -720,9 +777,8 @@ affect especially the behavior of the decoder.
 
    Decodes the JSON text in stream *input* and returns the array or
    object it contains, or *NULL* on error, in which case *error* is
 
    Decodes the JSON text in stream *input* and returns the array or
    object it contains, or *NULL* on error, in which case *error* is

-   filled with information about the error. See above for discussion
-   on the *error* parameter. *flags* is currently unused, and should
-   be set to 0.
+   filled with information about the error. *flags* is currently
+   unused, and should be set to 0.

 
 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
 
 
 .. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
 


@@ -730,64 +786,11 @@ affect especially the behavior of the decoder.
 
    Decodes the JSON text in file *path* and returns the array or
    object it contains, or *NULL* on error, in which case *error* is
 
    Decodes the JSON text in file *path* and returns the array or
    object it contains, or *NULL* on error, in which case *error* is

-   filled with information about the error. See above for discussion
-   on the *error* parameter. *flags* is currently unused, and should
-   be set to 0.
-
-.. type:: json_error_t
-
-   This data structure is used to return information on decoding
-   errors from the decoding functions.
-
-   .. member:: char text[]
-
-      The error message (in UTF-8), or an empty string if a message is
-      not available.
-
-   .. member:: char source[]
+   filled with information about the error. *flags* is currently
+   unused, and should be set to 0.

 
 

-      Source of the error. This is (a part of) the file name when
-      using :func:`json_load_file()`, or a special identifier in angle
-      brackets otherwise (e.g. ``<string>``).

 
 

-   .. member:: int line
-
-      The line number on which the error occurred.
-
-   .. member:: int column
-
-      The character column on which the error occurred. Note that this
-      is the *character column*, not the byte column, i.e. a non-ASCII
-      UTF-8 character counts as one column.
-
-   .. member:: size_t position
-
-      The position in bytes from the start of the input. This is
-      useful for debugging Unicode encoding problems.
-
-   The normal use of :type:`json_error_t` is to allocate it on the
-   stack, and pass a pointer to a decoding function. Example::
-
-      int main() {
-          json_t *json;
-          json_error_t error;
-
-          json = json_load_file("/path/to/file.json", 0, &error);
-          if(!json) {
-              /* the error variable contains error information */
-          }
-          ...
-      }
-
-   Also note that if the decoding succeeded (``json != NULL`` in the
-   above example), the contents of ``error`` are unspecified.
-
-   All decoding functions also accept *NULL* as the
-   :type:`json_error_t` pointer, in which case no error information
-   is returned to the caller.
-
-
-.. _apiref-building-values:
+.. _apiref-pack:

 
 Building values
 ===============
 
 Building values
 ===============


@@ -893,12 +896,14 @@ More examples::
   json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
 
 
   json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
 
 

+.. _apiref-unpack:
+

 Parsing and validating values
 =============================
 
 This sectinon describes functions that help to validate complex values
 and extract, or *unpack*, data from them. Like :ref:`building values
 Parsing and validating values
 =============================
 
 This sectinon describes functions that help to validate complex values
 and extract, or *unpack*, data from them. Like :ref:`building values

-<apiref-building-values>`, this is also based on format strings.
+<apiref-pack>`, this is also based on format strings.

 
 While a JSON value is unpacked, the type specified in the format
 string is checked to match that of the JSON value. This is the
 
 While a JSON value is unpacked, the type specified in the format
 string is checked to match that of the JSON value. This is the