Consolidate documentation (#3071)

* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables

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

@@ -1,4 +1,4 @@
-# basic_json::accept
+# <small>nlohmann::basic_json::</small>accept
 
 ```cpp
 // (1)
@@ -17,7 +17,7 @@ Checks whether the input is valid JSON.
 1. Reads from a compatible input.
 2. Reads from a pair of character iterators
     
-    The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
+    The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
     respectively as UTF-8, UTF-16 and UTF-32.
     
 Unlike the [`parse`](parse.md) function, this function neither throws an exception in case of invalid JSON input
@@ -84,7 +84,21 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
     --8<-- "examples/accept__string.output"
     ```
 
+## See also
+
+- [parse](parse.md) - deserialize from a compatible input
+- [operator>>](operator_gtgt.md) - deserialize from stream
+
 ## Version history
 
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
+
+!!! warning "Deprecation"
+
+    Overload (2) replaces calls to `accept` with a pair of iterators as their first parameter which has been
+    deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+    `#!cpp accept({ptr, ptr+len}, ...);` with `#!cpp accept(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::array
+# <small>nlohmann::basic_json::</small>array
 
 ```cpp
 static basic_json array(initializer_list_t init = {});
@@ -50,6 +50,11 @@ This function is only needed to express two edge cases that cannot be realized w
     --8<-- "examples/array.output"
     ```
 
+## See also
+
+- [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
+- [`object`](object.md) - create a JSON object value from an initializer list
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::array_t
+# <small>nlohmann::basic_json::</small>array_t
 
 ```cpp
 using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;
@@ -47,6 +47,22 @@ introduced by the compiler or runtime environment. A theoretical limit can be qu
 Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of type
 `#!cpp array_t*` must be dereferenced.
 
+## Examples
+
+??? example
+
+    The following code shows that `array_t` is by default, a typedef to `#!cpp std::vector<nlohmann::json>`.
+     
+    ```cpp
+    --8<-- "examples/array_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/array_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::at
+# <small>nlohmann::basic_json::</small>at
 
 ```cpp
 // (1)
@@ -14,8 +14,8 @@ reference at(const json_pointer& ptr);
 const_reference at(const json_pointer& ptr) const;
 ```
 
-1. Returns a reference to the element at specified location `idx`, with bounds checking.
-2. Returns a reference to the element at with specified key `key`, with bounds checking.
+1. Returns a reference to the array element at specified location `idx`, with bounds checking.
+2. Returns a reference to the object element at with specified key `key`, with bounds checking.
 3. Returns a reference to the element at with specified JSON pointer `ptr`, with bounds checking.
 
 ## Parameters
@@ -35,6 +35,10 @@ const_reference at(const json_pointer& ptr) const;
 2. reference to the element at key `key`
 3. reference to the element pointed to by `ptr`
 
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
 ## Exceptions
 
 1. The function can throw the following exceptions:
@@ -45,7 +49,7 @@ const_reference at(const json_pointer& ptr) const;
 2. The function can throw the following exceptions:
     - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
       in this case, calling `at` with a key makes no sense. See example below.
-    - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is is not
+    - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
       stored in the object; that is, `find(key) == end()`. See example below.
 3. The function can throw the following exceptions:
     - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
@@ -62,19 +66,15 @@ const_reference at(const json_pointer& ptr) const;
     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
       not be resolved. See example below.
 
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
 ## Complexity
 
 1. Constant
 2. Logarithmic in the size of the container.
 3. Constant
 
-## Example
+## Examples
 
-??? example
+??? example "Example: (1) access specified array element with bounds checking"
 
     The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
     exceptions that can be thrown.
@@ -89,7 +89,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__size_type.output"
     ```
 
-??? example
+??? example "Example: (1) access specified array element with bounds checking"
 
     The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
@@ -104,7 +104,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__size_type_const.output"
     ```
 
-??? example
+??? example "Example: (2) access specified object element with bounds checking"
 
     The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
     exceptions that can be thrown.
@@ -119,7 +119,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__object_t_key_type.output"
     ```
 
-??? example
+??? example "Example (2) access specified object element with bounds checking"
 
     The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
@@ -134,7 +134,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__object_t_key_type_const.output"
     ```
 
-??? example
+??? example "Example (3) access specified element via JSON Pointer"
 
     The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
     exceptions that can be thrown.
@@ -149,7 +149,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at_json_pointer.output"
     ```
 
-??? example
+??? example "Example (3) access specified element via JSON Pointer"
 
     The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
@@ -164,6 +164,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at_json_pointer_const.output"
     ```
 
+## See also
+
+- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
+- see [`value`](value.md) for access with default value
+
 ## Version history
 
 1. Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::back
+# <small>nlohmann::basic_json::</small>back
 
 ```cpp
 reference back();
@@ -20,26 +20,26 @@ return *tmp;
 In case of a structured type (array or object), a reference to the last element is returned. In case of number, string,
 boolean, or binary values, a reference to the value is returned.
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
 ## Exceptions
 
 If the JSON value is `#!json null`, exception
 [`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
 
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
 ## Complexity
 
 Constant.
 
-## Note
+## Notes
 
 !!! danger
 
     Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**!
 
-## Example
+## Examples
 
 ??? example
 
@@ -55,6 +55,10 @@ Constant.
     --8<-- "examples/back.output"
     ```
 
+## See also
+
+- [front](front.md) to access the first element
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,53 +1,55 @@
-# basic_json::basic_json
+# <small>nlohmann::basic_json::</small>basic_json
 
 ```cpp
-// 1
+// (1)
 basic_json(const value_t v);
 
-// 2
+// (2)
 basic_json(std::nullptr_t = nullptr) noexcept;
 
-// 3
+// (3)
 template<typename CompatibleType>
 basic_json(CompatibleType&& val) noexcept(noexcept(
            JSONSerializer<U>::to_json(std::declval<basic_json_t&>(),
                                       std::forward<CompatibleType>(val))));
 
-// 4
+// (4)
 template<typename BasicJsonType>
 basic_json(const BasicJsonType& val);
 
-// 5
+// (5)
 basic_json(initializer_list_t init,
            bool type_deduction = true,
            value_t manual_type = value_t::array);
 
-// 6
+// (6)
 basic_json(size_type cnt, const basic_json& val);
 
-// 7
+// (7)
 basic_json(iterator first, iterator last);
 basic_json(const_iterator first, const_iterator last);
 
-// 8
+// (8)
 basic_json(const basic_json& other);
 
-// 9
+// (9)
 basic_json(basic_json&& other) noexcept;
 ```
 
 1. Create an empty JSON value with a given type. The value will be default initialized with an empty value which depends
    on the type:
    
-    Value type  | initial value
-    ----------- | -------------
-    null        | `#!json null`
-    boolean     | `#!json false`
-    string      | `#!json ""`
-    number      | `#!json 0`
-    object      | `#!json {}`
-    array       | `#!json []`
-    binary      | empty array
+    | Value type | initial value  |
+    |------------|----------------|
+    | null       | `#!json null`  |
+    | boolean    | `#!json false` |
+    | string     | `#!json ""`    |
+    | number     | `#!json 0`     |
+    | object     | `#!json {}`    |
+    | array      | `#!json []`    |
+    | binary     | empty array    |
+
+    The postcondition of this constructor can be restored by calling [`clear()`](clear.md).
 
 2. Create a `#!json null` JSON value. It either takes a null pointer as parameter (explicitly creating `#!json null`)
    or no parameter (implicitly creating `#!json null`). The passed null pointer itself is not read -- it is only used to
@@ -104,6 +106,9 @@ basic_json(basic_json&& other) noexcept;
     
     - the empty array (`#!json []`): use `array(initializer_list_t)` with an empty initializer list in this case
     - arrays whose elements satisfy rule 2: use `array(initializer_list_t)` with the same initializer list in this case
+   
+    Function [`array()`](array.md) and [`object()`](object.md) force array and object creation from initializer lists,
+    respectively.
         
 6. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is
    created.
@@ -142,6 +147,9 @@ basic_json(basic_json&& other) noexcept;
     - `BasicJsonType` is a `basic_json` type.
     - `BasicJsonType` has different template arguments than `basic_json_t`.
 
+`U`:
+:   `uncvref_t<CompatibleType>`
+
 ## Parameters
 
 `v` (in)
@@ -175,6 +183,22 @@ basic_json(basic_json&& other) noexcept;
 `other` (in)
 :   the JSON value to copy/move
 
+## Exception safety
+
+1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+2. No-throw guarantee: this constructor never throws exceptions.
+3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
+   `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
+   JSON value.
+4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
+   `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
+   JSON value.
+5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
+9. No-throw guarantee: this constructor never throws exceptions.
+
 ## Exceptions
 
 1. /
@@ -193,28 +217,12 @@ basic_json(basic_json&& other) noexcept;
       `[first, last)` is undefined.
     - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if iterators `first`
       and `last` belong to a primitive type (number, boolean, or string), but `first` does not point to the first
-      element any more. In this case, the range `[first, last)` is undefined. See example code below.
+      element anymore. In this case, the range `[first, last)` is undefined. See example code below.
     - Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
       and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
 8. /
 9. The function does not throw exceptions.
 
-## Exception safety
-
-1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-2. No-throw guarantee: this constructor never throws exceptions.
-3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
-   `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
-   JSON value.
-4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
-   `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
-   JSON value.
-5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
-9. No-throw guarantee: this constructor never throws exceptions.
-
 ## Complexity
 
 1. Constant.
@@ -267,9 +275,9 @@ basic_json(basic_json&& other) noexcept;
         - `#!cpp `*this` has the same value as `other` before the call.
         - `other` is a JSON `#!json null` value
 
-## Example
+## Examples
 
-??? example
+??? example "Example: (1) create an empty value with a given type"
 
     The following code shows the constructor for different `value_t` values.
      
@@ -283,7 +291,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__value_t.output"
     ```
 
-??? example
+??? example "Example: (2) create a `#!json null` object"
 
     The following code shows the constructor with and without a null pointer parameter.
      
@@ -297,7 +305,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__nullptr_t.output"
     ```
 
-??? example
+??? example "Example: (3) create a JSON value from compatible types"
 
     The following code shows the constructor with several compatible types.
      
@@ -311,7 +319,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__CompatibleType.output"
     ```
 
-??? example
+??? example "Example: (5) create a container (array or object) from an initializer list"
 
     The example below shows how JSON values are created from initializer lists.
      
@@ -325,7 +333,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__list_init_t.output"
     ```
 
-??? example
+??? example "Example: (6) construct an array with count copies of given value"
 
     The following code shows examples for creating arrays with several copies of a given value.
      
@@ -339,7 +347,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__size_type_basic_json.output"
     ```
 
-??? example
+??? example "Example: (7) construct a JSON container given an iterator range"
 
     The example below shows several ways to create JSON values by specifying a subrange with iterators.
      
@@ -353,7 +361,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__InputIt_InputIt.output"
     ```
 
-??? example
+??? example "Example: (8) copy constructor"
 
     The following code shows an example for the copy constructor.
      
@@ -367,7 +375,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__basic_json.output"
     ```
 
-??? example
+??? example "Example: (9) move constructor"
 
     The code below shows the move constructor explicitly called via `std::move`.
      

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

@@ -1,4 +1,4 @@
-# basic_json::begin
+# <small>nlohmann::basic_json::</small>begin
 
 ```cpp
 iterator begin() noexcept;
@@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::binary
+# <small>nlohmann::basic_json::</small>binary
 
 ```cpp
 // (1)
@@ -45,6 +45,22 @@ standard value ctor, as both JSON arrays and JSON binary arrays are backed with
 JSON binary arrays are a non-standard extension it was decided that it would be best to prevent automatic initialization
 of a binary array type, for backwards compatibility and so it does not happen on accident.
 
+## Examples
+
+??? example
+
+    The following code shows how to create a binary value.
+     
+    ```cpp
+    --8<-- "examples/binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/binary.output"
+    ```
+
 ## Version history
 
 - Added in version 3.8.0.

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

@@ -1,4 +1,4 @@
-# basic_json::binary_t
+# <small>nlohmann::basic_json::</small>binary_t
 
 ```cpp
 using binary_t = byte_container_with_subtype<BinaryType>;
@@ -8,9 +8,10 @@ This type is a type designed to carry binary data that appears in various serial
 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for
 compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
 
-Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint8_t`, which
+Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_t`, which
 is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is
-incompatible with each other, and it is up to the user to translate between them).
+incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType`
+via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.md).
 
 [CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
 > Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
@@ -18,7 +19,7 @@ incompatible with each other, and it is up to the user to translate between them
 
 [MessagePack's documentation on the bin type
 family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:
-> Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
+> Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
 
 [BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to
 represent the generic binary type which has the description:
@@ -62,6 +63,27 @@ type `#!cpp binary_t*` must be dereferenced.
     - If a subtype is given, it is used and added as unsigned 8-bit integer.
     - If no subtype is given, the generic binary subtype 0x00 is used.
 
+## Examples
+
+??? example
+
+    The following code shows that `binary_t` is by default, a typedef to
+    `#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
+     
+    ```cpp
+    --8<-- "examples/binary_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/binary_t.output"
+    ```
+
+## See also
+
+- [byte_container_with_subtype](../byte_container_with_subtype/index.md)
+
 ## Version history
 
 - Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0.

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

@@ -1,4 +1,4 @@
-# basic_json::boolean_t
+# <small>nlohmann::basic_json::</small>boolean_t
 
 ```cpp
 using boolean_t = BooleanType;
@@ -21,6 +21,22 @@ With the default values for `BooleanType` (`#!cpp bool`), the default value for
 
 Boolean values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `boolean_t` is by default, a typedef to `#!cpp bool`.
+     
+    ```cpp
+    --8<-- "examples/boolean_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/boolean_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::cbegin
+# <small>nlohmann::basic_json::</small>cbegin
 
 ```cpp
 const_iterator cbegin() const noexcept;
@@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::cbor_tag_handler_t
+# <small>nlohmann::basic_json::</small>cbor_tag_handler_t
 
 ```cpp
 enum class cbor_tag_handler_t

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

@@ -1,4 +1,4 @@
-# basic_json::cend
+# <small>nlohmann::basic_json::</small>cend
 
 ```cpp
 const_iterator cend() const noexcept;
@@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::clear
+# <small>nlohmann::basic_json::</small>clear
 
 ```cpp
 void clear() noexcept;
@@ -7,15 +7,15 @@ void clear() noexcept;
 Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](basic_json.md) would
 have been called with the current value type from [`type()`](type.md):
 
-Value type  | initial value
------------ | -------------
-null        | `null`
-boolean     | `false`
-string      | `""`
-number      | `0`
-binary      | An empty byte vector
-object      | `{}`
-array       | `[]`
+| Value type | initial value        |
+|------------|----------------------|
+| null       | `null`               |
+| boolean    | `false`              |
+| string     | `""`                 |
+| number     | `0`                  |
+| binary     | An empty byte vector |
+| object     | `{}`                 |
+| array      | `[]`                 |
 
 Has the same effect as calling
 
@@ -35,7 +35,7 @@ Linear in the size of the JSON value.
 
 All iterators, pointers and references related to this container are invalidated.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,12 +1,17 @@
-# basic_json::contains
+# <small>nlohmann::basic_json::</small>contains
 
 ```cpp
+// (1)
 template<typename KeyT>
 bool contains(KeyT && key) const;
+
+// (2)
+bool contains(const json_pointer& ptr) const;
 ```
 
-Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the JSON
-value is not an object, `#!cpp false` is returned.
+1. Check whether an element exists in a JSON object with key equivalent to `key`. If the element is not found or the 
+   JSON value is not an object, `#!cpp false` is returned.
+2. Check whether the given JSON pointer `ptr` can be resolved in the current JSON value.
 
 ## Template parameters
 
@@ -17,27 +22,45 @@ value is not an object, `#!cpp false` is returned.
 
 `key` (in)
 :   key value to check its existence.
-    
+
+`ptr` (in)
+:   JSON pointer to check its existence.
+
 ## Return value
 
-`#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value is
-not an object, `#!cpp false` is returned.
+1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
+   is not an object, `#!cpp false` is returned.
+2. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.
 
 ## Exception safety
 
 Strong exception safety: if an exception occurs, the original value stays intact.
 
+## Exceptions
+
+1. The function does not throw exceptions.
+2. The function can throw the following exceptions:
+    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index begins with
+      `0`.
+    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index was not a
+      number.
+
 ## Complexity
 
 Logarithmic in the size of the JSON object.
 
 ## Notes
 
-This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+1. This method always returns `#!cpp false` when executed on a JSON type that is not an object.
+2. This method can be executed on any JSON value type.
 
-## Example
+!!! info "Postconditions"
 
-??? example
+    If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`.
+
+## Examples
+
+??? example "Example (1) check with key"
 
     The example shows how `contains()` is used.
     
@@ -51,6 +74,21 @@ This method always returns `#!cpp false` when executed on a JSON type that is no
     --8<-- "examples/contains.output"
     ```
 
+??? example "Example (1) check with JSON pointer"
+
+    The example shows how `contains()` is used.
+    
+    ```cpp
+    --8<-- "examples/contains_json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/contains_json_pointer.output"
+    ```
+
 ## Version history
 
-- Added in version 3.6.0.
+1. Added in version 3.6.0.
+2. Added in version 3.7.0.

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

@@ -1,4 +1,4 @@
-# basic_json::count
+# <small>nlohmann::basic_json::</small>count
 
 ```cpp
 template<typename KeyT>
@@ -34,7 +34,7 @@ Logarithmic in the size of the JSON object.
 
 This method always returns `0` when executed on a JSON type that is not an object.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::crbegin
+# <small>nlohmann::basic_json::</small>crbegin
 
 ```cpp
 const_reverse_iterator crbegin() const noexcept;
@@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::rend
+# <small>nlohmann::basic_json::</small>crend
 
 ```cpp
 const_reverse_iterator crend() const noexcept;
@@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::diff
+# <small>nlohmann::basic_json::</small>diff
 
 ```cpp
 static basic_json diff(const basic_json& source,
@@ -33,11 +33,11 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 Linear in the lengths of `source` and `target`.
 
-## Note
+## Notes
 
 Currently, only `remove`, `add`, and `replace` operations are generated.
           
-## Example
+## Examples
 
 ??? example
 
@@ -53,6 +53,10 @@ Currently, only `remove`, `add`, and `replace` operations are generated.
     --8<-- "examples/diff.output"
     ```
 
+## See also
+
+- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
+
 ## Version history
 
 - Added in version 2.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::dump
+# <small>nlohmann::basic_json::</small>dump
 
 ```cpp
 string_t dump(const int indent = -1,
@@ -7,8 +7,9 @@ string_t dump(const int indent = -1,
               const error_handler_t error_handler = error_handler_t::strict) const;
 ```
 
-Serialization function for JSON values. The function tries to mimic Python's `json.dumps()` function, and currently
-supports its `indent` and `ensure_ascii` parameters.
+Serialization function for JSON values. The function tries to mimic Python's
+[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently  supports its `indent`
+and `ensure_ascii` parameters.
     
 ## Parameters
 
@@ -27,7 +28,7 @@ supports its `indent` and `ensure_ascii` parameters.
 :   how to react on decoding errors; there are three possible values (see [`error_handler_t`](error_handler_t.md):
     `strict` (throws and exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
     with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all bytes are copied to the output
-    unchanged).
+    unchanged)).
     
 ## Return value
 
@@ -37,6 +38,11 @@ string containing the serialization of the JSON value
 
 Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded and `error_handler` is set to `strict`
+
 ## Complexity
 
 Linear.
@@ -48,7 +54,7 @@ Binary values are serialized as object containing two keys:
 - "bytes": an array of bytes as integers
 - "subtype": the subtype as integer or `#!json null` if the binary has no subtype
 
-## Example
+## Examples
 
 ??? example
 
@@ -64,3 +70,10 @@ Binary values are serialized as object containing two keys:
     ```json
     --8<-- "examples/dump.output"
     ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Indentation character `indent_char`, option `ensure_ascii` and exceptions added in version 3.0.0.
+- Error handlers added in version 3.4.0.
+- Serialization of binary values added in version 3.8.0.

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

@@ -1,4 +1,4 @@
-# basic_json::emplace
+# <small>nlohmann::basic_json::</small>emplace
 
 ```cpp
 template<class... Args>

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

@@ -1,4 +1,4 @@
-# basic_json::emplace_back
+# <small>nlohmann::basic_json::</small>emplace_back
 
 ```cpp
 template<class... Args>

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

@@ -1,4 +1,4 @@
-# basic_json::empty
+# <small>nlohmann::basic_json::</small>empty
 
 ```cpp
 bool empty() const noexcept;
@@ -10,15 +10,15 @@ Checks if a JSON value has no elements (i.e. whether its [`size()`](size.md) is
 
 The return value depends on the different types and is defined as follows:
 
-Value type  | return value
------------ | -------------
-null        | `#!cpp true`
-boolean     | `#!cpp false`
-string      | `#!cpp false`
-number      | `#!cpp false`
-binary      | `#!cpp false`
-object      | result of function `object_t::empty()`
-array       | result of function `array_t::empty()`
+| Value type | return value                           |
+|------------|----------------------------------------|
+| null       | `#!cpp true`                           |
+| boolean    | `#!cpp false`                          |
+| string     | `#!cpp false`                          |
+| number     | `#!cpp false`                          |
+| binary     | `#!cpp false`                          |
+| object     | result of function `object_t::empty()` |
+| array      | result of function `array_t::empty()`  |
 
 ## Exception safety
 
@@ -44,7 +44,7 @@ bool empty() const noexcept
 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 `#!cpp false` in the case of a string.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::end
+# <small>nlohmann::basic_json::</small>end
 
 ```cpp
 iterator end() noexcept;
@@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::erase
+# <small>nlohmann::basic_json::</small>erase
 
 ```cpp
 // (1)
@@ -17,7 +17,7 @@ void erase(const size_type idx);
 ```
 
 1. Removes an element from a JSON value specified by iterator `pos`. The iterator `pos` must be valid and
-   dereferenceable. Thus the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
+   dereferenceable. Thus, the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for
    `pos`.
    
     If called on a primitive type other than `#!json null`, the resulting JSON value will be `#!json null`.
@@ -58,6 +58,10 @@ void erase(const size_type idx);
    (`key` was not found) or `1` (`key` was found).
 4. /
 
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
 ## Exceptions
 
 1. The function can throw the following exceptions:
@@ -85,10 +89,6 @@ void erase(const size_type idx);
     - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example:
       `"array index 17 is out of range"`
 
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
 ## Complexity
 
 1. The complexity depends on the type:
@@ -107,15 +107,14 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## Notes
 
-1. Invalidates iterators and references at or after the point of the
-   erase, including the `end()` iterator.
+1. Invalidates iterators and references at or after the point of the `erase`, including the `end()` iterator.
 2. /
 3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected.
 4. /
 
-## Example
+## Examples
 
-??? example
+??? example "Example: (1) remove element given an iterator"
 
     The example shows the effect of `erase()` for different JSON types using an iterator.
     
@@ -129,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/erase__IteratorType.output"
     ```
 
-??? example
+??? example "Example: (2) remove elements given an iterator range"
 
     The example shows the effect of `erase()` for different JSON types using an iterator range.
     
@@ -143,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/erase__IteratorType_IteratorType.output"
     ```
 
-??? example
+??? example "Example: (3) remove element from a JSON object given a key"
 
     The example shows the effect of `erase()` for different JSON types using an object key.
     
@@ -157,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/erase__key_type.output"
     ```
 
-??? example
+??? example "Example: (4) remove element from a JSON array given an index"
 
     The example shows the effect of `erase()` using an array index.
     

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

@@ -1,4 +1,4 @@
-# basic_json::error_handler_t
+# <small>nlohmann::basic_json::</small>error_handler_t
 
 ```cpp
 enum class error_handler_t {

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

@@ -1,4 +1,4 @@
-# basic_json::exception
+# <small>nlohmann::basic_json::</small>exception
 
 ```cpp
 class exception : public std::exception;
@@ -44,7 +44,13 @@ Subclasses:
 
 - **id** - the id of the exception
 
-## Example
+## Notes
+
+To have nothrow-copy-constructible exceptions, we internally use `std::runtime_error` which can cope with
+arbitrary-length error messages. Intermediate strings are built with static functions and then passed to the actual
+constructor.
+
+## Examples
 
 ??? example
 
@@ -60,6 +66,10 @@ Subclasses:
     --8<-- "examples/exception.output"
     ```
 
+## See also
+
+[List of exceptions](127.0.0.1:8000/home/exceptions/)
+
 ## Version history
 
 - Since version 3.0.0.

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

@@ -1,11 +1,11 @@
-# basic_json::find
+# <small>nlohmann::basic_json::</small>find
 
 ```cpp
 template<typename KeyT>
 iterator find(KeyT&& key);
 
 template<typename KeyT>
-const_iterator find(KeyT&& key) const
+const_iterator find(KeyT&& key) const;
 ```
 
 Finds an element in a JSON object with key equivalent to `key`. If the element is not found or the JSON value is not an
@@ -38,7 +38,7 @@ Logarithmic in the size of the JSON object.
 
 This method always returns `end()` when executed on a JSON type that is not an object.
 
-## Example
+## Examples
 
 ??? example
 
@@ -54,6 +54,10 @@ This method always returns `end()` when executed on a JSON type that is not an o
     --8<-- "examples/find__key_type.output"
     ```
 
+## See also
+
+- [contains](contains.md) checks whether a key exists
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::flatten
+# <small>nlohmann::basic_json::</small>flatten
 
 ```cpp
 basic_json flatten() const;
@@ -25,7 +25,7 @@ Linear in the size the JSON value.
 Empty objects and arrays are flattened to `#!json null` and will not be reconstructed correctly by the
 [`unflatten()`](unflatten.md) function.
 
-## Example
+## Examples
 
 ??? example
 
@@ -41,6 +41,10 @@ Empty objects and arrays are flattened to `#!json null` and will not be reconstr
     --8<-- "examples/flatten.output"
     ```
 
+## See also
+
+- [unflatten](unflatten.md) the reverse function
+
 ## Version history
 
 - Added in version 2.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::from_bson
+# <small>nlohmann::basic_json::</small>from_bson
 
 ```cpp
 // (1)
@@ -18,6 +18,8 @@ Deserializes a given input to a JSON value using the BSON (Binary JSON) serializ
 1. Reads from a compatible input.
 2. Reads from an iterator range.
 
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
+
 ## Template parameters
 
 `InputType`
@@ -58,11 +60,16 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+
+Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
+encountered.
+
 ## Complexity
 
 Linear in the size of the input.
 
-## Example
+## Examples
 
 ??? example
 
@@ -78,6 +85,26 @@ Linear in the size of the input.
     --8<-- "examples/from_bson.output"
     ```
 
+## See also
+
+- [BSON specification](http://bsonspec.org/spec.html)
+- [to_bson](to_bson.md) for the analogous serialization
+- [from_cbor](from_cbor.md) for the related CBOR format
+- [from_msgpack](from_msgpack.md) for the related MessagePack format
+- [from_ubjson](from_ubjson.md) for the related UBJSON format
+
 ## Version history
 
 - Added in version 3.4.0.
+
+!!! warning "Deprecation"
+
+    - Overload (2) replaces calls to `from_bson` with a pointer and a length as first two parameters, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_bson(ptr, len, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
+    - Overload (2) replaces calls to `from_bson` with a pair of iterators as their first parameter, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_bson({ptr, ptr+len}, ...);` with `#!cpp from_bson(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::from_cbor
+# <small>nlohmann::basic_json::</small>from_cbor
 
 ```cpp
 // (1)
@@ -21,6 +21,8 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object
 1. Reads from a compatible input.
 2. Reads from an iterator range.
 
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/cbor.md).
+
 ## Template parameters
 
 `InputType`
@@ -65,11 +67,20 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+ 
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from CBOR were
+  used in the given input or if the input is not valid CBOR
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
+  but not found
+
 ## Complexity
 
 Linear in the size of the input.
 
-## Example
+## Examples
 
 ??? example
 
@@ -92,3 +103,15 @@ Linear in the size of the input.
 - Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
 - Added `allow_exceptions` parameter in version 3.2.0.
 - Added `tag_handler` parameter in version 3.9.0.
+
+!!! warning "Deprecation"
+
+    - Overload (2) replaces calls to `from_cbor` with a pointer and a length as first two parameters, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_cbor(ptr, len, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`.
+    - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_cbor({ptr, ptr+len}, ...);` with `#!cpp from_cbor(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::from_msgpack
+# <small>nlohmann::basic_json::</small>from_msgpack
 
 ```cpp
 // (1)
@@ -18,6 +18,8 @@ Deserializes a given input to a JSON value using the MessagePack serialization f
 1. Reads from a compatible input.
 2. Reads from an iterator range.
 
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/messagepack.md).
+
 ## Template parameters
 
 `InputType`
@@ -58,11 +60,20 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of  file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from
+  MessagePack were used in the given input or if the input is not valid MessagePack
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key,
+  but not found
+
 ## Complexity
 
 Linear in the size of the input.
 
-## Example
+## Examples
 
 ??? example
 
@@ -84,3 +95,15 @@ Linear in the size of the input.
 - Parameter `start_index` since version 2.1.1.
 - Changed to consume input adapters, removed `start_index` parameter, and added `strict` parameter in version 3.0.0.
 - Added `allow_exceptions` parameter in version 3.2.0.
+
+!!! warning "Deprecation"
+
+    - Overload (2) replaces calls to `from_msgpack` with a pointer and a length as first two parameters, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_msgpack(ptr, len, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
+    - Overload (2) replaces calls to `from_cbor` with a pair of iterators as their first parameter, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_msgpack({ptr, ptr+len}, ...);` with `#!cpp from_msgpack(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::from_ubjson
+# <small>nlohmann::basic_json::</small>from_ubjson
 
 ```cpp
 // (1)
@@ -18,6 +18,8 @@ Deserializes a given input to a JSON value using the UBJSON (Universal Binary JS
 1. Reads from a compatible input.
 2. Reads from an iterator range.
 
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/ubjson.md).
+
 ## Template parameters
 
 `InputType`
@@ -58,11 +60,19 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+
+- Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or
+  the end of file was not reached when `strict` was set to true
+- Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed 
+  successfully
+
 ## Complexity
 
 Linear in the size of the input.
 
-## Example
+## Examples
 
 ??? example
 
@@ -82,3 +92,15 @@ Linear in the size of the input.
 
 - Added in version 3.1.0.
 - Added `allow_exceptions` parameter in version 3.2.0.
+
+!!! warning "Deprecation"
+
+    - Overload (2) replaces calls to `from_ubjson` with a pointer and a length as first two parameters, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_ubjson(ptr, len, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
+    - Overload (2) replaces calls to `from_ubjson` with a pair of iterators as their first parameter, which has been
+      deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_ubjson({ptr, ptr+len}, ...);` with `#!cpp from_ubjson(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::front
+# <small>nlohmann::basic_json::</small>front
 
 ```cpp
 reference front();
@@ -13,26 +13,26 @@ Returns a reference to the first element in the container. For a JSON container
 In case of a structured type (array or object), a reference to the first element is returned. In case of number, string,
 boolean, or binary values, a reference to the value is returned.
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
 ## Exceptions
 
 If the JSON value is `#!json null`, exception
 [`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown.
 
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
 ## Complexity
 
 Constant.
 
-## Note
+## Notes
 
 !!! danger
 
     Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**!
 
-## Example
+## Examples
 
 ??? example
 
@@ -48,6 +48,10 @@ Constant.
     --8<-- "examples/front.output"
     ```
 
+## See also
+
+- [back](back.md) to access the last element
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::get
+# <small>nlohmann::basic_json::</small>get
 
 ```cpp
 // (1)
@@ -31,7 +31,7 @@ constexpr const PointerType get_ptr() const noexcept;
     return ret;
     ```
 
-    This overloads is chosen if:
+    This overload is chosen if:
     
     - `ValueType` is not `basic_json`,
     - `json_serializer<ValueType>` has a `from_json()` method of the form
@@ -48,7 +48,7 @@ constexpr const PointerType get_ptr() const noexcept;
     return JSONSerializer<ValueTypeCV>::from_json(*this);
     ``` 
    
-    This overloads is chosen if:
+    This overload is chosen if:
     
     - `ValueType` is not `basic_json` and
     - `json_serializer<ValueType>` has a `from_json()` method of the form
@@ -94,7 +94,7 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
 
     Writing data to the pointee (overload 3) of the result yields an undefined state.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::get_allocator
+# <small>nlohmann::basic_json::</small>get_allocator
 
 ```cpp
 static allocator_type get_allocator();
@@ -13,3 +13,7 @@ associated allocator
 ## Version history
 
 - Unknown.
+
+!!! note
+
+    This documentation page is a stub.

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

@@ -1,4 +1,4 @@
-# basic_json::get_binary
+# <small>nlohmann::basic_json::</small>get_binary
 
 ```cpp
 binary_t& get_binary();
@@ -24,6 +24,22 @@ Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) i
 
 Constant.
 
+## Examples
+
+??? example
+
+    The following code shows how to query a binary value.
+     
+    ```cpp
+    --8<-- "examples/get_binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_binary.output"
+    ```
+
 ## Version history
 
 - Added in version 3.8.0.

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

@@ -1,8 +1,8 @@
-# basic_json::get_ptr
+# <small>nlohmann::basic_json::</small>get_ptr
 
 ```cpp
 template<typename PointerType>
-PointerType get_ptr();
+PointerType get_ptr() noexcept;
 
 template<typename PointerType>
 constexpr const PointerType get_ptr() const noexcept;
@@ -10,7 +10,7 @@ constexpr const PointerType get_ptr() const noexcept;
 
 Implicit pointer access to the internally stored JSON value. No copies are made.
 
-## Template arguments
+## Template parameters
 
 `PointerType`
 :   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
@@ -25,7 +25,7 @@ otherwise
 
 ## Exception safety
 
-Strong exception safety: if an exception occurs, the original value stays intact.
+No-throw guarantee: this function never throws exceptions.
 
 ## Complexity
 
@@ -37,7 +37,7 @@ Constant.
 
     Writing data to the pointee of the result yields an undefined state.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::get_ref
+# <small>nlohmann::basic_json::</small>get_ref
 
 ```cpp
 template<typename ReferenceType>
@@ -10,7 +10,7 @@ const ReferenceType get_ref() const;
 
 Implicit reference access to the internally stored JSON value. No copies are made.
 
-## Template arguments
+## Template parameters
 
 `ReferenceType`
 :   reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
@@ -42,7 +42,7 @@ Constant.
 
     Writing data to the referee of the result yields an undefined state.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,10 +1,10 @@
-# basic_json::get_to
+# <small>nlohmann::basic_json::</small>get_to
 
 ```cpp
 template<typename ValueType>
 ValueType& get_to(ValueType& v) const noexcept(
     noexcept(JSONSerializer<ValueType>::from_json(
-        std::declval<const basic_json_t&>(), v)))
+        std::declval<const basic_json_t&>(), v)));
 ```
 
 Explicit type conversion between the JSON value and a compatible value. The value is filled into the input parameter by
@@ -16,7 +16,7 @@ ValueType v;
 JSONSerializer<ValueType>::from_json(*this, v);
 ```
 
-This overloads is chosen if:
+This overload is chosen if:
 
 - `ValueType` is not `basic_json`,
 - `json_serializer<ValueType>` has a `from_json()` method of the form `void from_json(const basic_json&, ValueType&)`
@@ -34,7 +34,7 @@ the input parameter, allowing chaining calls
 
 Depends on what `json_serializer<ValueType>` `from_json()` method throws
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,6 +1,6 @@
-# basic_json
+# <small>nlohmann::</small>basic_json
 
-Defined in header `<json.hpp>`
+<small>Defined in header `<nlohmann/json.hpp>`</small>
 
 ```cpp
 template<
@@ -18,41 +18,83 @@ template<
 class basic_json;
 ```
 
+## Template parameters
+
+| Template parameter   | Description                                                               | Derived type                                |
+|----------------------|---------------------------------------------------------------------------|---------------------------------------------|
+| `ObjectType`         | type for JSON objects                                                     | [`object_t`](object_t.md)                   |
+| `ArrayType`          | type for JSON arrays                                                      | [`array_t`](array_t.md)                     |
+| `StringType`         | type for JSON strings and object keys                                     | [`string_t`](string_t.md)                   |
+| `BooleanType`        | type for JSON booleans                                                    | [`boolean_t`](boolean_t.md)                 |
+| `NumberIntegerType`  | type for JSON integer numbers                                             | [`number_integer_t`](number_integer_t.md)   |
+| `NumberUnsignedType` | type for JSON unsigned integer numbers                                    | [`number_unsigned_t`](number_unsigned_t.md) |
+| `NumberFloatType`    | type for JSON floating-point numbers                                      | [`number_float_t`](number_float_t.md)       |
+| `AllocatorType`      | type of the allocator to use                                              |                                             |
+| `JSONSerializer`     | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md)     |
+| `BinaryType`         | type for binary arrays                                                    | [`binary_t`](binary_t.md)                   |
+
 ## Specializations
 
 - [**json**](../json.md) - default specialization
 - [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
 
-## Template parameters
-
-| Template parameter   | Description | Derived type |
-| -------------------- | ----------- | ------------ |
-| `ObjectType`         | type for JSON objects | [`object_t`](object_t.md) |
-| `ArrayType`          | type for JSON arrays | [`array_t`](array_t.md) |
-| `StringType`         | type for JSON strings and object keys | [`string_t`](string_t.md) |
-| `BooleanType`        | type for JSON booleans | [`boolean_t`](boolean_t.md) |
-| `NumberIntegerType`  | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
-| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
-| `NumberFloatType`    | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
-| `AllocatorType`      | type of the allocator to use | |
-| `JSONSerializer`     | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
-| `BinaryType`         | type for binary arrays | [`binary_t`](binary_t.md) |
-
 ## Iterator invalidation
 
 Todo
 
+## Requirements
+
+The class satisfies the following concept requirements:
+
+### Basic
+
+- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default
+  constructed. The result will be a JSON null value.
+- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed
+  from an rvalue argument.
+- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be
+  copy-constructed from an lvalue expression.
+- [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): A JSON value van be assigned from an
+  rvalue argument.
+- [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): A JSON value can be copy-assigned from
+  an lvalue expression.
+- [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): JSON values can be destructed.
+
+### Layout
+
+- [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): JSON values have
+  [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): All non-static data
+  members are private and standard layout types, the class has no virtual functions or (virtual) base classes.
+
+### Library-wide
+
+- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with
+  `==`, see [`operator==`](operator_eq.md).
+- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with
+  `<`, see [`operator<`](operator_le).
+- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with
+  any lvalue or rvalue of other compatible types, using unqualified function `swap`.
+- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against
+  `std::nullptr_t` objects which are used to model the `null` value.
+
+### Container
+
+- [Container](https://en.cppreference.com/w/cpp/named_req/Container): JSON values can be used like STL containers and
+  provide iterator access.
+- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer): JSON values can be used like
+  STL containers and provide reverse iterator access.
+
 ## Member types
 
-- [**adl_serializer**](../adl_serializer.md) - the default serializer
+- [**adl_serializer**](../adl_serializer) - the default serializer
 - [**value_t**](value_t.md) - the JSON type enumeration
-- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
+- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
 - [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
 - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
 - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
-- initializer_list_t
+- **initializer_list_t** - type for initializer lists of `basic_json` values
 - [**input_format_t**](input_format_t.md) - type to choose the format to parse
-- json_sax_t
+- [**json_sax_t**](../json_sax/index.md) - type for SAX events
 
 ### Exceptions
 
@@ -65,21 +107,21 @@ Todo
 
 ### Container types
 
-| Type                     | Definition |
-| ------------------------ | ---------- |
-| `value_type`             | `#!cpp basic_json` |
-| `reference`              | `#!cpp value_type&` |
-| `const_reference`        | `#!cpp const value_type&` |
-| `difference_type`        | `#!cpp std::ptrdiff_t` |
-| `size_type`              | `#!cpp std::size_t` |
-| `allocator_type`         | `#!cpp AllocatorType<basic_json>` |
-| `pointer`                | `#!cpp std::allocator_traits<allocator_type>::pointer` |
-| `const_pointer`          | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
-| `iterator`               | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
+| Type                     | Definition                                                                                                |
+|--------------------------|-----------------------------------------------------------------------------------------------------------|
+| `value_type`             | `#!cpp basic_json`                                                                                        |
+| `reference`              | `#!cpp value_type&`                                                                                       |
+| `const_reference`        | `#!cpp const value_type&`                                                                                 |
+| `difference_type`        | `#!cpp std::ptrdiff_t`                                                                                    |
+| `size_type`              | `#!cpp std::size_t`                                                                                       |
+| `allocator_type`         | `#!cpp AllocatorType<basic_json>`                                                                         |
+| `pointer`                | `#!cpp std::allocator_traits<allocator_type>::pointer`                                                    |
+| `const_pointer`          | `#!cpp std::allocator_traits<allocator_type>::const_pointer`                                              |
+| `iterator`               | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator)          |
 | `const_iterator`         | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
-| `reverse_iterator`       | reverse iterator, derived from `iterator` |
-| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` |
-| `iteration_proxy`        | helper type for [`items`](items.md) function |
+| `reverse_iterator`       | reverse iterator, derived from `iterator`                                                                 |
+| `const_reverse_iterator` | reverse iterator, derived from `const_iterator`                                                           |
+| `iteration_proxy`        | helper type for [`items`](items.md) function                                                              |
 
 ### JSON value data types
 
@@ -103,9 +145,9 @@ Todo
 - [(constructor)](basic_json.md)
 - [(destructor)](~basic_json.md)
 - [**operator=**](operator=.md) - copy assignment
-- [**array**](array_t.md) (static) - explicitly create an array
-- [**binary**](binary.md) (static) - explicitly create a binary array
-- [**object**](object_t.md) (static) - explicitly create an object
+- [**array**](array_t.md) (_static_) - explicitly create an array
+- [**binary**](binary.md) (_static_) - explicitly create a binary array
+- [**object**](object_t.md) (_static_) - explicitly create an object
 
 ### Object inspection
 
@@ -183,7 +225,7 @@ Access to the JSON value
 - [**erase**](erase.md) - remove elements
 - [**insert**](insert.md) - inserts elements
 - [**update**](update.md) - updates a JSON object from another object, overwriting existing keys 
-- swap - exchanges the values
+- [**swap**](swap.md) - exchanges the values
 
 ### Lexicographical comparison operators
 
@@ -197,13 +239,12 @@ Access to the JSON value
 ### Serialization / Dumping
 
 - [**dump**](dump.md) - serialization
-- to_string - user-defined to_string function for JSON values
 
 ### Deserialization / Parsing
 
-- [**parse**](parse.md) (static) - deserialize from a compatible input
-- [**accept**](accept.md) (static) - check if the input is valid JSON
-- [**sax_parse**](sax_parse.md) (static) - generate SAX events
+- [**parse**](parse.md) (_static_) - deserialize from a compatible input
+- [**accept**](accept.md) (_static_) - check if the input is valid JSON
+- [**sax_parse**](sax_parse.md) (_static_) - generate SAX events
 
 ### JSON Pointer functions
 
@@ -213,7 +254,7 @@ Access to the JSON value
 ### JSON Patch functions
 
 - [**patch**](patch.md) - applies a JSON patch
-- [**diff**](diff.md) (static) - creates a diff as a JSON patch
+- [**diff**](diff.md) (_static_) - creates a diff as a JSON patch
 
 ### JSON Merge Patch functions
 
@@ -226,19 +267,20 @@ Access to the JSON value
 
 ### Binary formats
 
-- [**from_bson**](from_bson.md) (static) - create a JSON value from an input in BSON format
-- [**from_cbor**](from_cbor.md) (static) - create a JSON value from an input in CBOR format
-- [**from_msgpack**](from_msgpack.md) (static) - create a JSON value from an input in MessagePack format
-- [**from_ubjson**](from_ubjson.md) (static) - create a JSON value from an input in UBJSON format
-- [**to_bson**](to_bson.md) (static) - create a BSON serialization of a given JSON value
-- [**to_cbor**](to_cbor.md) (static) - create a CBOR serialization of a given JSON value
-- [**to_msgpack**](to_msgpack.md) (static) - create a MessagePack serialization of a given JSON value
-- [**to_ubjson**](to_ubjson.md) (static) - create a UBJSON serialization of a given JSON value
+- [**from_bson**](from_bson.md) (_static_) - create a JSON value from an input in BSON format
+- [**from_cbor**](from_cbor.md) (_static_) - create a JSON value from an input in CBOR format
+- [**from_msgpack**](from_msgpack.md) (_static_) - create a JSON value from an input in MessagePack format
+- [**from_ubjson**](from_ubjson.md) (_static_) - create a JSON value from an input in UBJSON format
+- [**to_bson**](to_bson.md) (_static_) - create a BSON serialization of a given JSON value
+- [**to_cbor**](to_cbor.md) (_static_) - create a CBOR serialization of a given JSON value
+- [**to_msgpack**](to_msgpack.md) (_static_) - create a MessagePack serialization of a given JSON value
+- [**to_ubjson**](to_ubjson.md) (_static_) - create a UBJSON serialization of a given JSON value
 
 ## Non-member functions
 
-- operator<<(std::ostream&) - serialize to stream
-- operator>>(std::istream&) - deserialize from stream
+- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
+- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream
+- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values
 
 ## Literals
 
@@ -247,6 +289,29 @@ Access to the JSON value
 
 ## Helper classes
 
-- std::hash<nlohmann::json\>
-- std::less<nlohmann::value_t\>
-- std::swap<nlohmann::json\>
+- [**std::hash&lt;basic_json&gt;**](std_hash.md) - return a hash value for a JSON object
+- [**std::swap&lt;basic_json&gt;**](std_swap.md) - exchanges the values of two JSON objects
+
+## Example
+
+??? example
+
+    The example shows how the library is used.
+    
+    ```cpp
+    --8<-- "examples/README.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/README.output"
+    ```
+
+## See also
+
+- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)
+
+## Version history
+
+- Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::input_format_t
+# <small>nlohmann::basic_json::</small>input_format_t
 
 ```cpp
 enum class input_format_t {
@@ -25,7 +25,7 @@ ubjson
 :   UBJSON (Universal Binary JSON)
 
 bson
-:   BSON (Bin­ary JSON)
+:   BSON (Binary JSON)
 
 ## Version history
 

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

@@ -1,4 +1,4 @@
-# basic_json::insert
+# <small>nlohmann::basic_json::</small>insert
 
 ```cpp
 // (1)
@@ -18,11 +18,11 @@ iterator insert(const_iterator pos, initializer_list_t ilist);
 void insert(const_iterator first, const_iterator last);
 ```
 
-1. Inserts element `val` to array before iterator `pos`.
-2. Inserts `cnt` copies of `val` to array before iterator `pos`.
-3. Inserts elements from range `[first, last)` to array before iterator `pos`.
-4. Inserts elements from initializer list `ilist` to array before iterator `pos`.
-5. Inserts elements from range `[first, last)` to object.
+1. Inserts element `val` into array before iterator `pos`.
+2. Inserts `cnt` copies of `val` into array before iterator `pos`.
+3. Inserts elements from range `[first, last)` into array before iterator `pos`.
+4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
+5. Inserts elements from range `[first, last)` into object.
 
 ## Parameters
 
@@ -52,6 +52,10 @@ void insert(const_iterator first, const_iterator last);
 4. iterator pointing to the first element inserted, or `pos` if `ilist` is empty
 5. /
 
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
 ## Exceptions
 
 1. The function can throw the following exceptions:
@@ -86,10 +90,6 @@ void insert(const_iterator first, const_iterator last);
     - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last`
       do not belong to the same JSON value; example: `"iterators do not fit"`
 
-## Exception safety
-
-Strong exception safety: if an exception occurs, the original value stays intact.
-
 ## Complexity
 
 1. Constant plus linear in the distance between `pos` and end of the container.
@@ -98,9 +98,9 @@ Strong exception safety: if an exception occurs, the original value stays intact
 4. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container.
 5. Logarithmic: `O(N*log(size() + N))`, where `N` is the number of elements to insert.
 
-## Example
+## Examples
 
-??? example
+??? example "Example (1): insert element into array"
 
     The example shows how `insert()` is used.
     
@@ -114,7 +114,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/insert.output"
     ```
 
-??? example
+??? example "Example (2): insert copies of element into array"
 
     The example shows how `insert()` is used.
     
@@ -128,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/insert__count.output"
     ```
 
-??? example
+??? example "Example (3): insert range of elements into array"
 
     The example shows how `insert()` is used.
     
@@ -142,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/insert__range.output"
     ```
 
-??? example
+??? example "Example (4): insert elements from initializer list into array"
 
     The example shows how `insert()` is used.
     
@@ -156,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/insert__ilist.output"
     ```
 
-??? example
+??? example "Example (5): insert range of elements into object"
 
     The example shows how `insert()` is used.
     

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

@@ -1,4 +1,4 @@
-# basic_json::invalid_iterator
+# <small>nlohmann::basic_json::</small>invalid_iterator
 
 ```cpp
 class invalid_iterator : public exception;
@@ -6,7 +6,7 @@ class invalid_iterator : public exception;
 
 This exception is thrown if iterators passed to a library function do not match the expected semantics.
 
-Exceptions have ids 2xx.
+Exceptions have ids 2xx (see [list of iterator errors](../../home/exceptions.md#iterator-errors)).
 
 ```plantuml
 std::exception <|-- basic_json::exception
@@ -38,7 +38,7 @@ class basic_json::invalid_iterator #FFFF00 {}
 
 - **id** - the id of the exception
 
-## Example
+## Examples
 
 ??? example
 
@@ -54,6 +54,14 @@ class basic_json::invalid_iterator #FFFF00 {}
     --8<-- "examples/invalid_iterator.output"
     ```
 
+## See also
+
+- [List of iterator errors](../../home/exceptions.md#iterator-errors)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
 ## Version history
 
 - Since version 3.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::is_array
+# <small>nlohmann::basic_json::</small>is_array
 
 ```cpp
 constexpr bool is_array() const noexcept;
@@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_binary
+# <small>nlohmann::basic_json::</small>is_binary
 
 ```cpp
 constexpr bool is_binary() const noexcept;
@@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_boolean
+# <small>nlohmann::basic_json::</small>is_boolean
 
 ```cpp
 constexpr bool is_boolean() const noexcept;
@@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_discarded
+# <small>nlohmann::basic_json::</small>is_discarded
 
 ```cpp
 constexpr bool is_discarded() const noexcept;
@@ -51,7 +51,7 @@ Constant.
 This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
 during parsing, but will be removed when inside a structured value or replaced by null in other cases.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_null
+# <small>nlohmann::basic_json::</small>is_null
 
 ```cpp
 constexpr bool is_null() const noexcept;
@@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_number
+# <small>nlohmann::basic_json::</small>is_number
 
 ```cpp
 constexpr bool is_number() const noexcept;
@@ -28,7 +28,7 @@ constexpr bool is_number() const noexcept
 }
 ```
 
-## Example
+## Examples
 
 ??? example
 
@@ -44,6 +44,12 @@ constexpr bool is_number() const noexcept
     --8<-- "examples/is_number.output"
     ```
 
+## See also
+
+- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
+- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
+- [is_number_float()](is_number_float.md) check if value is a floating-point number
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::is_number_float
+# <small>nlohmann::basic_json::</small>is_number_float
 
 ```cpp
 constexpr bool is_number_float() const noexcept;
@@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 
@@ -35,6 +35,12 @@ Constant.
     --8<-- "examples/is_number_float.output"
     ```
 
+## See also
+
+- [is_number()](is_number.md) check if value is a number
+- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
+- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::is_number_integer
+# <small>nlohmann::basic_json::</small>is_number_integer
 
 ```cpp
 constexpr bool is_number_integer() const noexcept;
@@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 
@@ -35,6 +35,12 @@ Constant.
     --8<-- "examples/is_number_integer.output"
     ```
 
+## See also
+
+- [is_number()](is_number.md) check if value is a number
+- [is_number_unsigned()](is_number_unsigned.md) check if value is an unsigned integer number
+- [is_number_float()](is_number_float.md) check if value is a floating-point number
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::is_number_unsigned
+# <small>nlohmann::basic_json::</small>is_number_unsigned
 
 ```cpp
 constexpr bool is_number_unsigned() const noexcept;
@@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 
@@ -35,6 +35,12 @@ Constant.
     --8<-- "examples/is_number_unsigned.output"
     ```
 
+## See also
+
+- [is_number()](is_number.md) check if value is a number
+- [is_number_integer()](is_number_integer.md) check if value is an integer or unsigned integer number
+- [is_number_float()](is_number_float.md) check if value is a floating-point number
+
 ## Version history
 
 - Added in version 2.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::is_object
+# <small>nlohmann::basic_json::</small>is_object
 
 ```cpp
 constexpr bool is_object() const noexcept;
@@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_primitive
+# <small>nlohmann::basic_json::</small>is_primitive
 
 ```cpp
 constexpr bool is_primitive() const noexcept;
@@ -38,7 +38,7 @@ The term *primitive* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
 This library extends primitive types to binary types, because binary types are  roughly comparable to strings. Hence,
 `is_primitive()` returns `#!cpp true` for binary values.
 
-## Example
+## Examples
 
 ??? example
 
@@ -54,6 +54,15 @@ This library extends primitive types to binary types, because binary types are
     --8<-- "examples/is_primitive.output"
     ```
 
+## See also
+
+- [is_structured()](is_structured.md) returns whether JSON value is structured
+- [is_null()](is_null.md) returns whether JSON value is `null`
+- [is_string()](is_string.md) returns whether JSON value is a string
+- [is_boolean()](is_boolean.md) returns whether JSON value is a boolean
+- [is_number()](is_number.md) returns whether JSON value is a number
+- [is_binary()](is_binary.md) returns whether JSON value is a binary array
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::is_string
+# <small>nlohmann::basic_json::</small>is_string
 
 ```cpp
 constexpr bool is_string() const noexcept;
@@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::is_structured
+# <small>nlohmann::basic_json::</small>is_structured
 
 ```cpp
 constexpr bool is_structured() const noexcept;
@@ -18,6 +18,15 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
+## Possible implementation
+
+```cpp
+constexpr bool is_primitive() const noexcept
+{
+    return is_array() || is_object();
+}
+```
+
 ## Notes
 
 The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259):
@@ -27,7 +36,7 @@ The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259)
 
 Note that though strings are containers in C++, they are treated as primitive values in JSON.
 
-## Example
+## Examples
 
 ??? example
 
@@ -43,6 +52,12 @@ Note that though strings are containers in C++, they are treated as primitive va
     --8<-- "examples/is_structured.output"
     ```
 
+## See also
+
+- [is_primitive()](is_primitive.md) returns whether JSON value is primitive
+- [is_array()](is_array.md) returns whether value is an array
+- [is_object()](is_object.md) returns whether value is an object
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,11 +1,11 @@
-# basic_json::items
+# <small>nlohmann::basic_json::</small>items
 
 ```cpp
 iteration_proxy<iterator> items() noexcept;
 iteration_proxy<const_iterator> items() const noexcept;
 ```
 
-This function allows to access `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
+This function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a
 reference to the JSON values is returned, so there is no access to the underlying iterator.
 
 For loop without `items()` function:
@@ -36,7 +36,7 @@ for (auto& el : j_object.items())
 }
 ```
 
-The `items()` function also allows to use
+The `items()` function also allows using
 [structured bindings](https://en.cppreference.com/w/cpp/language/structured_binding) (C++17):
 
 ```cpp
@@ -68,7 +68,7 @@ When iterating over an array, `key()` will return the index of the element as st
     Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
     <https://github.com/nlohmann/json/issues/2040> for more information.
 
-## Example
+## Examples
 
 ??? example
 
@@ -86,11 +86,15 @@ When iterating over an array, `key()` will return the index of the element as st
 
 ## Version history
 
-- Added in version 3.0.0.
+- Added `iterator_wrapper` in version 3.0.0.
+- Added `items` and deprecated `iterator_wrapper` in version 3.1.0.
 - Added structured binding support in version 3.5.0.
 
-!!! note
+!!! warning "Deprecation"
 
     This function replaces the static function `iterator_wrapper` which was introduced in version 1.0.0, but has been
     deprecated in version 3.1.0. Function `iterator_wrapper` will be removed in version 4.0.0. Please replace all
     occurrences of `#!cpp iterator_wrapper(j)` with `#!cpp j.items()`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::json_serializer
+# <small>nlohmann::basic_json::</small>json_serializer
 
 ```cpp
 template<typename T, typename SFINAE>
@@ -17,7 +17,7 @@ using json_serializer = JSONSerializer<T, SFINAE>;
 
 #### Default type
 
-The default values for `json_serializer` is [`adl_serializer`](../adl_serializer.md).
+The default values for `json_serializer` is [`adl_serializer`](../adl_serializer).
 
 ## Version history
 

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

@@ -1,4 +1,4 @@
-# basic_json::max_size
+# <small>nlohmann::basic_json::</small>max_size
 
 ```cpp
 size_type max_size() const noexcept;
@@ -11,15 +11,15 @@ i.e. `std::distance(begin(), end())` for the JSON value.
 
 The return value depends on the different types and is defined as follows:
 
-Value type  | return value
------------ | -------------
-null        | `0` (same as [`size()`](size.md))
-boolean     | `1` (same as [`size()`](size.md))
-string      | `1` (same as [`size()`](size.md))
-number      | `1` (same as [`size()`](size.md))
-binary      | `1` (same as [`size()`](size.md))
-object      | result of function `object_t::max_size()`
-array       | result of function `array_t::max_size()`
+| Value type | return value                              |
+|------------|-------------------------------------------|
+| null       | `0` (same as [`size()`](size.md))         |
+| boolean    | `1` (same as [`size()`](size.md))         |
+| string     | `1` (same as [`size()`](size.md))         |
+| number     | `1` (same as [`size()`](size.md))         |
+| binary     | `1` (same as [`size()`](size.md))         |
+| object     | result of function `object_t::max_size()` |
+| array      | result of function `array_t::max_size()`  |
 
 ## Exception safety
 
@@ -36,7 +36,7 @@ constant complexity.
 This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of
 string elements the JSON value can store which is `1`.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::merge_patch
+# <small>nlohmann::basic_json::</small>merge_patch
 
 ```cpp
 void merge_patch(const basic_json& apply_patch);
@@ -37,7 +37,7 @@ Thereby, `Target` is the current object; that is, the patch is applied to the cu
 
 Linear in the lengths of `apply_patch`.
 
-## Example
+## Examples
 
 ??? example
 
@@ -53,6 +53,11 @@ Linear in the lengths of `apply_patch`.
     --8<-- "examples/merge_patch.output"
     ```
 
+## See also
+
+- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
+- [patch](patch.md) apply a JSON patch
+
 ## Version history
 
 - Added in version 3.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::meta
+# <small>nlohmann::basic_json::</small>meta
 
 ```cpp
 static basic_json meta();
@@ -11,14 +11,14 @@ the platform and compiler.
 
 JSON object holding version information
 
-key         | description
------------ | ---------------
-`compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
-`copyright` | The copyright line for the library as string.
-`name`      | The name of the library as string.
-`platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
-`url`       | The URL of the project as string.
-`version`   | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
+| key         | description                                                                                                                                                                                                                                                                    |
+|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). |
+| `copyright` | The copyright line for the library as string.                                                                                                                                                                                                                                  |
+| `name`      | The name of the library as string.                                                                                                                                                                                                                                             |
+| `platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.                                                                                                                                                                             |
+| `url`       | The URL of the project as string.                                                                                                                                                                                                                                              |
+| `version`   | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).                                                                                  |
 
 ## Exception safety
 
@@ -28,20 +28,22 @@ Strong guarantee: if an exception is thrown, there are no changes to any JSON va
 
 Constant.
 
-## Example
+## Examples
 
-The following code shows an example output of the `meta()`
-function.
+??? example
 
-```cpp
---8<-- "examples/meta.cpp"
-```
-
-Output:
-
-```json
---8<-- "examples/meta.output"
-```
+    The following code shows an example output of the `meta()`
+    function.
+    
+    ```cpp
+    --8<-- "examples/meta.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/meta.output"
+    ```
 
 ## Version history
 

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

@@ -1,4 +1,4 @@
-# basic_json::number_float_t
+# <small>nlohmann::basic_json::</small>number_float_t
 
 ```cpp
 using number_float_t = NumberFloatType;
@@ -49,6 +49,22 @@ and be serialized to `null`.
 
 Floating-point number values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `number_float_t` is by default, a typedef to `#!cpp double`.
+     
+    ```cpp
+    --8<-- "examples/number_float_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/number_float_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::number_integer_t
+# <small>nlohmann::basic_json::</small>number_integer_t
 
 ```cpp
 using number_integer_t = NumberIntegerType;
@@ -45,7 +45,7 @@ range will yield over/underflow when used in a constructor. During deserializati
 will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md).
 
 [RFC 8259](https://tools.ietf.org/html/rfc8259) further states:
-> 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
+> Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are
 > interoperable in the sense that implementations will agree exactly on their numeric values.
 
 As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is
@@ -55,6 +55,22 @@ interoperable.
 
 Integer number values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `number_integer_t` is by default, a typedef to `#!cpp std::int64_t`.
+     
+    ```cpp
+    --8<-- "examples/number_integer_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/number_integer_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::number_unsigned_t
+# <small>nlohmann::basic_json::</small>number_unsigned_t
 
 ```cpp
 using number_unsigned_t = NumberUnsignedType;
@@ -55,6 +55,22 @@ range [0, UINT64_MAX], this class's integer type is interoperable.
 
 Integer number values are stored directly inside a `basic_json` type.
 
+## Examples
+
+??? example
+
+    The following code shows that `number_unsigned_t` is by default, a typedef to `#!cpp std::uint64_t`.
+     
+    ```cpp
+    --8<-- "examples/number_unsigned_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/number_unsigned_t.output"
+    ```
+
 ## Version history
 
 - Added in version 2.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::object
+# <small>nlohmann::basic_json::</small>object
 
 ```cpp
 static basic_json object(initializer_list_t init = {});
@@ -16,6 +16,10 @@ elements must be strings. If the initializer list is empty, the empty object `#!
 
 JSON object value
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
 ## Exceptions
 
 Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose
@@ -23,10 +27,6 @@ first 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
 `init`. See example below.
 
-## Exception safety
-
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
-
 ## Complexity
 
 Linear in the size of `init`.
@@ -53,6 +53,11 @@ the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`
     --8<-- "examples/object.output"
     ```
 
+## See also
+
+- [`basic_json(initializer_list_t)`](basic_json.md) - create a JSON value from an initializer list
+- [`array`](array.md) - create a JSON array value from an initializer list
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,11 +1,9 @@
-# basic_json::object_comparator_t
+# <small>nlohmann::basic_json::</small>object_comparator_t
 
 ```cpp
-// until C++14
-using object_comparator_t = std::less<StringType>;
+using object_comparator_t = std::less<StringType>;  // until C++14
 
-// since C++14
-using object_comparator_t = std::less<>;
+using object_comparator_t = std::less<>;            // since C++14
 ```
 
 The comparator used in [`object_t`](object_t.md).

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

@@ -1,4 +1,4 @@
-# basic_json::object_t
+# <small>nlohmann::basic_json::</small>object_t
 
 ```cpp
 using object_t = ObjectType<StringType,
@@ -92,6 +92,22 @@ return name/value pairs in a different order than they were originally stored. I
 alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
 [RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects.
 
+## Examples
+
+??? example
+
+    The following code shows that `object_t` is by default, a typedef to `#!cpp std::map<json::string_t, json>`.
+     
+    ```cpp
+    --8<-- "examples/object_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/object_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::operator+=
+# <small>nlohmann::basic_json::</small>operator+=
 
 ```cpp
 // (1)
@@ -18,7 +18,7 @@ reference operator+=(initializer_list_t init);
 2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
    is created before inserting `val`.
 
-3. This function allows to use `operator+=` with an initializer list. In case
+3. This function allows using `operator+=` with an initializer list. In case
 
     1. the current value is an object,
     2. the initializer list `init` contains only two elements, and
@@ -62,7 +62,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
 
 ## Examples
 
-??? example
+??? example "Example: (1) add element to array"
 
     The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
     was silently converted to a JSON array.
@@ -77,7 +77,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
     --8<-- "examples/push_back.output"
     ```
 
-??? example
+??? example "Example: (2) add element to object"
 
     The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
     was silently converted to a JSON object.
@@ -92,7 +92,7 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
     --8<-- "examples/push_back__object_t__value.output"
     ```
 
-??? example
+??? example "Example: (3) add to object from initializer list"
 
     The example shows how initializer lists are treated as objects when possible.
 

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

@@ -1,4 +1,4 @@
-# basic_json::operator=
+# <small>nlohmann::basic_json::</small>operator=
 
 ```cpp
 basic_json& operator=(basic_json other) noexcept (
@@ -21,7 +21,7 @@ constructor, destructor, and the `swap()` member function.
 
 Linear.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::operator[]
+# <small>nlohmann::basic_json::</small>operator[]
 
 ```cpp
 // (1)
@@ -18,8 +18,8 @@ reference operator[](const json_pointer& ptr);
 const_reference operator[](const json_pointer& ptr) const;
 ```
 
-1. Returns a reference to the element at specified location `idx`.
-2. Returns a reference to the element at with specified key `key`.
+1. Returns a reference to the array element at specified location `idx`.
+2. Returns a reference to the object element at with specified key `key`.
 3. Returns a reference to the element at with specified JSON pointer `ptr`.
 
 ## Template parameters
@@ -44,6 +44,10 @@ const_reference operator[](const json_pointer& ptr) const;
 2. reference to the element at key `key`
 3. reference to the element pointed to by `ptr`
 
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
 ## Exceptions
 
 1. The function can throw the following exceptions:
@@ -62,6 +66,12 @@ const_reference operator[](const json_pointer& ptr) const;
     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
       not be resolved.
 
+## Complexity
+
+1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
+2. Logarithmic in the size of the container.
+3. Constant
+
 ## Notes
 
 !!! danger
@@ -80,26 +90,16 @@ const_reference operator[](const json_pointer& ptr) const;
    
     In particular:
 
-    - If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null`
+    - If the JSON pointer points to an object key that does not exist, it is created and filled with a `#!json null`
       value before a reference to it 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 is created and filled with a `#!json null`
       value before a reference to it is returned. All indices between the current maximum and the given index are also
       filled with `#!json null`.
     - The special value `-` is treated as a synonym for the index past the end.
 
-## Exception safety
+## Examples
 
-Strong exception safety: if an exception occurs, the original value stays intact.
-
-## Complexity
-
-1. Constant if `idx` is in the range of the array. Otherwise linear in `idx - size()`.
-2. Logarithmic in the size of the container.
-3. Constant
-
-## Example
-
-??? example
+??? example "Example (1): access specified array element"
 
     The example below shows how array elements can be read and written using `[]` operator. Note the addition of
     `#!json null` values.
@@ -114,7 +114,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/operatorarray__size_type.output"
     ```
 
-??? example
+??? example "Example (1): access specified array element"
 
     The example below shows how array elements can be read using the `[]` operator.
 
@@ -128,7 +128,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/operatorarray__size_type_const.output"
     ```
 
-??? example
+??? example "Example (2): access specified object element"
 
     The example below shows how object elements can be read and written using the `[]` operator.
     
@@ -142,7 +142,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/operatorarray__key_type.output"
     ```
 
-??? example
+??? example "Example (2): access specified object element"
 
     The example below shows how object elements can be read using the `[]` operator.
     
@@ -156,7 +156,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/operatorarray__key_type_const.output"
     ```
 
-??? example
+??? example "Example (3): access specified element via JSON Pointer"
 
     The example below shows how values can be read and written using JSON Pointers.
     
@@ -170,7 +170,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/operatorjson_pointer.output"
     ```
 
-??? example
+??? example "Example (3): access specified element via JSON Pointer"
 
     The example below shows how values can be read using JSON Pointers.
     
@@ -184,6 +184,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/operatorjson_pointer_const.output"
     ```
 
+## See also
+
+- see [`at`](at.md) for access by reference with range checking
+- see [`value`](value.md) for access with default value
+
 ## Version history
 
 1. Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::operator ValueType
+# <small>nlohmann::basic_json::</small>operator ValueType
 
 ```cpp
 template<typename ValueType>
@@ -45,7 +45,7 @@ explicit operator ValueType() const;
 That is, implicit conversions can be switched off by defining
 [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::operator==
+# <small>nlohmann::basic_json::</small>operator==
 
 ```cpp
 bool operator==(const_reference lhs, const_reference rhs) noexcept;
@@ -85,7 +85,7 @@ Linear.
     }
     ```
 
-## Example
+## Examples
 
 ??? example
 
@@ -101,6 +101,20 @@ Linear.
     --8<-- "examples/operator__equal.output"
     ```
 
+??? example
+
+    The example demonstrates comparing several JSON types against the null pointer (JSON `#!json null`).
+        
+    ```cpp
+    --8<-- "examples/operator__equal__nullptr_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator__equal__nullptr_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::operator>=
+# <small>nlohmann::basic_json::</small>operator>=
 
 ```cpp
 bool operator>=(const_reference lhs, const_reference rhs) noexcept,
@@ -38,7 +38,7 @@ No-throw guarantee: this function never throws exceptions.
 
 Linear.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::operator>
+# <small>nlohmann::basic_json::</small>operator>
 
 ```cpp
 bool operator>(const_reference lhs, const_reference rhs) noexcept,
@@ -37,7 +37,7 @@ No-throw guarantee: this function never throws exceptions.
 
 Linear.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -0,0 +1,65 @@
+# operator>>(basic_json)
+
+```cpp
+std::istream& operator>>(std::istream& i, basic_json& j);
+```
+
+Deserializes an input stream to a JSON value.
+
+## Parameters
+
+`i` (in, out)
+:   input stream to read a serialized JSON value from
+
+`j` (in, out)
+:   JSON value to write the deserialized input to
+
+## Return value
+
+the stream `i`
+
+## Exceptions
+
+- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
+- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate 
+  error.
+- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
+
+## Complexity
+
+Linear in the length of the input. The parser is a predictive LL(1) parser.
+
+## Notes
+
+A UTF-8 byte order mark is silently ignored.
+
+## Examples
+
+??? example
+
+    The example below shows how a JSON value is constructed by reading a serialization from a stream.
+        
+    ```cpp
+    --8<-- "examples/operator_deserialize.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_deserialize.output"
+    ```
+
+## See also
+
+- [accept](accept.md) - check if the input is valid JSON
+- [parse](parse.md) - deserialize from a compatible input
+
+## Version history
+
+- Added in version 1.0.0
+
+!!! warning "Deprecation"
+
+    This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
+    been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
+    with `#!cpp i >> j;`.

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

@@ -1,4 +1,4 @@
-# basic_json::operator<=
+# <small>nlohmann::basic_json::</small>operator<=
 
 ```cpp
 bool operator<=(const_reference lhs, const_reference rhs) noexcept,
@@ -38,7 +38,7 @@ No-throw guarantee: this function never throws exceptions.
 
 Linear.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,7 +1,7 @@
-# basic_json::operator""_json
+# <small>nlohmann::basic_json::</small>operator""_json
 
 ```cpp
-json operator "" _json(const char* s, std::size_t n)
+json operator "" _json(const char* s, std::size_t n);
 ```
 
 This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a
@@ -27,6 +27,22 @@ The function can throw anything that [`parse(s, s+n)`](parse.md) would throw.
 
 Linear.
 
+## Examples
+
+??? example
+
+    The following code shows how to create JSON values from string literals.
+     
+    ```cpp
+    --8<-- "examples/operator_literal_json.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_literal_json.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -1,11 +1,11 @@
-# basic_json::operator""_json_pointer
+# <small>nlohmann::basic_json::</small>operator""_json_pointer
 
 ```cpp
-json_pointer operator "" _json_pointer(const char* s, std::size_t n)
+json_pointer operator "" _json_pointer(const char* s, std::size_t n);
 ```
 
 This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
-to a string literal and returns a [`json_pointer`](../json_pointer.md) object if no parse error occurred.
+to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred.
 
 ## Parameters
 
@@ -17,16 +17,32 @@ to a string literal and returns a [`json_pointer`](../json_pointer.md) object if
 
 ## Return value
 
-[`json_pointer`](../json_pointer.md) value parsed from `s`
+[`json_pointer`](../json_pointer/index.md) value parsed from `s`
 
 ## Exceptions
 
-The function can throw anything that [`json_pointer::json_pointer`](../json_pointer.md) would throw.
+The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw.
 
 ## Complexity
 
 Linear.
 
+## Examples
+
+??? example
+
+    The following code shows how to create JSON Pointers from string literals.
+     
+    ```cpp
+    --8<-- "examples/operator_literal_json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_literal_json_pointer.output"
+    ```
+
 ## Version history
 
 - Added in version 2.0.0.

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

@@ -1,7 +1,7 @@
-# basic_json::operator<
+# <small>nlohmann::basic_json::</small>operator<
 
 ```cpp
-bool operator<(const_reference lhs, const_reference rhs) noexcept,
+bool operator<(const_reference lhs, const_reference rhs) noexcept;
 
 template<typename ScalarType>
 bool operator<(const_reference lhs, const ScalarType rhs) noexcept;
@@ -52,7 +52,7 @@ No-throw guarantee: this function never throws exceptions.
 
 Linear.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -0,0 +1,62 @@
+# operator<<(basic_json)
+
+```cpp
+std::ostream& operator<<(std::ostream& o, const basic_json& j);
+```
+
+Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
+[`dump`](dump.md) member function.
+
+- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
+  instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result
+  is the same as calling `dump(4)`.
+- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
+  the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character.
+
+## Parameters
+
+`o` (in, out)
+:   stream to serialize to
+
+`j` (in)
+:   JSON value to serialize
+
+## Return value
+
+the stream `o`
+
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set.
+
+## Complexity
+
+Linear.
+
+## Examples
+
+??? example
+
+    The example below shows the serialization with different parameters to `width` to adjust the indentation level.
+        
+    ```cpp
+    --8<-- "examples/operator_serialize.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_serialize.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0
+- Support for indentation character added in version 3.0.0.
+
+!!! warning "Deprecation"
+
+    This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has
+    been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;`
+    with `#!cpp o << j;`.

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

@@ -1,4 +1,4 @@
-# basic_json::operator!=
+# <small>nlohmann::basic_json::</small>operator!=
 
 ```cpp
 bool operator!=(const_reference lhs, const_reference rhs) noexcept;
@@ -37,20 +37,35 @@ No-throw guarantee: this function never throws exceptions.
 
 Linear.
 
-## Example
+## Examples
 
-The example demonstrates comparing several JSON
-types.
+??? example
+
+    The example demonstrates comparing several JSON types.
+        
+    ```cpp
+    --8<-- "examples/operator__notequal.cpp"
+    ```
     
-```cpp
---8<-- "examples/operator__notequal.cpp"
-```
+    Output:
+    
+    ```json
+    --8<-- "examples/operator__notequal.output"
+    ```
 
-Output:
+??? example
 
-```json
---8<-- "examples/operator__notequal.output"
-```
+    The example demonstrates comparing several JSON types against the null pointer (JSON `#!json null`).
+        
+    ```cpp
+    --8<-- "examples/operator__notequal__nullptr_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator__notequal__nullptr_t.output"
+    ```
 
 ## Version history
 

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

@@ -1,4 +1,4 @@
-# basic_json::operator value_t
+# <small>nlohmann::basic_json::</small>operator value_t
 
 ```cpp
 constexpr operator value_t() const noexcept;
@@ -10,18 +10,18 @@ Return the type of the JSON value as a value from the [`value_t`](value_t.md) en
 
 the type of the JSON value
 
-Value type                | return value
-------------------------- | -------------------------
-`#!json null`             | `value_t::null`
-boolean                   | `value_t::boolean`
-string                    | `value_t::string`
-number (integer)          | `value_t::number_integer`
-number (unsigned integer) | `value_t::number_unsigned`
-number (floating-point)   | `value_t::number_float`
-object                    | `value_t::object`
-array                     | `value_t::array`
-binary                    | `value_t::binary`
-discarded                 | `value_t::discarded`
+| Value type                | return value               |
+|---------------------------|----------------------------|
+| `#!json null`             | `value_t::null`            |
+| boolean                   | `value_t::boolean`         |
+| string                    | `value_t::string`          |
+| number (integer)          | `value_t::number_integer`  |
+| number (unsigned integer) | `value_t::number_unsigned` |
+| number (floating-point)   | `value_t::number_float`    |
+| object                    | `value_t::object`          |
+| array                     | `value_t::array`           |
+| binary                    | `value_t::binary`          |
+| discarded                 | `value_t::discarded`       |
 
 ## Exception safety
 
@@ -31,7 +31,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::other_error
+# <small>nlohmann::basic_json::</small>other_error
 
 ```cpp
 class other_error : public exception;
@@ -6,7 +6,7 @@ class other_error : public exception;
 
 This exception is thrown in case of errors that cannot be classified with the other exception types.
 
-Exceptions have ids 5xx.
+Exceptions have ids 5xx (see [list of other errors](../../home/exceptions.md#further-exceptions)).
 
 ```plantuml
 std::exception <|-- basic_json::exception
@@ -38,7 +38,7 @@ class basic_json::other_error #FFFF00 {}
 
 - **id** - the id of the exception
 
-## Example
+## Examples
 
 ??? example
 
@@ -54,6 +54,14 @@ class basic_json::other_error #FFFF00 {}
     --8<-- "examples/other_error.output"
     ```
 
+## See also
+
+- [List of other errors](../../home/exceptions.md#further-exceptions)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+
 ## Version history
 
 - Since version 3.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::out_of_range
+# <small>nlohmann::basic_json::</small>out_of_range
 
 ```cpp
 class out_of_range : public exception;
@@ -7,7 +7,7 @@ class out_of_range : public exception;
 This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for
 instance in case of array indices or nonexisting object keys.
 
-Exceptions have ids 4xx.
+Exceptions have ids 4xx (see [list of out-of-range errors](../../home/exceptions.md#out-of-range)).
 
 ```plantuml
 std::exception <|-- basic_json::exception
@@ -39,7 +39,7 @@ class basic_json::out_of_range #FFFF00 {}
 
 - **id** - the id of the exception
 
-## Example
+## Examples
 
 ??? example
 
@@ -55,6 +55,14 @@ class basic_json::out_of_range #FFFF00 {}
     --8<-- "examples/out_of_range.output"
     ```
 
+## See also
+
+- [List of out-of-range errors](../../home/exceptions.md#out-of-range)
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
 ## Version history
 
 - Since version 3.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::parse
+# <small>nlohmann::basic_json::</small>parse
 
 ```cpp
 // (1)
@@ -180,8 +180,22 @@ super-linear complexity.
     --8<-- "examples/parse__allow_exceptions.output"
     ```
 
+## See also
+
+- [accept](accept.md) - check if the input is valid JSON
+- [operator>>](operator_gtgt.md) - deserialize from stream
+
 ## Version history
 
 - Added in version 1.0.0.
 - Overload for contiguous containers (1) added in version 2.0.3.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
+
+!!! warning "Deprecation"
+
+    Overload (2) replaces calls to `parse` with a pair of iterators as their first parameter which has been
+    deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+    `#!cpp parse({ptr, ptr+len}, ...);` with `#!cpp parse(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

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

@@ -1,4 +1,4 @@
-# basic_json::parse_error
+# <small>nlohmann::basic_json::</small>parse_error
 
 ```cpp
 class parse_error : public exception;
@@ -7,7 +7,9 @@ class parse_error : public exception;
 This exception is thrown by the library when a parse error occurs. Parse errors can occur during the deserialization of
 JSON text, BSON, CBOR, MessagePack, UBJSON, as well as when using JSON Patch.
 
-Exceptions have ids 1xx.
+Member `byte` holds the byte index of the last read character in the input file (see note below).
+
+Exceptions have ids 1xx (see [list of parse errors](../../home/exceptions.md#parse-errors)).
 
 ```plantuml
 std::exception <|-- basic_json::exception
@@ -38,12 +40,12 @@ class basic_json::parse_error #FFFF00 {
 - **id** - the id of the exception
 - **byte** - byte index of the parse error
 
-## Note
+## Notes
 
-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
+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 for binary formats.
 
-## Example
+## Examples
 
 ??? example
 
@@ -59,6 +61,14 @@ or the end of file. This also holds true when reading a byte vector for binary f
     --8<-- "examples/parse_error.output"
     ```
 
+## See also
+
+- [List of parse errors](../../home/exceptions.md#parse-errors)
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
+- [`other_error`](other_error.md) for exceptions indicating other library errors
+
 ## Version history
 
 - Since version 3.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::parse_event_t
+# <small>nlohmann::basic_json::</small>parse_event_t
 
 ```cpp
 enum class parse_event_t : std::uint8_t {
@@ -20,7 +20,7 @@ The parser callback distinguishes the following events:
 - `array_end`: the parser read `]` and finished processing a JSON array
 - `value`: the parser finished reading a JSON value
 
-## Example
+## Examples
 
 ![Example when certain parse events are triggered](../../images/callback_events.png)
 

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

@@ -1,4 +1,4 @@
-# basic_json::parser_callback_t
+# <small>nlohmann::basic_json::</small>parser_callback_t
 
 ```cpp
 template<typename BasicJsonType>
@@ -14,14 +14,14 @@ is a boolean indicating whether the element that emitted the callback shall be k
 We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
 table describes the values of the parameters `depth`, `event`, and `parsed`.
 
-parameter `event` | description | parameter `depth` | parameter `parsed`
------------------- | ----------- | ------------------ | -------------------
-`parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
-`parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
-`parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
-`parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
-`parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
-`parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value
+| parameter `event`             | description                                               | parameter `depth`                         | parameter `parsed`               |
+|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
+| `parse_event_t::object_start` | the parser read `{` and started to process a JSON object  | depth of the parent of the JSON object    | a JSON value with type discarded |
+| `parse_event_t::key`          | the parser read a key of a value in an object             | depth of the currently parsed JSON object | a JSON string containing the key |
+| `parse_event_t::object_end`   | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object    | the parsed JSON object           |
+| `parse_event_t::array_start`  | the parser read `[` and started to process a JSON array   | depth of the parent of the JSON array     | a JSON value with type discarded |
+| `parse_event_t::array_end`    | the parser read `]` and finished processing a JSON array  | depth of the parent of the JSON array     | the parsed JSON array            |
+| `parse_event_t::value`        | the parser finished reading a JSON value                  | depth of the value                        | the parsed JSON value            |
 
 ![Example when certain parse events are triggered](../../images/callback_events.png)
 
@@ -51,7 +51,7 @@ called:
 Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In
 the latter case, it is either skipped completely or replaced by an empty discarded object.
 
-# Example
+## Examples
 
 ??? example
 

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

@@ -1,11 +1,11 @@
-# basic_json::patch
+# <small>nlohmann::basic_json::</small>patch
 
 ```cpp
 basic_json patch(const basic_json& json_patch) const;
 ```
 
 [JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to
-a JSON) document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
+a JSON document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from
 the patch.
 
 ## Parameters
@@ -17,6 +17,10 @@ the patch.
 
 patched document
 
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+
 ## Exceptions
 
 - Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of
@@ -31,21 +35,17 @@ patched document
 - 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 changes in the JSON value.
-
 ## Complexity
 
 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
 affected by the patch, the complexity can usually be neglected.
 
-## Note
+## Notes
 
 The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception
 is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.
 
-## Example
+## Examples
 
 ??? example
 
@@ -61,6 +61,12 @@ is thrown. In any case, the original value is not changed: the patch is applied
     --8<-- "examples/patch.output"
     ```
 
+## See also
+
+- [RFC 6902 (JSON Patch)](https://tools.ietf.org/html/rfc6902)
+- [RFC 6901 (JSON Pointer)](https://tools.ietf.org/html/rfc6901)
+- [merge_patch](merge_patch.md) applies a JSON Merge Patch
+
 ## Version history
 
 - Added in version 2.0.0.

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

@@ -1,4 +1,4 @@
-# basic_json::push_back
+# <small>nlohmann::basic_json::</small>push_back
 
 ```cpp
 // (1)
@@ -18,7 +18,7 @@ void push_back(initializer_list_t init);
 2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object
    is created before inserting `val`.
 
-3. This function allows to use `push_back` with an initializer list. In case
+3. This function allows using `push_back` with an initializer list. In case
 
     1. the current value is an object,
     2. the initializer list `init` contains only two elements, and
@@ -58,7 +58,7 @@ void push_back(initializer_list_t init);
 
 ## Examples
 
-??? example
+??? example "Example: (1) add element to array"
 
     The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value
     was silently converted to a JSON array.
@@ -73,7 +73,7 @@ void push_back(initializer_list_t init);
     --8<-- "examples/push_back.output"
     ```
 
-??? example
+??? example "Example: (2) add element to object"
 
     The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value
     was silently converted to a JSON object.
@@ -88,7 +88,7 @@ void push_back(initializer_list_t init);
     --8<-- "examples/push_back__object_t__value.output"
     ```
 
-??? example
+??? example "Example: (3) add to object from initializer list"
 
     The example shows how initializer lists are treated as objects when possible.
 

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

@@ -1,4 +1,4 @@
-# basic_json::rbegin
+# <small>nlohmann::basic_json::</small>rbegin
 
 ```cpp
 reverse_iterator rbegin() noexcept;
@@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::rend
+# <small>nlohmann::basic_json::</small>rend
 
 ```cpp
 reverse_iterator rend() noexcept;
@@ -22,7 +22,7 @@ No-throw guarantee: this member function never throws exceptions.
 
 Constant.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -1,4 +1,4 @@
-# basic_json::sax_parse
+# <small>nlohmann::basic_json::</small>sax_parse
 
 ```cpp
 // (1)
@@ -23,10 +23,10 @@ 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 4 bytes, which will be interpreted
+    The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
     respectively as UTF-8, UTF-16 and UTF-32.
 
-The SAX event lister must follow the interface of `json_sax`.
+The SAX event lister must follow the interface of [`json_sax`](../json_sax/index.md).
 
 ## Template parameters
 
@@ -107,3 +107,9 @@ A UTF-8 byte order mark is silently ignored.
 
 - Added in version 3.2.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
+
+!!! warning "Deprecation"
+
+    Overload (2) replaces calls to `sax_parse` with a pair of iterators as their first parameter which has been
+    deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
+    `#!cpp sax_parse({ptr, ptr+len});` with `#!cpp sax_parse(ptr, ptr+len);`.

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

@@ -1,4 +1,4 @@
-# basic_json::size
+# <small>nlohmann::basic_json::</small>size
 
 ```cpp
 size_type size() const noexcept;
@@ -10,15 +10,15 @@ Returns the number of elements in a JSON value.
 
 The return value depends on the different types and is defined as follows:
 
-Value type  | return value
------------ | -------------
-null        | `0`
-boolean     | `1`
-string      | `1`
-number      | `1`
-binary      | `1`
-object      | result of function object_t::size()
-array       | result of function array_t::size()
+| Value type | return value                        |
+|------------|-------------------------------------|
+| null       | `0`                                 |
+| boolean    | `1`                                 |
+| string     | `1`                                 |
+| number     | `1`                                 |
+| binary     | `1`                                 |
+| object     | result of function object_t::size() |
+| array      | result of function array_t::size()  |
 
 ## Exception safety
 
@@ -35,7 +35,7 @@ constant complexity.
 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.
 
-## Example
+## Examples
 
 ??? example
 

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

@@ -0,0 +1,32 @@
+# <small>std::</small>hash<nlohmann::basic_json\>
+
+```cpp
+namespace std {
+    struct hash<nlohmann::basic_json>;
+}
+```
+
+Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the
+type of the JSON value is taken into account to have different hash values for `#!json null`, `#!cpp 0`, `#!cpp 0U`, and
+`#!cpp false`, etc.
+
+## Examples
+
+??? example
+
+    The example shows how to calculate hash values for different JSON values.
+     
+    ```cpp
+    --8<-- "examples/std_hash.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/std_hash.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended for arbitrary basic_json types in version 3.10.5.

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

@@ -0,0 +1,51 @@
+# std::swap<basic_json\>
+
+```cpp
+namespace std {
+    void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2);
+}
+```
+
+Exchanges the values of two JSON objects.
+
+## Parameters
+
+`j1` (in, out)
+:   value to be replaced by `j2`
+
+`j2` (in, out)
+:   value to be replaced by `j1`
+
+## Possible implementation
+
+```cpp
+void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2)
+{
+    j1.swap(j2);
+}
+```
+
+## Examples
+
+??? example
+
+    The following code shows how two values are swapped with `std::swap`.
+     
+    ```cpp
+    --8<-- "examples/std_swap.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/std_swap.output"
+    ```
+
+## See also
+
+- [swap](swap.md)
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended for arbitrary basic_json types in version 3.10.5.

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

@@ -1,4 +1,4 @@
-# basic_json::string_t
+# <small>nlohmann::basic_json::</small>string_t
 
 ```cpp
 using string_t = StringType;
@@ -45,6 +45,22 @@ This implementation is interoperable as it does compare strings code unit by cod
 String values are stored as pointers in a `basic_json` type. That is, for any access to string values, a pointer of type
 `string_t*` must be dereferenced.
 
+## Examples
+
+??? example
+
+    The following code shows that `string_t` is by default, a typedef to `#!cpp std::string`.
+     
+    ```cpp
+    --8<-- "examples/string_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/string_t.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -0,0 +1,157 @@
+# <small>nlohmann::basic_json::</small>swap
+
+```cpp
+// (1)
+void swap(reference other) noexcept;
+
+// (2)
+void swap(reference left, reference right) noexcept;
+
+// (3)
+void swap(array_t& other);
+
+// (4)
+void swap(object_t& other);
+
+// (5)
+void swap(string_t& other);
+
+// (6)
+void swap(binary_t& other);
+
+// (7)
+void swap(typename binary_t::container_type& other);
+```
+
+1. Exchanges the contents of the JSON value with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. 
+2. Exchanges the contents of the JSON value from `left` with those of `right`. Does not invoke any move, copy, or swap
+   operations on individual elements. All iterators and references remain valid. The past-the-end iterator is
+   invalidated. Implemented as a friend function callable via ADL.
+3. Exchanges the contents of a JSON array with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. 
+4. Exchanges the contents of a JSON object with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+5. Exchanges the contents of a JSON string with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+6. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+7. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. Unlike
+   version (6), no binary subtype is involved.
+
+## Parameters
+
+`other` (in, out)
+:   value to exchange the contents with
+
+`left` (in, out)
+:   value to exchange the contents with
+
+`right` (in, out)
+:   value to exchange the contents with
+
+## Exceptions
+
+1. No-throw guarantee: this function never throws exceptions.
+2. No-throw guarantee: this function never throws exceptions.
+3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   arrays; example: `"cannot use swap() with boolean"`
+4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   objects; example: `"cannot use swap() with boolean"`
+5. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   strings; example: `"cannot use swap() with boolean"`
+6. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   binaries; example: `"cannot use swap() with boolean"`
+7. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   binaries; example: `"cannot use swap() with boolean"`
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example "Example: Swap JSON value (1, 2)"
+
+    The example below shows how JSON values can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__reference.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__reference.output"
+    ```
+
+??? example "Example: Swap array (3)"
+
+    The example below shows how arrays can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__array_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__array_t.output"
+    ```
+
+??? example "Example: Swap object (4)"
+
+    The example below shows how objects can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__object_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__object_t.output"
+    ```
+
+??? example "Example: Swap string (5)"
+
+    The example below shows how strings can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__string_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__string_t.output"
+    ```
+
+??? example "Example: Swap string (6)"
+
+    The example below shows how binary values can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__binary_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__binary_t.output"
+    ```
+
+## See also
+
+- [std::swap<basic_json\>](std_swap.md)
+
+## Version history
+
+1. Since version 1.0.0.
+2. Since version 1.0.0.
+3. Since version 1.0.0.
+4. Since version 1.0.0.
+5. Since version 1.0.0.
+6. Since version 3.8.0.
+7. Since version 3.8.0.

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

@@ -1,4 +1,4 @@
-# basic_json::to_bson
+# <small>nlohmann::basic_json::</small>to_bson
 
 ```cpp
 // (1)
@@ -15,6 +15,8 @@ so-called document).
 1. Returns a byte vector containing the BSON serialization.
 2. Writes the BSON serialization to an output adapter.
 
+The exact mapping and its limitations is described on a [dedicated page](../../features/binary_formats/bson.md).
+
 ## Parameters
 
 `j` (in)
@@ -36,7 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 Linear in the size of the JSON value `j`.
 
-## Example
+## Examples
 
 ??? example