From c607b5c2ac3851f91431a062e17d74bec349d1b2 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 6 Sep 2017 17:14:06 +0200 Subject: [PATCH] :memo: improved documentation --- doc/Doxyfile | 3 ++- src/json.hpp | 68 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 44 insertions(+), 27 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index e61f3024..8dfc0dcd 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -30,7 +30,8 @@ TAB_SIZE = 4 ALIASES = "complexity=@par Complexity\n" \ "liveexample{2}=@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The example code above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim" \ "requirement=@par Requirements\n" \ - "exceptionsafety=@par Exception safety\n" + "exceptionsafety=@par Exception safety\n" \ + "iterators=@par Iterator validity\n" TCL_SUBST = OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO diff --git a/src/json.hpp b/src/json.hpp index 9adf6245..e7c42920 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -226,10 +226,6 @@ as when using JSON Patch. Member @a byte holds the byte index of the last read character in the input file. -@note For an input with n bytes, 1 is the index of the first character and n+1 - is the index of the terminating null byte or the end of file. This also - holds true when reading a byte vector (CBOR or MessagePack). - Exceptions have ids 1xx. name / id | example message | description @@ -247,6 +243,10 @@ json.exception.parse_error.110 | parse error at 1: cannot read 2 bytes from vect json.exception.parse_error.112 | parse error at 1: error reading CBOR; last byte: 0xf8 | Not all types of CBOR or MessagePack are supported. This exception occurs if an unsupported byte was read. json.exception.parse_error.113 | parse error at 2: expected a CBOR string; last byte: 0x98 | While parsing a map key, a value that is not a string has been read. +@note For an input with n bytes, 1 is the index of the first character and n+1 + is the index of the terminating null byte or the end of file. This also + holds true when reading a byte vector (CBOR or MessagePack). + @liveexample{The following code shows how a `parse_error` exception can be caught.,parse_error} @@ -11279,9 +11279,9 @@ class basic_json /// @{ /*! - @brief checks whether the container is empty + @brief checks whether the container is empty. - Checks if a JSON value has no elements. + Checks if a JSON value has no elements (i.e. whether its @ref size is `0`). @return The return value depends on the different types and is defined as follows: @@ -11294,23 +11294,27 @@ class basic_json object | result of function `object_t::empty()` array | result of function `array_t::empty()` - @note This function does not return whether a string stored as JSON value - is empty - it returns whether the JSON container itself is empty which is - false in the case of a string. + @liveexample{The following code uses `empty()` to check if a JSON + object contains any elements.,empty} @complexity Constant, as long as @ref array_t and @ref object_t satisfy the Container concept; that is, their `empty()` functions have constant complexity. + @iterators No changes. + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + + @note This function does not return whether a string stored as JSON value + is empty - it returns whether the JSON container itself is empty which is + false in the case of a string. + @requirement This function helps `basic_json` satisfying the [Container](http://en.cppreference.com/w/cpp/concept/Container) requirements: - The complexity is constant. - Has the semantics of `begin() == end()`. - @liveexample{The following code uses `empty()` to check if a JSON - object contains any elements.,empty} - @sa @ref size() -- returns the number of elements @since version 1.0.0 @@ -11361,23 +11365,27 @@ class basic_json object | result of function object_t::size() array | result of function array_t::size() - @note This function does not return the length of a string stored as JSON - value - it returns the number of elements in the JSON value which is 1 in - the case of a string. + @liveexample{The following code calls `size()` on the different value + types.,size} @complexity Constant, as long as @ref array_t and @ref object_t satisfy the Container concept; that is, their size() functions have constant complexity. + @iterators No changes. + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + + @note This function does not return the length of a string stored as JSON + value - it returns the number of elements in the JSON value which is 1 in + the case of a string. + @requirement This function helps `basic_json` satisfying the [Container](http://en.cppreference.com/w/cpp/concept/Container) requirements: - The complexity is constant. - Has the semantics of `std::distance(begin(), end())`. - @liveexample{The following code calls `size()` on the different value - types.,size} - @sa @ref empty() -- checks whether the container is empty @sa @ref max_size() -- returns the maximal number of elements @@ -11431,10 +11439,17 @@ class basic_json object | result of function `object_t::max_size()` array | result of function `array_t::max_size()` + @liveexample{The following code calls `max_size()` on the different value + types. Note the output is implementation specific.,max_size} + @complexity Constant, as long as @ref array_t and @ref object_t satisfy the Container concept; that is, their `max_size()` functions have constant complexity. + @iterators No changes. + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + @requirement This function helps `basic_json` satisfying the [Container](http://en.cppreference.com/w/cpp/concept/Container) requirements: @@ -11442,9 +11457,6 @@ class basic_json - Has the semantics of returning `b.size()` where `b` is the largest possible JSON value. - @liveexample{The following code calls `max_size()` on the different value - types. Note the output is implementation specific.,max_size} - @sa @ref size() -- returns the number of elements @since version 1.0.0 @@ -11504,14 +11516,18 @@ class basic_json *this = basic_json(type()); @endcode - @complexity Linear in the size of the JSON value. - - @exceptionsafety No-throw guarantee: this function never throws exceptions. - @liveexample{The example below shows the effect of `clear()` to different JSON types.,clear} - @sa @ref basic_json(value_t) -- constructor that creates + @complexity Linear in the size of the JSON value. + + @iterators All iterators, pointers and references related to this container + are invalidated. + + @exceptionsafety No-throw guarantee: this function never throws exceptions. + + @sa @ref basic_json(value_t) -- constructor that creates an object with the + same value than calling `clear()` @since version 1.0.0 */