📝 add more API documentation

doc/mkdocs/docs/api/basic_json/number_integer_t.md

@@ -7,41 +7,31 @@ using number_integer_t = NumberIntegerType;
 The type used to store JSON numbers (integers).
 
 [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-> The representation of numbers is similar to that used in most
+> The representation of numbers is similar to that used in most programming languages. A number is represented in base
-> programming languages. A number is represented in base 10 using decimal
+> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
-> digits. It contains an integer component that may be prefixed with an
+> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
-> optional minus sign, which may be followed by a fraction part and/or an
+> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
-> exponent part. Leading zeros are not allowed. (...) Numeric values that
-> cannot be represented in the grammar below (such as Infinity and NaN)
-> are not permitted.
 
-This description includes both integer and floating-point numbers.
+This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
-However, C++ allows more precise storage if it is known whether the number
+known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
-is a signed integer, an unsigned integer or a floating-point number.
+types, `number_integer_t`,  [`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are
-Therefore, three different types, `number_integer_t`, 
+used.
-[`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are used.
 
-To store integer numbers in C++, a type is defined by the template
+To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type
-parameter `NumberIntegerType` which chooses the type to use.
+to use.
 
 ## Notes
 
 #### Default type
 
-With the default values for `NumberIntegerType` (`std::int64_t`), the default
+With the default values for `NumberIntegerType` (`std::int64_t`), the default value for `number_integer_t` is
-value for `number_integer_t` is:
+`#!cpp std::int64_t`.
-
-```cpp
-std::int64_t
-```
 
 #### Default behavior
 
-- The restrictions about leading zeros is not enforced in C++. Instead,
+- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an
-  leading zeros in integer literals lead to an interpretation as octal
+  interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer
-  number. Internally, the value will be stored as decimal number. For
+  literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
-  instance, the C++ integer literal `010` will be serialized to `8`.
-  During deserialization, leading zeros yield an error.
 - Not-a-number (NaN) values will be serialized to `null`.
 
 #### Limits
@@ -49,21 +39,17 @@ std::int64_t
 [RFC 7159](http://rfc7159.net/rfc7159) specifies:
 > An implementation may set limits on the range and precision of numbers.
 
-When the default type is used, the maximal integer number that can be
+When the default type is used, the maximal integer number that can be stored is `9223372036854775807` (INT64_MAX) and
-stored is `9223372036854775807` (INT64_MAX) and the minimal integer number
+the minimal integer number that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers that are out of
-that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers
+range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers
-that are out of range will yield over/underflow when used in a
+will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
-constructor. During deserialization, too large or small integer numbers
-will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md)
-or [`number_float_t`](number_float_t.md).
 
 [RFC 7159](http://rfc7159.net/rfc7159) further states:
-> Note that when such software is used, numbers that are integers and are
+> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
-> in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+> interoperable in the sense that implementations will agree exactly on their numeric values.
-> that implementations will agree exactly on their numeric values.
 
-As this range is a subrange of the exactly supported range [INT64_MIN,
+As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
-INT64_MAX], this class's integer type is interoperable.
+interoperable.
 
 #### Storage
 

doc/mkdocs/docs/api/basic_json/number_unsigned_t.md

@@ -7,41 +7,31 @@ using number_unsigned_t = NumberUnsignedType;
 The type used to store JSON numbers (unsigned).
 
 [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows:
-> The representation of numbers is similar to that used in most
+> The representation of numbers is similar to that used in most programming languages. A number is represented in base
-> programming languages. A number is represented in base 10 using decimal
+> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may
-> digits. It contains an integer component that may be prefixed with an
+> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that
-> optional minus sign, which may be followed by a fraction part and/or an
+> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.
-> exponent part. Leading zeros are not allowed. (...) Numeric values that
-> cannot be represented in the grammar below (such as Infinity and NaN)
-> are not permitted.
 
-This description includes both integer and floating-point numbers.
+This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is
-However, C++ allows more precise storage if it is known whether the number
+known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different
-is a signed integer, an unsigned integer or a floating-point number.
+types, [`number_integer_t`](number_integer_t.md), `number_unsigned_t` and [`number_float_t`](number_float_t.md) are
-Therefore, three different types, [`number_integer_t`](number_integer_t.md),
+used.
-`number_unsigned_t` and [`number_float_t`](number_float_t.md) are used.
 
-To store unsigned integer numbers in C++, a type is defined by the
+To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses
-template parameter `NumberUnsignedType` which chooses the type to use.
+the type to use.
 
 ## Notes
 
 #### Default type
 
-With the default values for `NumberUnsignedType` (`std::uint64_t`), the
+With the default values for `NumberUnsignedType` (`std::uint64_t`), the default value for `number_unsigned_t` is
-default value for `number_unsigned_t` is:
+`#!cpp std::uint64_t`.
-
-```cpp
-std::uint64_t
-```
 
 #### Default behavior
 
-- The restrictions about leading zeros is not enforced in C++. Instead,
+- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an
-  leading zeros in integer literals lead to an interpretation as octal
+  interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer 
-  number. Internally, the value will be stored as decimal number. For
+  literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error.
-  instance, the C++ integer literal `010` will be serialized to `8`.
-  During deserialization, leading zeros yield an error.
 - Not-a-number (NaN) values will be serialized to `null`.
 
 #### Limits
@@ -49,22 +39,17 @@ std::uint64_t
 [RFC 7159](http://rfc7159.net/rfc7159) specifies:
 > An implementation may set limits on the range and precision of numbers.
 
-When the default type is used, the maximal integer number that can be
+When the default type is used, the maximal integer number that can be stored is `18446744073709551615` (UINT64_MAX) and
-stored is `18446744073709551615` (UINT64_MAX) and the minimal integer
+the minimal integer number that can be stored is `0`. Integer numbers that are out of range will yield over/underflow
-number that can be stored is `0`. Integer numbers that are out of range
+when used in a constructor. During deserialization, too large or small integer numbers will be automatically be stored
-will yield over/underflow when used in a constructor. During
+as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md).
-deserialization, too large or small integer numbers will be automatically
-be stored as [`number_integer_t`](number_integer_t.md) or
-[`number_float_t`](number_float_t.md).
 
 [RFC 7159](http://rfc7159.net/rfc7159) further states:
-> Note that when such software is used, numbers that are integers and are
+> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are
-> in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense
+> interoperable in the sense that implementations will agree exactly on their numeric values.
-> that implementations will agree exactly on their numeric values.
 
-As this range is a subrange (when considered in conjunction with the
+As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported
-number_integer_t type) of the exactly supported range [0, UINT64_MAX],
+range [0, UINT64_MAX], this class's integer type is interoperable.
-this class's integer type is interoperable.
 
 #### Storage
 

doc/mkdocs/docs/api/basic_json/object.md

@@ -4,9 +4,8 @@
 static basic_json object(initializer_list_t init = {});
 ```
 
-Creates a JSON object value from a given initializer list. The initializer
+Creates a JSON object value from a given initializer list. The initializer lists elements must be pairs, and their first
-lists elements must be pairs, and their first elements must be strings. If
+elements must be strings. If the initializer list is empty, the empty object `#!json {}` is created.
-the initializer list is empty, the empty object `#!json {}` is created.
 
 ## Parameters
 
@@ -19,17 +18,14 @@ JSON object value
 
 ## Exceptions
 
-Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301)
+Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose
-if `init` is not a list of pairs whose first
+first elements are strings. In this case, no object can be created. When such a value is passed to
-elements are strings. In this case, no object can be created. When such a
+`basic_json(initializer_list_t, bool, value_t)`, an array would have been created from the passed initializer list
-value is passed to `basic_json(initializer_list_t, bool, value_t)`,
+`init`. See example below.
-an array would have been created from the passed initializer list `init`.
-See example below.
 
 ## Exception safety
 
-Strong guarantee: if an exception is thrown, there are no
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-changes in the JSON value.
 
 ## Complexity
 
@@ -37,18 +33,15 @@ Linear in the size of `init`.
 
 ## Notes
 
-This function is only added for symmetry reasons. In contrast to the
+This function is only added for symmetry reasons. In contrast to the related function `array(initializer_list_t)`, there
-related function `array(initializer_list_t)`, there are
+are no cases which can only be expressed by this function. That is, any initializer list `init` can also be passed to
-no cases which can only be expressed by this function. That is, any
+the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`.
-initializer list `init` can also be passed to the initializer list
-constructor `basic_json(initializer_list_t, bool, value_t)`.
     
 ## Examples
 
 ??? example
 
-    The following code shows an example for the `object`
+    The following code shows an example for the `object` function.
-    function.
 
     ```cpp
     --8<-- "examples/object.cpp"

doc/mkdocs/docs/api/basic_json/object_t.md

@@ -10,12 +10,10 @@ using object_t = ObjectType<StringType,
 The type used to store JSON objects.
 
 [RFC 7159](http://rfc7159.net/rfc7159) describes JSON objects as follows:
-> An object is an unordered collection of zero or more name/value pairs,
+> An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a
-> where a name is a string and a value is a string, number, boolean, null,
+> string, number, boolean, null, object, or array.
-> object, or array.
 
-To store objects in C++, a type is defined by the template parameters
+To store objects in C++, a type is defined by the template parameters described below.
-described below.
 
 ## Template parameters
 
@@ -23,9 +21,8 @@ described below.
 :   the container to store objects (e.g., `std::map` or `std::unordered_map`)
 
 `StringType`
-:   the type of the keys or names (e.g., `std::string`).
+:   the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to
-    The comparison function `std::less<StringType>` is used to order elements
+    order elements inside the container.
-    inside the container.
 
 `AllocatorType`
 :   the allocator to use for objects (e.g., `std::allocator`)
@@ -34,9 +31,8 @@ described below.
 
 #### Default type
 
-With the default values for `ObjectType` (`std::map`), `StringType`
+With the default values for `ObjectType` (`std::map`), `StringType` (`std::string`), and `AllocatorType`
-(`std::string`), and `AllocatorType` (`std::allocator`), the default
+(`std::allocator`), the default value for `object_t` is:
-value for `object_t` is:
 
 ```cpp
 std::map<
@@ -49,23 +45,19 @@ std::map<
 
 #### Behavior
 
-The choice of `object_t` influences the behavior of the JSON class. With
+The choice of `object_t` influences the behavior of the JSON class. With the default type, objects have the following
-the default type, objects have the following behavior:
+behavior:
 
-- When all names are unique, objects will be interoperable in the sense
+- When all names are unique, objects will be interoperable in the sense that all software implementations receiving that
-  that all software implementations receiving that object will agree on
+  object will agree on the name-value mappings.
-  the name-value mappings.
+- When the names within an object are not unique, it is unspecified which one of the values for a given key will be
-- When the names within an object are not unique, it is unspecified which
+  chosen. For instance, `#!json {"key": 2, "key": 1}` could be equal to either `#!json {"key": 1}` or
-  one of the values for a given key will be chosen. For instance,
-  `#!json {"key": 2, "key": 1}` could be equal to either `#!json {"key": 1}` or
   `#!json {"key": 2}`.
-- Internally, name/value pairs are stored in lexicographical order of the
+- Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see
-  names. Objects will also be serialized (see [`dump`](dump.md)) in this order.
+  [`dump`](dump.md)) in this order. For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored
-  For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored
   and serialized as `#!json {"a": 2, "b": 1}`.
-- When comparing objects, the order of the name/value pairs is irrelevant.
+- When comparing objects, the order of the name/value pairs is irrelevant. This makes objects interoperable in the sense
-  This makes objects interoperable in the sense that they will not be
+  that they will not be affected by these differences. For instance, `#!json {"b": 1, "a": 2}` and
-  affected by these differences. For instance, `#!json {"b": 1, "a": 2}` and
   `#!json {"a": 2, "b": 1}` will be treated as equal.
 
 #### Limits
@@ -73,26 +65,21 @@ the default type, objects have the following behavior:
 [RFC 7159](http://rfc7159.net/rfc7159) specifies:
 > An implementation may set limits on the maximum depth of nesting.
 
-In this class, the object's limit of nesting is not explicitly constrained.
+In this class, the object's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be
-However, a maximum depth of nesting may be introduced by the compiler or
+introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the
-runtime environment. A theoretical limit can be queried by calling the
 [`max_size`](max_size.md) function of a JSON object.
 
 #### Storage
 
-Objects are stored as pointers in a `basic_json` type. That is, for any
+Objects are stored as pointers in a `basic_json` type. That is, for any access to object values, a pointer of type
-access to object values, a pointer of type `object_t*` must be
+`object_t*` must be dereferenced.
-dereferenced.
 
 #### Object key order
 
-The order name/value pairs are added to the object is *not*
+The order name/value pairs are added to the object is *not* preserved by the library. Therefore, iterating an object may
-preserved by the library. Therefore, iterating an object may return
+return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in
-name/value pairs in a different order than they were originally stored. In
+alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
-fact, keys will be traversed in alphabetical order as `std::map` with
+[RFC 7159](http://rfc7159.net/rfc7159), because any order implements the specified "unordered" nature of JSON objects.
-`std::less` is used by default. Please note this behavior conforms to [RFC
-7159](http://rfc7159.net/rfc7159), because any order implements the
-specified "unordered" nature of JSON objects.
 
 ## Version history
 

doc/mkdocs/docs/api/basic_json/operator+=.md

@@ -12,13 +12,11 @@ reference operator+=(const typename object_t::value_type& val);
 reference operator+=(initializer_list_t init);
 ```
 
-1. Appends the given element `val` to the end of the JSON array. If the
+1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an
-   function is called on a JSON null value, an empty array is created before
+   empty array is created before appending `val`.
-   appending `val`.
 
-2. Inserts the given element `val` to the JSON object. If the function is
+2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
-   called on a JSON null value, an empty object is created before inserting
+   is created before inserting `val`.
-   `val`.
 
 3. This function allows to use `operator+=` with an initializer list. In case
 
@@ -26,9 +24,8 @@ reference operator+=(initializer_list_t init);
     2. the initializer list `init` contains only two elements, and
     3. the first element of `init` is a string,
 
-    `init` is converted into an object element and added using
+    `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
-    `operator+=(const typename object_t::value_type&)`. Otherwise, `init`
+    Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
-    is converted to a JSON value and added using `operator+=(basic_json&&)`.
 
 ## Parameters
 
@@ -45,11 +42,11 @@ reference operator+=(initializer_list_t init);
 ## Exceptions
 
 1. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON array or
+    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      null; example: `"cannot use operator+=() with number"`
+      JSON array or null; example: `"cannot use operator+=() with number"`
 2. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON object or
+    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      null; example: `"cannot use operator+=() with number"`
+      JSON object or null; example: `"cannot use operator+=() with number"`
 
 ## Complexity
 
@@ -59,18 +56,16 @@ reference operator+=(initializer_list_t init);
 
 ## Notes
 
-(3) This function is required to resolve an ambiguous overload error,
+(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both
-because pairs like `{"key", "value"}` can be both interpreted as
+interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, see
-`object_t::value_type` or `std::initializer_list<basic_json>`, see
 [#235](https://github.com/nlohmann/json/issues/235) for more information.
 
 ## Examples
 
 ??? example
 
-    The example shows how `push_back()` and `+=` can be used to
+    The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
-    add elements to a JSON array. Note how the `null` value was silently
+    was silently converted to a JSON array.
-    converted to a JSON array.
     
     ```cpp
     --8<-- "examples/push_back.cpp"
@@ -84,9 +79,8 @@ because pairs like `{"key", "value"}` can be both interpreted as
 
 ??? example
 
-    The example shows how `push_back()` and `+=` can be used to
+    The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
-    add elements to a JSON object. Note how the `null` value was silently
+    was silently converted to a JSON object.
-    converted to a JSON object.
 
     ```cpp
     --8<-- "examples/push_back__object_t__value.cpp"
@@ -100,8 +94,7 @@ because pairs like `{"key", "value"}` can be both interpreted as
 
 ??? example
 
-    The example shows how initializer lists are treated as
+    The example shows how initializer lists are treated as objects when possible.
-    objects when possible.
 
     ```cpp
     --8<-- "examples/push_back__initializer_list.cpp"

doc/mkdocs/docs/api/basic_json/operator=.md

@@ -9,9 +9,8 @@ basic_json& operator=(basic_json other) noexcept (
 );
 ```
 
-Copy assignment operator. Copies a JSON value via the "copy and swap"
+Copy assignment operator. Copies a JSON value via the "copy and swap" strategy: It is expressed in terms of the copy
-strategy: It is expressed in terms of the copy constructor, destructor,
+constructor, destructor, and the `swap()` member function.
-and the `swap()` member function.
 
 ## Parameters
 
@@ -26,10 +25,8 @@ Linear.
 
 ??? example
 
-    The code below shows and example for the copy assignment. It
+    The code below shows and example for the copy assignment. It creates a copy of value `a` which is then swapped with
-    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    `b`. Finally, the copy of `a` (which is the null value after the swap) is destroyed.
-    copy of `a` (which is the null value after the swap) is
-    destroyed.
      
     ```cpp
     --8<-- "examples/basic_json__copyassignment.cpp"

doc/mkdocs/docs/api/basic_json/operator==.md

@@ -12,11 +12,10 @@ bool operator==(ScalarType lhs, const const_reference rhs) noexcept;
 
 Compares two JSON values for equality according to the following rules:
 
-- Two JSON values are equal if (1) they are from the same type and (2)
+- Two JSON values are equal if (1) they are from the same type and (2) their stored values are the same according to
-  their stored values are the same according to their respective
+  their respective `operator==`.
-  `operator==`.
+- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
-- Integer and floating-point numbers are automatically converted before
+  treated as unequal.
-  comparison. Note that two NaN values are always treated as unequal.
 - Two JSON null values are equal.
 
 ## Template parameters
@@ -46,11 +45,10 @@ Linear.
 
 ## Notes
 
-- Floating-point inside JSON values numbers are compared with
+- Floating-point inside JSON values numbers are compared with `json::number_float_t::operator==` which is
-`json::number_float_t::operator==` which is `double::operator==` by
+  `double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative
-default. To compare floating-point while respecting an epsilon, an alternative
+  [comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
-[comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
+  could be used, for instance
-could be used, for instance
 
     ```cpp
     template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
@@ -84,18 +82,19 @@ could be used, for instance
 
 ## Example
 
-The example demonstrates comparing several JSON
+??? example
-types.
+
+    The example demonstrates comparing several JSON types.
+        
+    ```cpp
+    --8<-- "examples/operator__equal.cpp"
+    ```
     
-```cpp
+    Output:
---8<-- "examples/operator__equal.cpp"
+    
-```
+    ```json
-
+    --8<-- "examples/operator__equal.output"
-Output:
+    ```
-
-```json
---8<-- "examples/operator__equal.output"
-```
 
 ## Version history
 

doc/mkdocs/docs/api/basic_json/operator[].md

@@ -47,51 +47,45 @@ const_reference operator[](const json_pointer& ptr) const;
 ## Exceptions
 
 1. The function can throw the following exceptions:
-    - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array or null; in that
+    - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
-      cases, using the `[]` operator with an index makes no sense.
+      or null; in that cases, using the `[]` operator with an index makes no sense.
 2. The function can throw the following exceptions:
-    - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array or null; in that
+    - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
-      cases, using the `[]` operator with an index makes no sense.
+      or null; in that cases, using the `[]` operator with an index makes no sense.
 3. The function can throw the following exceptions:
-    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed JSON pointer `ptr`
+    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
-      begins with '0'.
+      JSON pointer `ptr` begins with '0'.
-    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed JSON pointer `ptr`
+    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
-      is not a number.
+      JSON pointer `ptr` is not a number.
-    - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used in the passed JSON
+    - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
-      pointer `ptr` for the const version.
+      in the passed JSON pointer `ptr` for the const version.
-    - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can not be resolved.
+    - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
+      not be resolved.
 
 ## Notes
 
 !!! danger
 
-    1. If the element with key `idx` does not exist, the behavior is
+    1. If the element with key `idx` does not exist, the behavior is undefined.
-       undefined.
+    2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by an assertion**!
-    2. If the element with key `key` does not exist, the behavior is
-       undefined and is **guarded by an assertion**!
 
-1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`),
+1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the
-   then the array is silently filled up with `#!json null` values to make `idx` a
+   array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In
-   valid reference to the last stored element.
+   case the value was `#!json null` before, it is converted to an array.
-   In case the value was `#!json null` before, it is converted to an array.
 
-2. If `key` is not found in the object, then it is silently added to
+2. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to
-   the object and filled with a `#!json null` value to make `key` a valid reference.
+   make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object.
-   In case the value was `#!json null` before, it is converted to an object.
 
 3. `null` values are created in arrays and objects if necessary.
    
     In particular:
 
-    - If the JSON pointer points to an object key that does not exist, it
+    - If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null`
-      is created an filled with a `null` value before a reference to it
+      value before a reference to it is returned.
-      is returned.
+    - If the JSON pointer points to an array index that does not exist, it is created an filled with a `#!json null`
-    - If the JSON pointer points to an array index that does not exist, it
+      value before a reference to it is returned. All indices between the current maximum and the given index are also
-      is created an filled with a `null` value before a reference to it
+      filled with `#!json null`.
-      is returned. All indices between the current maximum and the given
+    - The special value `-` is treated as a synonym for the index past the end.
-      index are also filled with `null`.
-    - The special value `-` is treated as a synonym for the index past the
-      end.
 
 ## Exception safety
 
@@ -107,9 +101,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ??? example
 
-    The example below shows how array elements can be read and
+    The example below shows how array elements can be read and written using `[]` operator. Note the addition of
-    written using `[]` operator. Note the addition of `null`
+    `#!json null` values.
-    values.
         
     ```cpp
     --8<-- "examples/operatorarray__size_type.cpp"
@@ -123,8 +116,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ??? example
 
-    The example below shows how array elements can be read using
+    The example below shows how array elements can be read using the `[]` operator.
-    the `[]` operator.
 
     ```cpp
     --8<-- "examples/operatorarray__size_type_const.cpp"
@@ -138,8 +130,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ??? example
 
-    The example below shows how object elements can be read and
+    The example below shows how object elements can be read and written using the `[]` operator.
-    written using the `[]` operator.
     
     ```cpp
     --8<-- "examples/operatorarray__key_type.cpp"
@@ -153,8 +144,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ??? example
 
-    The example below shows how object elements can be read using
+    The example below shows how object elements can be read using the `[]` operator.
-    the `[]` operator.
     
     ```cpp
     --8<-- "examples/operatorarray__key_type_const.cpp"

doc/mkdocs/docs/api/basic_json/operator_value_t.md

@@ -4,8 +4,7 @@
 constexpr operator value_t() const noexcept;
 ```
 
-Return the type of the JSON value as a value from the [`value_t`](value_t.md)
+Return the type of the JSON value as a value from the [`value_t`](value_t.md) enumeration.
-enumeration.
     
 ## Return value
 
@@ -36,8 +35,7 @@ Constant.
 
 ??? example
 
-    The following code exemplifies `operator value_t()` for all JSON
+    The following code exemplifies `operator value_t()` for all JSON types.
-    types.
     
     ```cpp
     --8<-- "examples/operator__value_t.cpp"

doc/mkdocs/docs/api/basic_json/parser_callback_t.md

@@ -6,16 +6,13 @@ using parser_callback_t =
     std::function<bool(int depth, parse_event_t event, BasicJsonType& parsed)>;
 ```
 
-With a parser callback function, the result of parsing a JSON text can be
+With a parser callback function, the result of parsing a JSON text can be influenced. When passed to
-influenced. When passed to [`parse`](parse.md), it is called on certain events
+[`parse`](parse.md), it is called on certain events (passed as [`parse_event_t`](parse_event_t.md) via parameter
-(passed as [`parse_event_t`](parse_event_t.md) via parameter `event`) with a set recursion
+`event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the callback function
-depth `depth` and context JSON value `parsed`. The return value of the
+is a boolean indicating whether the element that emitted the callback shall be kept or not.
-callback function is a boolean indicating whether the element that emitted
-the callback shall be kept or not.
 
-We distinguish six scenarios (determined by the event type) in which the
+We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
-callback function can be called. The following table describes the values
+table describes the values of the parameters `depth`, `event`, and `parsed`.
-of the parameters `depth`, `event`, and `parsed`.
 
 parameter `event` | description | parameter `depth` | parameter `parsed`
 ------------------ | ----------- | ------------------ | -------------------
@@ -28,13 +25,13 @@ parameter `event` | description | parameter `depth` | parameter `parsed`
 
 ![Example when certain parse events are triggered](../../images/callback_events.png)
 
-Discarding a value (i.e., returning `#!cpp false`) has different effects
+Discarding a value (i.e., returning `#!cpp false`) has different effects depending on the context in which function was
-depending on the context in which function was called:
+called:
 
-- Discarded values in structured types are skipped. That is, the parser
+- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
-  will behave as if the discarded value was never read.
+  read.
-- In case a value outside a structured type is skipped, it is replaced
+- In case a value outside a structured type is skipped, it is replaced with `null`. This case happens if the top-level
-  with `null`. This case happens if the top-level element is skipped.
+  element is skipped.
 
 ## Parameters
 
@@ -51,9 +48,8 @@ depending on the context in which function was called:
 
 ## Return value
 
-Whether the JSON value which called the function during parsing
+Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
-should be kept (`#!cpp true`) or not (`#!cpp false`). In the latter case, it is either
+the latter case, it is either skipped completely or replaced by an empty discarded object.
-skipped completely or replaced by an empty discarded object.
 
 # Example
 

doc/mkdocs/docs/api/basic_json/patch.md

@@ -4,10 +4,9 @@
 basic_json patch(const basic_json& json_patch) const;
 ```
 
-[JSON Patch](http://jsonpatch.com) defines a JSON document structure for
+[JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
-expressing a sequence of operations to apply to a JSON) document. With
+a JSON) document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
-this function, a JSON Patch is applied to the current JSON value by
+the patch.
-executing all operations from the patch.
 
 ## Parameters
 
@@ -20,40 +19,37 @@ patched document
 
 ## Exceptions
 
-- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of an array of
+- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of
-  objects.
+  an array of objects.
-- Throws [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105) if the JSON patch is malformed (e.g., mandatory
+- Throws [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105) if the JSON patch is malformed (e.g.,
-  attributes are missing); example: `"operation add must have member path"`.
+  mandatory attributes are missing); example: `"operation add must have member path"`.
 - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index is out of range.
-- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch could not be
+- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch
-  resolved successfully in the current JSON value; example: `"key baz not found"`.
+  could not be resolved successfully in the current JSON value; example: `"key baz not found"`.
-- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent ("add", "remove", "move")
+- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent
-- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was unsuccessful.
+  ("add", "remove", "move")
+- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was
+  unsuccessful.
 
 ## Exception safety
 
-Strong guarantee: if an exception is thrown, there are no
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-changes in the JSON value.
 
 ## Complexity
 
-Linear in the size of the JSON value and the length of the
+Linear in the size of the JSON value and the length of the JSON patch. As usually only a fraction of the JSON value is
-JSON patch. As usually only a fraction of the JSON value is affected by
+affected by the patch, the complexity can usually be neglected.
-the patch, the complexity can usually be neglected.
 
 ## Note
 
-The application of a patch is atomic: Either all operations succeed
+The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception
-  and the patched document is returned or an exception is thrown. In
+is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
-  any case, the original value is not changed: the patch is applied
-  to a copy of the value.
 
 ## Example
 
 ??? example
 
-    The following code shows how a JSON patch is applied to a
+    The following code shows how a JSON patch is applied to a value.
-    value.
      
     ```cpp
     --8<-- "examples/patch.cpp"

doc/mkdocs/docs/api/basic_json/push_back.md

@@ -12,13 +12,11 @@ void push_back(const typename object_t::value_type& val);
 void push_back(initializer_list_t init);
 ```
 
-1. Appends the given element `val` to the end of the JSON array. If the
+1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an
-   function is called on a JSON null value, an empty array is created before
+   empty array is created before appending `val`.
-   appending `val`.
 
-2. Inserts the given element `val` to the JSON object. If the function is
+2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
-   called on a JSON null value, an empty object is created before inserting
+   is created before inserting `val`.
-   `val`.
 
 3. This function allows to use `push_back` with an initializer list. In case
 
@@ -26,9 +24,8 @@ void push_back(initializer_list_t init);
     2. the initializer list `init` contains only two elements, and
     3. the first element of `init` is a string,
 
-    `init` is converted into an object element and added using
+    `init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`.
-    `push_back(const typename object_t::value_type&)`. Otherwise, `init`
+    Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`.
-    is converted to a JSON value and added using `push_back(basic_json&&)`.
 
 ## Parameters
 
@@ -41,11 +38,11 @@ void push_back(initializer_list_t init);
 ## Exceptions
 
 1. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON array or
+    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      null; example: `"cannot use push_back() with number"`
+      JSON array or null; example: `"cannot use push_back() with number"`
 2. The function can throw the following exceptions:
-    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON object or
+    - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than
-      null; example: `"cannot use push_back() with number"`
+      JSON object or null; example: `"cannot use push_back() with number"`
 
 ## Complexity
 
@@ -55,18 +52,16 @@ void push_back(initializer_list_t init);
 
 ## Notes
 
-(3) This function is required to resolve an ambiguous overload error,
+(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both
-because pairs like `{"key", "value"}` can be both interpreted as
+    interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, see
-`object_t::value_type` or `std::initializer_list<basic_json>`, see
+    [#235](https://github.com/nlohmann/json/issues/235) for more information.
-[#235](https://github.com/nlohmann/json/issues/235) for more information.
 
 ## Examples
 
 ??? example
 
-    The example shows how `push_back()` and `+=` can be used to
+    The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
-    add elements to a JSON array. Note how the `null` value was silently
+    was silently converted to a JSON array.
-    converted to a JSON array.
     
     ```cpp
     --8<-- "examples/push_back.cpp"
@@ -80,9 +75,8 @@ because pairs like `{"key", "value"}` can be both interpreted as
 
 ??? example
 
-    The example shows how `push_back()` and `+=` can be used to
+    The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
-    add elements to a JSON object. Note how the `null` value was silently
+    was silently converted to a JSON object.
-    converted to a JSON object.
 
     ```cpp
     --8<-- "examples/push_back__object_t__value.cpp"
@@ -96,8 +90,7 @@ because pairs like `{"key", "value"}` can be both interpreted as
 
 ??? example
 
-    The example shows how initializer lists are treated as
+    The example shows how initializer lists are treated as objects when possible.
-    objects when possible.
 
     ```cpp
     --8<-- "examples/push_back__initializer_list.cpp"

doc/mkdocs/docs/api/basic_json/rend.md

@@ -5,8 +5,8 @@ reverse_iterator rend() noexcept;
 const_reverse_iterator rend() const noexcept;
 ```
 
-Returns an iterator to the reverse-end; that is, one before the first
+Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder,
-element. This element acts as a placeholder, attempting to access it results in undefined behavior.
+attempting to access it results in undefined behavior.
 
 ![Illustration from cppreference.com](../../images/range-rbegin-rend.svg)
 

doc/mkdocs/docs/api/basic_json/sax_parse.md

@@ -23,8 +23,8 @@ Read from input and generate SAX events
 1. Read from a compatible input.
 2. Read from a pair of character iterators
     
-    The value_type of the iterator must be a integral type with size of 1, 2 or
+    The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
-    4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32.
+    respectively as UTF-8, UTF-16 and UTF-32.
 
 The SAX event lister must follow the interface of `json_sax`.
 
@@ -61,9 +61,8 @@ The SAX event lister must follow the interface of `json_sax`.
 :   whether the input has to be consumed completely (optional, `#!cpp true` by default)
 
 `ignore_comments` (in)
-:   whether comments should be ignored and treated
+:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
-    like whitespace (`#!cpp true`) or yield a parse error (`#!cpp false`); (optional, `#!cpp false` by
+    (`#!cpp false`); (optional, `#!cpp false` by default)
-    default)
 
 `first` (in)
 :   iterator to start of character range
@@ -79,9 +78,8 @@ return value of the last processed SAX event
 
 ## Complexity
 
-Linear in the length of the input. The parser is a predictive
+Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX
-LL(1) parser. The complexity can be higher if the SAX consumer `sax` has
+consumer `sax` has a super-linear complexity.
-a super-linear complexity.
 
 ## Notes
 
@@ -91,9 +89,8 @@ A UTF-8 byte order mark is silently ignored.
 
 ??? example
 
-    The example below demonstrates the `sax_parse()` function
+    The example below demonstrates the `sax_parse()` function reading from string and processing the events with a
-    reading from string and processing the events with a user-defined SAX
+    user-defined SAX event consumer.
-    event consumer.
     
     ```cpp
     --8<-- "examples/sax_parse.cpp"

doc/mkdocs/docs/api/basic_json/size.md

@@ -8,8 +8,7 @@ Returns the number of elements in a JSON value.
     
 ## Return value
 
-The return value depends on the different types and is
+The return value depends on the different types and is defined as follows:
-defined as follows:
 
 Value type  | return value
 ----------- | -------------
@@ -27,22 +26,20 @@ No-throw guarantee: this function never throws exceptions.
 
 ## Complexity
 
-Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy
+Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy the
-the Container concept; that is, their `size()` functions have constant
+[Container](https://en.cppreference.com/w/cpp/named_req/Container) concept; that is, their `size()` functions have
-complexity.
+constant complexity.
 
 ## Notes
 
-This function does not return the length of a string stored as JSON
+This function does not return the length of a string stored as JSON value -- it returns the number of elements in the
-value - it returns the number of elements in the JSON value which is `1` in
+JSON value which is `1` in the case of a string.
-the case of a string.
 
 ## Example
 
 ??? example
 
-    The following code calls `size()` on the different value
+    The following code calls `size()` on the different value types.
-    types.
     
     ```cpp
     --8<-- "examples/size.cpp"

doc/mkdocs/docs/api/basic_json/string_t.md

@@ -9,53 +9,41 @@ The type used to store JSON strings.
 [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows:
 > A string is a sequence of zero or more Unicode characters.
 
-To store objects in C++, a type is defined by the template parameter
+To store objects in C++, a type is defined by the template parameter described below. Unicode values are split by the
-described below. Unicode values are split by the JSON class into
+JSON class into byte-sized characters during deserialization.
-byte-sized characters during deserialization.
 
 ## Template parameters
 
 `StringType`
-:   the container to store strings (e.g., `std::string`).
+:   the container to store strings (e.g., `std::string`). Note this container is used for keys/names in objects, see
-    Note this container is used for keys/names in objects, see [object_t](object_t.md).
+    [object_t](object_t.md).
 
 ## Notes
 
 #### Default type
 
-With the default values for `StringType` (`std::string`), the default
+With the default values for `StringType` (`std::string`), the default value for `string_t` is `#!cpp std::string`.
-value for `string_t` is:
-
-```cpp
-std::string
-```
 
 #### Encoding
 
-Strings are stored in UTF-8 encoding. Therefore, functions like
+Strings are stored in UTF-8 encoding. Therefore, functions like `std::string::size()` or `std::string::length()` return
-`std::string::size()` or `std::string::length()` return the number of
+the number of bytes in the string rather than the number of characters or glyphs.
-bytes in the string rather than the number of characters or glyphs.
 
 #### String comparison
 
 [RFC 7159](http://rfc7159.net/rfc7159) states:
-> Software implementations are typically required to test names of object
+> Software implementations are typically required to test names of object members for equality. Implementations that
-> members for equality. Implementations that transform the textual
+> transform the textual representation into sequences of Unicode code units and then perform the comparison numerically,
-> representation into sequences of Unicode code units and then perform the
+> code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or
-> comparison numerically, code unit by code unit, are interoperable in the
+> inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may
-> sense that implementations will agree in all cases on equality or
+> incorrectly find that `"a\\b"` and `"a\u005Cb"` are not equal.
-> inequality of two strings. For example, implementations that compare
-> strings with escaped characters unconverted may incorrectly find that
-> `"a\\b"` and `"a\u005Cb"` are not equal.
 
-This implementation is interoperable as it does compare strings code unit
+This implementation is interoperable as it does compare strings code unit by code unit.
-by code unit.
 
 #### Storage
 
-String values are stored as pointers in a `basic_json` type. That is,
+String values are stored as pointers in a `basic_json` type. That is, for any access to string values, a pointer of type
-for any access to string values, a pointer of type `string_t*` must be
+`string_t*` must be dereferenced.
-dereferenced.
 
 ## Version history
 

doc/mkdocs/docs/api/basic_json/type.md

@@ -4,9 +4,8 @@
 constexpr value_t type() const noexcept;
 ```
 
-Return the type of the JSON value as a value from the [`value_t`](value_t.md)
+Return the type of the JSON value as a value from the [`value_t`](value_t.md) enumeration.
-enumeration.
+
-    
 ## Return value
 
 the type of the JSON value
@@ -36,8 +35,7 @@ Constant.
 
 ??? example
 
-    The following code exemplifies `type()` for all JSON
+    The following code exemplifies `type()` for all JSON types.
-    types.
     
     ```cpp
     --8<-- "examples/type.cpp"

doc/mkdocs/docs/api/basic_json/type_name.md

@@ -4,8 +4,8 @@
 const char* type_name() const noexcept;
 ```
 
-Returns the type name as string to be used in error messages - usually to
+Returns the type name as string to be used in error messages -- usually to indicate that a function was called on a
-indicate that a function was called on a wrong JSON type.
+wrong JSON type.
     
 ## Return value
 
@@ -34,8 +34,7 @@ Constant.
 
 ??? example
 
-    The following code exemplifies `type_name()` for all JSON
+    The following code exemplifies `type_name()` for all JSON types.
-    types.
     
     ```cpp
     --8<-- "examples/type_name.cpp"

doc/mkdocs/docs/api/basic_json/unflatten.md

@@ -4,13 +4,11 @@
 basic_json unflatten() const;
 ```
 
-The function restores the arbitrary nesting of a JSON value that has been
+The function restores the arbitrary nesting of a JSON value that has been flattened before using the
-flattened before using the [`flatten()`](flatten.md) function. The JSON value must
+[`flatten()`](flatten.md) function. The JSON value must meet certain constraints:
-meet certain constraints:
 
 1. The value must be an object.
-2. The keys must be JSON pointers (see
+2. The keys must be JSON pointers (see [RFC 6901](https://tools.ietf.org/html/rfc6901))
-   [RFC 6901](https://tools.ietf.org/html/rfc6901))
 3. The mapped values must be primitive JSON types.
     
 ## Return value
@@ -34,17 +32,15 @@ Linear in the size the JSON value.
 
 ## Notes
 
-Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null`
+Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and can not unflattened to
-values and can not unflattened to their original type. Apart from
+their original type. Apart from this example, for a JSON value `j`, the following is always true:
-this example, for a JSON value `j`, the following is always true:
 `#!cpp j == j.flatten().unflatten()`.
 
 ## Example
 
 ??? example
 
-    The following code shows how a flattened JSON object is
+    The following code shows how a flattened JSON object is unflattened into the original nested JSON object.
-    unflattened into the original nested JSON object.
     
     ```cpp
     --8<-- "examples/unflatten.cpp"

doc/mkdocs/docs/api/basic_json/update.md

@@ -11,7 +11,8 @@ void update(const_iterator first, const_iterator last);
 1. Inserts all values from JSON object `j` and overwrites existing keys.
 2. Inserts all values from from range `[first, last)` and overwrites existing keys.
 
-The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update) function.
+The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update)
+function.
 
 ## Parameters
 
@@ -27,16 +28,15 @@ The function is motivated by Python's [dict.update](https://docs.python.org/3.6/
 ## Exceptions
 
 1. The function can throw thw following exceptions:
-    - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than objects;
+    - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
-      example: `"cannot use update() with string"`
+      objects; example: `"cannot use update() with string"`
 2. The function can throw thw following exceptions:
-    - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than objects;
+    - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
-      example: `"cannot use update() with string"`
+      objects; example: `"cannot use update() with string"`
-    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an iterator which does not belong
+    - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an
-      to the current JSON value; example: `"iterator does not fit current
+      iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"`
-      value"`
+    - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
-    - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last` do not belong to the
+      do not belong to the same JSON value; example: `"iterators do not fit"`
-      same JSON value; example: `"iterators do not fit"`
 
 ## Complexity
 

doc/mkdocs/docs/api/basic_json/value.md

@@ -12,8 +12,8 @@ ValueType value(const json_pointer& ptr,
                 const ValueType& default_value) const;
 ```
 
-1. Returns either a copy of an object's element at the specified key `key`
+1. Returns either a copy of an object's element at the specified key `key` or a given default value if no element with
-   or a given default value if no element with key `key` exists.
+   key `key` exists.
    
     The function is basically equivalent to executing
     ```cpp
@@ -24,8 +24,8 @@ ValueType value(const json_pointer& ptr,
     }
     ```
 
-2. Returns either a copy of an object's element at the specified JSON pointer `ptr`
+2. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value
-   or a given default value if no value at `ptr` exists.
+   at `ptr` exists.
    
     The function is basically equivalent to executing
     ```cpp
@@ -36,16 +36,14 @@ ValueType value(const json_pointer& ptr,
     }
     ```
 
-Unlike [`operator[]`](operator[].md), this
+Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by
-function does not implicitly add an element to the position defined by `key`/`ptr`
+`key`/`ptr` key. This function is furthermore also applicable to const objects.
-key. This function is furthermore also applicable to const objects.
 
 ## Template parameters
 
 `ValueType` 
-:   type compatible to JSON values, for instance `#!cpp int` for
+:   type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans,
-    JSON integer numbers, `#!cpp bool` for JSON booleans, or `#!cpp std::vector` types for
+    or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
-    JSON arrays. Note the type of the expected value at `key`/`ptr` and the default
     value `default_value` must be compatible.
 
 ## Parameters
@@ -72,15 +70,15 @@ changes to any JSON value.
 ## Exceptions
 
 1. The function can throw thw following exceptions:
-    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match the type of the
+    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
-      value at `key`
+      the type of the value at `key`
-    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; in that case,
+    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
-      using `value()` with a key makes no sense.
+      in that case, using `value()` with a key makes no sense.
 2. The function can throw thw following exceptions:
-    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match the type of the
+    - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match
-      value at `ptr`
+      the type of the value at `ptr`
-    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; in that case,
+    - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object;
-      using `value()` with a key makes no sense.
+      in that case, using `value()` with a key makes no sense.
 
 ## Complexity
 
@@ -91,8 +89,7 @@ changes to any JSON value.
 
 ??? example
 
-    The example below shows how object elements can be queried
+    The example below shows how object elements can be queried with a default value.
-    with a default value.
     
     ```cpp
     --8<-- "examples/basic_json__value.cpp"
@@ -106,8 +103,7 @@ changes to any JSON value.
 
 ??? example
 
-    The example below shows how object elements can be queried
+    The example below shows how object elements can be queried with a default value.
-    with a default value.
     
     ```cpp
     --8<-- "examples/basic_json__value_ptr.cpp"

doc/mkdocs/docs/api/basic_json/value_t.md

@@ -15,23 +15,19 @@ enum class value_t : std::uint8_t {
 };
 ```
 
-This enumeration collects the different JSON types. It is internally used to
+This enumeration collects the different JSON types. It is internally used to distinguish the stored values, and the
-distinguish the stored values, and the functions [`is_null`](is_null.md),
+functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_array.md), [`is_string`](is_string.md),
-[`is_object`](is_object.md), [`is_array`](is_array.md),
+[`is_boolean`](is_boolean.md), [`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md),
-[`is_string`](is_string.md), [`is_boolean`](is_boolean.md),
-[`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md),
 [`is_number_unsigned`](is_number_unsigned.md), and [`is_number_float`](is_number_float.md)),
 [`is_discarded`](is_discarded.md), [`is_binary`](is_binary.md), [`is_primitive`](is_primitive.md), and
 [`is_structured`](is_structured.md) rely on it.
 
 ## Note
 
-There are three enumeration entries (number_integer, number_unsigned, and
+There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library
-number_float), because the library distinguishes these three types for numbers:
+distinguishes these three types for numbers: [`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
-[`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers,
+[`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
-[`number_integer_t`](number_integer_t.md) is used for signed integers, and
+for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
-[`number_float_t`](number_float_t.md) is used for floating-point numbers or to
-approximate integers which do not fit in the limits of their respective type.
 
 ## Version history