Documentation change (#3672)

Co-authored-by: Florian Albrechtskirchinger <falbrechtskirchinger@gmail.com>

.github/workflows/ubuntu.yml

@@ -151,9 +151,12 @@ jobs:
 
   ci_test_documentation:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        target: [ci_test_examples, ci_test_api_documentation]
     steps:
       - uses: actions/checkout@v3
       - name: Run CMake
         run: cmake -S . -B build -DJSON_CI=On
       - name: Build
-        run: cmake --build build --target ci_test_documentation
+        run: cmake --build build --target ${{ matrix.target }}

cmake/ci.cmake

@@ -953,12 +953,18 @@ add_custom_target(ci_icpc
 # test documentation
 ###############################################################################
 
-add_custom_target(ci_test_documentation
+add_custom_target(ci_test_examples
     COMMAND make CXX="${GCC_TOOL}" check_output_portable -j8
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs
     COMMENT "Check that all examples compile and create the desired output"
 )
 
+add_custom_target(ci_test_api_documentation
+    COMMAND ${Python3_EXECUTABLE} scripts/check_structure.py
+    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs
+    COMMENT "Lint the API documentation"
+)
+
 ###############################################################################
 # Clean up all generated files.
 ###############################################################################

docs/examples/from_json__default_constructible.cpp

@@ -0,0 +1,37 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+// a simple struct to model a person
+struct person
+{
+    std::string name;
+    std::string address;
+    int age;
+};
+} // namespace ns
+
+namespace ns
+{
+void from_json(const json& j, person& p)
+{
+    j.at("name").get_to(p.name);
+    j.at("address").get_to(p.address);
+    j.at("age").get_to(p.age);
+}
+} // namespace ns
+
+int main()
+{
+    json j;
+    j["name"] = "Ned Flanders";
+    j["address"] = "744 Evergreen Terrace";
+    j["age"] = 60;
+
+    auto p = j.get<ns::person>();
+
+    std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
+}

docs/examples/from_json__default_constructible.output

@@ -0,0 +1 @@
+Ned Flanders (60) lives in 744 Evergreen Terrace

docs/examples/from_json__non_default_constructible.cpp

@@ -0,0 +1,53 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+// a simple struct to model a person (not default constructible)
+struct person
+{
+    person(std::string n, std::string a, int aa)
+        : name(std::move(n)), address(std::move(a)), age(aa)
+    {}
+
+    std::string name;
+    std::string address;
+    int age;
+};
+} // namespace ns
+
+namespace nlohmann
+{
+template <>
+struct adl_serializer<ns::person>
+{
+    static ns::person from_json(const json& j)
+    {
+        return {j.at("name"), j.at("address"), j.at("age")};
+    }
+
+    // Here's the catch! You must provide a to_json method! Otherwise, you
+    // will not be able to convert person to json, since you fully
+    // specialized adl_serializer on that type
+    static void to_json(json& j, ns::person p)
+    {
+        j["name"] = p.name;
+        j["address"] = p.address;
+        j["age"] = p.age;
+    }
+};
+} // namespace nlohmann
+
+int main()
+{
+    json j;
+    j["name"] = "Ned Flanders";
+    j["address"] = "744 Evergreen Terrace";
+    j["age"] = 60;
+
+    auto p = j.get<ns::person>();
+
+    std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
+}

docs/examples/from_json__non_default_constructible.output

@@ -0,0 +1 @@
+Ned Flanders (60) lives in 744 Evergreen Terrace

docs/examples/nlohmann_json_namespace.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// possible use case: use NLOHMANN_JSON_NAMESPACE instead of nlohmann
+using json = NLOHMANN_JSON_NAMESPACE::json;
+
+// macro needed to output the NLOHMANN_JSON_NAMESPACE as string literal
+#define Q(x) #x
+#define QUOTE(x) Q(x)
+
+int main()
+{
+    std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl;
+}

docs/examples/nlohmann_json_namespace.output

@@ -0,0 +1 @@
+nlohmann::json_v3_11_1

docs/examples/nlohmann_json_namespace_begin.c++17.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <optional>
+#include <nlohmann/json.hpp>
+
+// partial specialization (see https://json.nlohmann.me/features/arbitrary_types/)
+NLOHMANN_JSON_NAMESPACE_BEGIN
+template <typename T>
+struct adl_serializer<std::optional<T>>
+{
+    static void to_json(json& j, const std::optional<T>& opt)
+    {
+        if (opt == std::nullopt)
+        {
+            j = nullptr;
+        }
+        else
+        {
+            j = *opt;
+        }
+    }
+};
+NLOHMANN_JSON_NAMESPACE_END
+
+int main()
+{
+    std::optional<int> o1 = 1;
+    std::optional<int> o2 = std::nullopt;
+
+    NLOHMANN_JSON_NAMESPACE::json j;
+    j.push_back(o1);
+    j.push_back(o2);
+    std::cout << j << std::endl;
+}

docs/examples/nlohmann_json_namespace_begin.c++17.output

@@ -0,0 +1 @@
+[1,null]

docs/examples/to_json.cpp

@@ -0,0 +1,32 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+// a simple struct to model a person
+struct person
+{
+    std::string name;
+    std::string address;
+    int age;
+};
+} // namespace ns
+
+namespace ns
+{
+void to_json(json& j, const person& p)
+{
+    j = json{ {"name", p.name}, {"address", p.address}, {"age", p.age} };
+}
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    json j = p;
+
+    std::cout << j << std::endl;
+}

docs/examples/to_json.output

@@ -0,0 +1 @@
+{"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}

docs/mkdocs/docs/api/adl_serializer/from_json.md

@@ -14,8 +14,8 @@ noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_
 -> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {}))
 ```
 
-This function is usually called by the [`get()`](../basic_json/get.md) function of the
+This function is usually called by the [`get()`](../basic_json/get.md) function of the [basic_json](../basic_json)
-[basic_json](../basic_json) class (either explicit or via conversion operators).
+class (either explicitly or via the conversion operators).
 
 1. This function is chosen for default-constructible value types.
 2. This function is chosen for value types which are not default-constructible.
@@ -32,9 +32,41 @@ This function is usually called by the [`get()`](../basic_json/get.md) function
 
 Copy of the JSON value, converted to `ValueType`
 
-!!! note
+## Examples
 
-    This documentation page is a stub.
+??? example "Example: (1) Default-constructible type"
+
+    The example below shows how a `from_json` function can be implemented for a user-defined type. This function is
+    called by the `adl_serializer` when `get<ns::person>()` is called.
+        
+    ```cpp
+    --8<-- "examples/from_json__default_constructible.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_json__default_constructible.output"
+    ```
+
+??? example "Example: (2) Non-default-constructible type"
+
+    The example below shows how a `from_json` is implemented as part of a specialization of the `adl_serializer` to
+    realize the conversion of a non-default-constructible type.
+        
+    ```cpp
+    --8<-- "examples/from_json__non_default_constructible.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_json__non_default_constructible.output"
+    ```
+
+## See also
+
+- [to_json](to_json.md)
 
 ## Version history
 

docs/mkdocs/docs/api/adl_serializer/to_json.md

@@ -17,9 +17,26 @@ This function is usually called by the constructors of the [basic_json](../basic
 `val` (in)
 :   value to read from
 
-!!! note
+## Examples
 
-    This documentation page is a stub.
+??? example
+
+    The example below shows how a `to_json` function can be implemented for a user-defined type. This function is called
+    by the `adl_serializer` when the constructor `basic_json(ns::person)` is called.
+        
+    ```cpp
+    --8<-- "examples/to_json.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/to_json.output"
+    ```
+
+## See also
+
+- [from_json](from_json.md)
 
 ## Version history
 

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

@@ -6,8 +6,8 @@ using boolean_t = BooleanType;
 
 The type used to store JSON booleans.
 
-[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two literals
+[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two
-`#!json true` and `#!json false`.
+literals `#!json true` and `#!json false`.
 
 To store objects in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.
 

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

@@ -19,6 +19,23 @@ using json_serializer = JSONSerializer<T, SFINAE>;
 
 The default values for `json_serializer` is [`adl_serializer`](../adl_serializer).
 
+## Examples
+
+??? example
+
+    The example below shows how a conversion of a non-default-constructible type is implemented via a specialization of
+    the `adl_serializer`.
+        
+    ```cpp
+    --8<-- "examples/from_json__non_default_constructible.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/from_json__non_default_constructible.output"
+    ```
+
 ## Version history
 
 - Since version 2.0.0.

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

@@ -28,4 +28,5 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
 ## Version history
 
 - Added in version 3.0.0.
-- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0.
+- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in
+  version 3.11.0.

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

@@ -90,7 +90,8 @@ Objects are stored as pointers in a `basic_json` type. That is, for any access t
 The order name/value pairs are added to the object is *not* preserved by the library. Therefore, iterating an object may
 return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in
 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.
+[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON
+objects.
 
 ## Examples
 

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

@@ -21,7 +21,8 @@ const_reference operator[](const json_pointer& ptr) const;
 ```
 
 1. Returns a reference to the array element at specified location `idx`.
-2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value.
+2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by
+   value.
 3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
    `#!cpp typename object_comparator_t::is_transparent` denotes a type.
 4. Returns a reference to the element with specified JSON pointer `ptr`.
@@ -234,6 +235,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 ## Version history
 
 1. Added in version 1.0.0.
-2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0.
+2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3)
+   in version 3.11.0.
 3. Added in version 3.11.0.
 4. Added in version 2.0.0.

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

@@ -20,8 +20,8 @@ class basic_json {
 ```
 
 1. Compares two JSON values for equality according to the following rules:
-    - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same
+    - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same type and their stored
-      type and their stored values are the same according to their respective `operator==`.
+      values are the same according to their respective `operator==`.
     - Integer and floating-point numbers are automatically converted before comparison.
 
 2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the

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

@@ -11,15 +11,14 @@ template<typename ScalarType>
 bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 ```
 
-1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs`
+1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` according to the following
-   according to the following rules:
+   rules:
-    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and
-      operand is `NaN` and the other operand is either `NaN` or any other number.
+      the other operand is either `NaN` or any other number.
     - Otherwise, returns the result of `#!cpp !(lhs < rhs)` (see [**operator<**](operator_lt.md)).
 
-2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or
+2. Compares whether a JSON value is greater than or equal to a scalar or a scalar is greater than or equal to a JSON
-   equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values
+   value by converting the scalar to a JSON value and comparing both JSON values according to 1.
-   according to 1.
 
 ## Template parameters
 

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

@@ -20,13 +20,12 @@ class basic_json {
 ```
 
 1. Compares two JSON values for inequality according to the following rules:
-    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and
-      operand is `NaN` and the other operand is either `NaN` or any other number.
+      the other operand is either `NaN` or any other number.
-    - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or
+    - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or `#!cpp !(*this == rhs)` (since C++20).
-      `#!cpp !(*this == rhs)` (since C++20).
 
-2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the
+2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the scalar to a JSON
-   scalar to a JSON value and comparing both JSON values according to 1.
+   value and comparing both JSON values according to 1.
 
 ## Template parameters
 

docs/mkdocs/docs/api/basic_json/operator_spaceship.md

@@ -12,16 +12,16 @@ class basic_json {
 
 1. 3-way compares two JSON values producing a result of type `std::partial_ordering` according to the following rules:
     - Two JSON values compare with a result of `std::partial_ordering::unordered` if either value is discarded.
-    - If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using their
+    - If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using
+      their respective `operator<=>`.
+    - Integer and floating-point numbers are converted to their common type and then 3-way compared using their
       respective `operator<=>`.
-    - Integer and floating-point numbers are converted to their common type and then 3-way compared using their respective
+      For instance, comparing an integer and a floating-point value will 3-way compare the first value converted to
-      `operator<=>`.
-      For instance, comparing an integer and a floating-point value will 3-way compare the first value convertered to
       floating-point with the second value.
     - Otherwise, yields a result by comparing the type (see [`value_t`](value_t.md)).
   
-2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and 3-way
+2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and
-   comparing both JSON values (see 1).
+   3-way comparing both JSON values (see 1).
 
 ## Template parameters
 

docs/mkdocs/docs/api/basic_json/to_bjdata.md

@@ -13,8 +13,8 @@ static void to_bjdata(const basic_json& j, detail::output_adapter<char> o,
                       const bool use_size = false, const bool use_type = false);
 ```
 
-Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData
+Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData aims to
-aims to be more compact than JSON itself, yet more efficient to parse.
+be more compact than JSON itself, yet more efficient to parse.
 
 1. Returns a byte vector containing the BJData serialization.
 2. Writes the BJData serialization to an output adapter.

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

@@ -52,10 +52,8 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_
 
     `operator<` and `operator<=>` (since C++20) are overloaded and compare according to the ordering described above.
     Until C++20 all other relational and equality operators yield results according to the integer value of each
-    enumerator.
+    enumerator. Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during
-    Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during overload
+    overload resolution, while others do not. For predictable and portable behavior use:
-    resolution, while others do not.
-    For predictable and portable behavior use:
 
       - `operator<` or `operator<=>` when wanting to compare according to the order described above
       - `operator==` or `operator!=` when wanting to compare according to each enumerators integer value

docs/mkdocs/docs/api/basic_json/~basic_json.md

@@ -14,6 +14,8 @@ No-throw guarantee: this member function never throws exceptions.
 
 Linear.
 
+<!-- NOLINT Examples -->
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/json_sax/binary.md

@@ -23,7 +23,7 @@ It is safe to move the passed binary value.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse__binary.cpp"

docs/mkdocs/docs/api/json_sax/boolean.md

@@ -19,7 +19,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/end_array.md

@@ -14,7 +14,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/end_object.md

@@ -14,7 +14,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/key.md

@@ -23,7 +23,7 @@ It is safe to move the passed object key value.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/null.md

@@ -14,7 +14,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/number_float.md

@@ -22,7 +22,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/number_integer.md

@@ -19,7 +19,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/number_unsigned.md

@@ -19,7 +19,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/parse_error.md

@@ -27,7 +27,7 @@ Whether parsing should proceed (**must return `#!cpp false`**).
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/start_array.md

@@ -23,7 +23,7 @@ Binary formats may report the number of elements.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/start_object.md

@@ -23,7 +23,7 @@ Binary formats may report the number of elements.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/string.md

@@ -23,7 +23,7 @@ It is safe to move the passed string value.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/macros/json_use_global_udls.md

@@ -21,8 +21,7 @@ When the macro is not defined, the library will define it to its default value.
 
 !!! info "Future behavior change"
 
-    The user-defined string literals will be removed from the global namespace in the next major release of the
+    The user-defined string literals will be removed from the global namespace in the next major release of the library.
-    library.
 
     To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where
     needed. Refer to any of the [string literals](#see-also) for details.
@@ -30,8 +29,8 @@ When the macro is not defined, the library will define it to its default value.
 !!! hint "CMake option"
 
     The placement of user-defined string literals can also be controlled with the CMake option
-    [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default)
+    [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`ON` by default) which defines
-    which defines `JSON_USE_GLOBAL_UDLS` accordingly.
+    `JSON_USE_GLOBAL_UDLS` accordingly.
 
 ## Examples
 

docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md

@@ -4,8 +4,8 @@
 #define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */
 ```
 
-This macro enables the (incorrect) legacy comparison behavior of discarded JSON values.
+This macro enables the (incorrect) legacy comparison behavior of discarded JSON values. Possible values are `1` to
-Possible values are `1` to enable or `0` to disable (default).
+enable or `0` to disable (default).
 
 When enabled, comparisons involving at least one discarded JSON value yield results as follows:
 
@@ -42,19 +42,16 @@ When the macro is not defined, the library will define it to its default value.
         `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`.
       - Overloads for the equality and relational operators emulate the legacy behavior.
 
-    Code outside your control may use either 3-way comparison or the equality and
+    Code outside your control may use either 3-way comparison or the equality and relational operators, resulting in
-    relational operators, resulting in inconsistent and unpredictable behavior.
+    inconsistent and unpredictable behavior.
 
-    See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way
+    See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way comparison.
-    comparison.
 
 !!! warning "Deprecation"
 
-    The legacy comparison behavior is deprecated and may be removed in a future major
+    The legacy comparison behavior is deprecated and may be removed in a future major version release.
-    version release.
 
-    New code should not depend on it and existing code should try to remove or rewrite
+    New code should not depend on it and existing code should try to remove or rewrite expressions relying on it.
-    expressions relying on it.
 
 !!! hint "CMake option"
 

docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md

@@ -7,9 +7,9 @@
 
 These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as
 serialization and want to use the member variable names as object keys in that object. The macro is to be defined
-**inside** the class/struct to create code for.
+**inside** the class/struct to create code for. Unlike
-Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members.
+[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. The first
-The first parameter is the name of the class/struct, and all remaining parameters name the members.
+parameter is the name of the class/struct, and all remaining parameters name the members.
 
 1. Will use [`at`](../basic_json/at.md) during deserialization and will throw
   [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
@@ -40,8 +40,8 @@ See examples below for the concrete generated code.
 
 !!! info "Prerequisites"
 
-    1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy]
+    1. The type `type` must be default constructible. See [How can I use `get()` for non-default
-       for how to overcome this limitation.
+       constructible/non-copyable types?][GetNonDefNonCopy] for how to overcome this limitation.
     2. The macro must be used inside the type (class/struct).
 
 [GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types

docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md

@@ -7,9 +7,9 @@
 
 These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as
 serialization and want to use the member variable names as object keys in that object. The macro is to be defined
-**outside** the class/struct to create code for, but **inside** its namespace.
+**outside** the class/struct to create code for, but **inside** its namespace. Unlike
-Unlike [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members.
+[`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. The first
-The first parameter is the name of the class/struct, and all remaining parameters name the members.
+parameter is the name of the class/struct, and all remaining parameters name the members.
 
 1. Will use [`at`](../basic_json/at.md) during deserialization and will throw
    [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object.
@@ -103,7 +103,8 @@ See examples below for the concrete generated code.
     - `ns::person` is default-constructible. This is a requirement for using the macro.
     - `ns::person` has only public member variables. This makes `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT`
       applicable.
-    - The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its namespace `ns`.
+    - The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its
+      namespace `ns`.
     - A missing key "age" in the deserialization does not yield an exception. Instead, the default value `-1` is used.
 
     The macro is equivalent to:

docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md

@@ -4,19 +4,34 @@
 #define NLOHMANN_JSON_NAMESPACE
 ```
 
-This macro evaluates to the full name of the `nlohmann` namespace, including
+This macro evaluates to the full name of the `nlohmann` namespace, including  the name of a versioned and ABI-tagged
-the name of a versioned and ABI-tagged inline namespace. Use this macro to
+inline namespace. Use this macro to unambiguously refer to the `nlohmann` namespace.
-unambiguously refer to the `nlohmann` namespace.
 
 ## Default definition
 
-The default value consists of a prefix, a version string, and optional ABI tags
+The default value consists of a prefix, a version string, and optional ABI tags depending on whether ABI-affecting
-depending on whether ABI-affecting macros are defined (e.g.,
+macros are defined (e.g., [`JSON_DIAGNOSTICS`](json_diagnostics.md), and
-[`JSON_DIAGNOSTICS`](json_diagnostics.md), and
 [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md)).
 
 When the macro is not defined, the library will define it to its default value.
 
+## Examples
+
+??? example
+
+    The example shows how to use `NLOHMANN_JSON_NAMESPACE` instead of just `nlohmann`, as well as how to output the value
+    of `NLOHMANN_JSON_NAMESPACE`.
+
+    ```cpp
+    --8<-- "examples/nlohmann_json_namespace.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_namespace.output"
+    ```
+
 ## See also
 
 - [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md

@@ -5,9 +5,8 @@
 #define NLOHMANN_JSON_NAMESPACE_END    // (2)
 ```
 
-These macros can be used to open and close the `nlohmann` namespace. They
+These macros can be used to open and close the `nlohmann` namespace. They include an inline namespace used to
-include an inline namespace used to differentiate symbols when linking multiple
+differentiate symbols when linking multiple versions (including different ABI-affecting macros) of this library.
-versions (including different ABI-affecting macros) of this library.
 
 1. Opens the namespace.
     ```cpp
@@ -25,11 +24,26 @@ versions (including different ABI-affecting macros) of this library.
 
 ## Default definition
 
-The default definitions open and close the `nlohmann` as well as an inline
+The default definitions open and close the `nlohmann` as well as an inline  namespace.
-namespace.
 
-When these macros are not defined, the library will define them to their
+When these macros are not defined, the library will define them to their default definitions.
-default definitions.
+
+## Examples
+
+??? example
+
+    The example shows an example how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
+    [How do I convert third-party types?](../../features/arbitrary_types.md#how-do-i-convert-third-party-types) page.
+
+    ```cpp
+    --8<-- "examples/nlohmann_json_namespace_begin.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_namespace_begin.c++17.output"
+    ```
 
 ## See also
 

docs/mkdocs/docs/api/operator_gtgt.md

@@ -21,8 +21,7 @@ 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 
+- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate error.
-  error.
 - Throws [`parse_error.103`](../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
 
 ## Complexity

docs/mkdocs/docs/api/operator_literal_json.md

@@ -15,8 +15,9 @@ using namespace nlohmann::json_literals;
 using namespace nlohmann::literals::json_literals;
 using namespace nlohmann;
 ```
-This is suggested to ease migration to the next major version release of the library.
+
-See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
+This is suggested to ease migration to the next major version release of the library. See
+['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
 
 ## Parameters
 

docs/mkdocs/docs/api/operator_literal_json_pointer.md

@@ -15,8 +15,8 @@ using namespace nlohmann::json_literals;
 using namespace nlohmann::literals::json_literals;
 using namespace nlohmann;
 ```
-This is suggested to ease migration to the next major version release of the library.
+This is suggested to ease migration to the next major version release of the library. See
-See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
+['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details.
 
 ## Parameters
 

docs/mkdocs/docs/api/operator_ltlt.md

@@ -35,7 +35,8 @@ the stream `o`
 ## Exceptions
 
 1. 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`](basic_json/dump.md) member functions, no `error_handler` can be set.
+   value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler`
+   can be set.
 2. None.
 
 ## Complexity

docs/mkdocs/docs/features/arbitrary_types.md

@@ -10,7 +10,7 @@ namespace ns {
         std::string address;
         int age;
     };
-}
+} // namespace ns
 
 ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
 

docs/mkdocs/docs/features/binary_formats/bjdata.md

@@ -1,20 +1,17 @@
 # BJData
 
 The [BJData format](https://neurojson.org) was derived from and improved upon
-[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12).
+[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). Specifically, it introduces an optimized
-Specifically, it introduces an optimized array container for efficient storage
+array container for efficient storage of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers -
-of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers -
+`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to unambiguously map common binary numeric types;
-`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to
+furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid
-unambigiously map common binary numeric types; furthermore, it uses little-endian
-(LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid
 unnecessary conversions on commonly available platforms.
 
-Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and
+Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare
-UBJSON demonstrate a rare combination of being both binary and **quasi-human-readable**. This
+combination of being both binary and **quasi-human-readable**. This is because all semantic elements in BJData and
-is because all semantic elements in BJData and UBJSON, including the data-type markers
+UBJSON, including the data-type markers and name/string types are directly human-readable. Data stored in the
-and name/string types are directly human-readable. Data stored in the BJData/UBJSON format
+BJData/UBJSON format are not only compact in size, fast to read/write, but also can be directly searched or read using
-are not only compact in size, fast to read/write, but also can be directly searched
+simple processing.
-or read using simple processing.
 
 !!! abstract "References"
 
@@ -74,48 +71,40 @@ The library uses the following mapping from JSON values types to BJData types ac
 
 !!! info "NaN/infinity handling"
 
-	If NaN or Infinity are stored inside a JSON number, they are
+    If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the
-    serialized properly. This behavior differs from the `dump()`
+    `dump()` function which serializes NaN or Infinity to `#!json null`.
-    function which serializes NaN or Infinity to `null`.
-
 
 !!! info "Endianness"
 
-	A breaking difference between BJData and UBJSON is the endianness
+    A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data
-    of numerical values. In BJData, all numerical data types (integers
+    types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as
-    `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE)
+    opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on
-    byte order as opposed to big-endian as used by UBJSON. Adopting LE
+    most modern computers where LE is used as the default byte order.
-    to store numeric records avoids unnecessary byte swapping on most modern
-    computers where LE is used as the default byte order.
 
 !!! info "Optimized formats"
 
     Optimized formats for containers are supported via two parameters of
     [`to_bjdata`](../../api/basic_json/to_bjdata.md):
 
-    - Parameter `use_size` adds size information to the beginning of a container and
+    - Parameter `use_size` adds size information to the beginning of a container and removes the closing marker.
-      removes the closing marker.
+    - Parameter `use_type` further checks whether all elements of a container have the same type and adds the type
-    - Parameter `use_type` further checks whether all elements of a container have the
+      marker to the beginning of the container. The `use_type` parameter must only be used together with
-      same type and adds the type marker to the beginning of the container.
+      `use_size = true`.
-      The `use_type` parameter must only be used together with `use_size = true`.
 
-    Note that `use_size = true` alone may result in larger representations -
+    Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the
-    the benefit of this parameter is that the receiving side is
+    receiving side is immediately informed of the number of elements in the container.
-    immediately informed of the number of elements in the container.
 
 !!! info "ND-array optimized format"
 
-	BJData extends UBJSON's optimized array **size** marker to support ND-arrays of
+    BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types
-    uniform numerical data types (referred to as *packed arrays*).
+    (referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested
-    For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored
+    optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to
-    as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`,
+    `[$U#[$i#i2 2 3 1 2 3 4 5 6` or `[$U#[i2 i3] 1 2 3 4 5 6`.
-    can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6`
-    or `[$U#[i2 i3] 1 2 3 4 5 6`.
 
-    To maintina type and size information, ND-arrays are converted to JSON objects following the
+    To maintain type and size information, ND-arrays are converted to JSON objects following the **annotated array
-    **annotated array format** (defined in the [JData specification (Draft 3)][JDataAAFmt]),
+    format** (defined in the [JData specification (Draft 3)][JDataAAFmt]), when parsed using
-    when parsed using [`from_bjdata`](../../api/basic_json/from_bjdata.md).
+    [`from_bjdata`](../../api/basic_json/from_bjdata.md). For example, the above 2-D `uint8` array can be parsed and
-    For example, the above 2-D `uint8` array can be parsed and accessed as
+    accessed as
 
     ```json
     {
@@ -126,34 +115,28 @@ The library uses the following mapping from JSON values types to BJData types ac
     ```
 
     Likewise, when a JSON object in the above form is serialzed using
-    [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted
+    [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted into a compact BJData ND-array. The
-    into a compact BJData ND-array. The only exception is, that when the 1-dimensional
+    only exception is, that when the 1-dimensional vector stored in `"_ArraySize_"` contains a single integer or two
-    vector stored in `"_ArraySize_"` contains a single integer or two integers with one
+    integers with one being 1, a regular 1-D optimized array is generated.
-    being 1, a regular 1-D optimized array is generated.
 
-    The current version of this library does not yet support automatic detection of and
+    The current version of this library does not yet support automatic detection of and conversion from a nested JSON
-    conversion from a nested JSON array input to a BJData ND-array.
+    array input to a BJData ND-array.
 
     [JDataAAFmt]: https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays)
 
 !!! info "Restrictions in optimized data types for arrays and objects"
 
-	Due to diminished space saving, hampered readability, and increased
+    Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data
-    security risks, in BJData, the allowed data types following the `$` marker
+    types following the `$` marker in an optimized array and object container are restricted to
-    in an optimized array and object container are restricted to
+    **non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDC`.
-    **non-zero-fixed-length** data types. Therefore, the valid optimized
+    This also means other variable (`[{SH`) or zero-length types (`TFN`) can not be used in an optimized array or object
-    type markers can only be one of `UiuImlMLhdDC`. This also means other
+    in BJData.
-    variable (`[{SH`) or zero-length types (`TFN`) can not be used in an
-    optimized array or object in BJData.
 
 !!! info "Binary values"
 
-	If the JSON data contains the binary type, the value stored is a list
+    If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the BJData
-    of integers, as suggested by the BJData documentation.  In particular,
+    documentation. In particular, this means that the serialization and the deserialization of JSON containing binary
-    this means that the serialization and the deserialization of JSON
+    values into BJData and back will result in a different JSON object.
-    containing binary values into BJData and back will result in a
-    different JSON object.
-
 
 ??? example
 
@@ -198,7 +181,6 @@ The library maps BJData types to JSON value types as follows:
 
     The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
 
-
 ??? example
 
     ```cpp

docs/mkdocs/docs/features/binary_formats/cbor.md

@@ -11,7 +11,8 @@ small code size, fairly small message size, and extensibility without the need f
 
 ## Serialization
 
-The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049):
+The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification
+([RFC 7049](https://www.rfc-editor.org/rfc/rfc7049.html)):
 
 | JSON value type | value/range                                | CBOR type                         | first byte |
 |-----------------|--------------------------------------------|-----------------------------------|------------|

docs/mkdocs/docs/features/binary_formats/messagepack.md

@@ -1,6 +1,8 @@
 # MessagePack
 
-MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves.
+MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON.
+But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one
+extra byte in addition to the strings themselves.
 
 !!! abstract "References"
 
@@ -9,7 +11,8 @@ MessagePack is an efficient binary serialization format. It lets you exchange da
 
 ## Serialization
 
-The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:
+The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack
+specification:
 
 | JSON value type | value/range                              | MessagePack type | first byte |
 |-----------------|------------------------------------------|------------------|------------|
@@ -64,7 +67,8 @@ The library uses the following mapping from JSON values types to MessagePack typ
 
 !!! info "NaN/infinity handling"
 
-	If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`.
+    If NaN or Infinity are stored inside a JSON number, they are serialized properly in contrast to the
+    [dump](../../api/basic_json/dump.md) function which serializes NaN or Infinity to `null`.
 
 ??? example
 

docs/mkdocs/docs/features/binary_formats/ubjson.md

@@ -1,6 +1,7 @@
 # UBJSON
 
-Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON.
+Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to
+achieve the generality of JSON, combined with being much easier to process than JSON.
 
 !!! abstract "References"
 
@@ -55,31 +56,24 @@ The library uses the following mapping from JSON values types to UBJSON types ac
 
 !!! info "NaN/infinity handling"
 
-	If NaN or Infinity are stored inside a JSON number, they are
+    If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the
-    serialized properly. This behavior differs from the `dump()`
+    `dump()` function which serializes NaN or Infinity to `null`.
-    function which serializes NaN or Infinity to `null`.
 
 !!! info "Optimized formats"
 
-	The optimized formats for containers are supported: Parameter
+    The optimized formats for containers are supported: Parameter `use_size` adds size information to the beginning of a
-    `use_size` adds size information to the beginning of a container and
+    container and removes the closing marker. Parameter `use_type` further checks whether all elements of a container
-    removes the closing marker. Parameter `use_type` further checks
+    have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be
-    whether all elements of a container have the same type and adds the
+    used together with `use_size = true`.
-    type marker to the beginning of the container. The `use_type`
-    parameter must only be used together with `use_size = true`.
 
-    Note that `use_size = true` alone may result in larger representations -
+    Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the
-    the benefit of this parameter is that the receiving side is
+    receiving side is immediately informed on the number of elements of the container.
-    immediately informed on the number of elements of the container.
 
 !!! info "Binary values"
 
-	If the JSON data contains the binary type, the value stored is a list
+    If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON
-    of integers, as suggested by the UBJSON documentation.  In particular,
+    documentation.  In particular, this means that serialization and the deserialization of a JSON containing binary
-    this means that serialization and the deserialization of a JSON
+    values into UBJSON and back will result in a different JSON object.
-    containing binary values into UBJSON and back will result in a
-    different JSON object.
-
 
 ??? example
 
@@ -119,7 +113,6 @@ The library maps UBJSON types to JSON value types as follows:
 
     The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
 
-
 ??? example
 
     ```cpp

docs/mkdocs/docs/features/element_access/unchecked_access.md

@@ -99,7 +99,8 @@ that the passed index is the new maximal index. Intermediate values are filled w
 
 !!! failure "Exceptions"
 
-    `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.
+    `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For
+    other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.
 
 ## Summary
 

docs/mkdocs/docs/features/parsing/parse_exceptions.md

@@ -1,6 +1,10 @@
 # Parsing and Exceptions
 
-When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
+When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown.
+This exception contains the position in the input where the error occurred, together with a diagnostic message and the
+last read input token. The exceptions page contains a
+[list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted
+input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like
 
 ```cpp
 json j;
@@ -19,7 +23,9 @@ In case exceptions are undesired or not supported by the environment, there are
 
 ## Switch off exceptions
 
-The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`).
+The `parse()` function accepts a `#!cpp bool` parameter `allow_exceptions` which controls whether an exception is
+thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned
+(`#!cpp false`).
 
 ```cpp
 json j = json::parse(my_input, nullptr, false);
@@ -33,7 +39,8 @@ Note there is no diagnostic information available in this scenario.
 
 ## Use accept() function
 
-Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON.
+Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating
+whether the input is valid JSON.
 
 ```cpp
 if (!json::accept(my_input))

docs/mkdocs/docs/features/parsing/parser_callbacks.md

@@ -2,9 +2,10 @@
 
 ## Overview
 
-With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events
+With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is
-(passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the
+called on certain events (passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and
-callback function is a boolean indicating whether the element that emitted the callback shall be kept or not.
+context JSON value `parsed`. The return value of the callback function is a boolean indicating whether the element that
+emitted the callback shall be kept or not.
 
 The type of the callback function is:
 
@@ -17,8 +18,8 @@ using parser_callback_t =
 
 ## Callback event types
 
-We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
+We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following
-of the parameters `depth`, `event`, and `parsed`.
+table describes the values of the parameters `depth`, `event`, and `parsed`.
 
 | parameter `event`             | description                                               | parameter `depth`                         | parameter `parsed`               |
 |-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
@@ -59,10 +60,13 @@ of the parameters `depth`, `event`, and `parsed`.
 
 ## Return value
 
-Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called:
+Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which the function
+was called:
 
-- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read.
+- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never
-- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the top-level element is skipped.
+  read.
+- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the
+  top-level element is skipped.
 
 ??? example
 

docs/mkdocs/requirements.txt

@@ -1,49 +1,49 @@
-Babel==2.10.1
+Babel==2.10.3
-certifi==2021.10.8
+certifi==2022.6.15
-charset-normalizer==2.0.12
+charset-normalizer==2.1.0
-click==8.1.2
+click==8.1.3
 csscompressor==0.9.5
 future==0.18.2
-ghp-import==2.0.2
+ghp-import==2.1.0
 gitdb==4.0.9
 GitPython==3.1.27
 htmlmin==0.1.12
 httplib2==0.20.4
 idna==3.3
-importlib-metadata==4.11.3
+importlib-metadata==4.12.0
-Jinja2==3.1.1
+Jinja2==3.1.2
 joblib==1.1.0
 jsmin==3.0.1
 livereload==2.6.3
 lunr==0.6.2
-Markdown==3.3.6
+Markdown==3.4.1
-markdown-include==0.6.0
+markdown-include==0.7.0
 MarkupSafe==2.1.1
 mergedeep==1.3.4
-mkdocs==1.3.0
+mkdocs==1.3.1
-mkdocs-git-revision-date-localized-plugin==1.0.1
+mkdocs-git-revision-date-localized-plugin==1.1.0
-mkdocs-material==8.2.10
+mkdocs-material==8.3.9
 mkdocs-material-extensions==1.0.3
 mkdocs-minify-plugin==0.5.0
-mkdocs-redirects==1.0.4
+mkdocs-redirects==1.0.5
 mkdocs-simple-hooks==0.1.5
 nltk==3.7
 packaging==21.3
 plantuml==0.3.0
 plantuml-markdown==3.6.3
-Pygments==2.11.0
+Pygments==2.12.0
-pymdown-extensions==9.3
+pymdown-extensions==9.5
-pyparsing==3.0.8
+pyparsing==3.0.9
 python-dateutil==2.8.2
 pytz==2022.1
 PyYAML==6.0
 pyyaml_env_tag==0.1
-regex==2022.4.24
+regex==2022.7.25
-requests==2.27.1
+requests==2.28.1
 six==1.16.0
 smmap==5.0.0
-tornado==6.1
+tornado==6.2
 tqdm==4.64.0
-urllib3==1.26.9
+urllib3==1.26.11
-watchdog==2.1.7
+watchdog==2.1.9
-zipp==3.8.0
+zipp==3.8.1

docs/mkdocs/scripts/check_structure.py

@@ -3,6 +3,7 @@
 import glob
 import os.path
 import re
+import sys
 
 warnings = 0
 
@@ -75,6 +76,12 @@ def check_structure():
                 if len(line) > 160 and '|' not in line:
                     report('whitespace/line_length', f'{file}:{lineno+1} ({current_section})', f'line is too long ({len(line)} vs. 160 chars)')
 
+                # sections in `<!-- NOLINT -->` comments are treated as present
+                if line.startswith('<!-- NOLINT'):
+                    current_section = line.strip('<!-- NOLINT')
+                    current_section = current_section.strip(' -->')
+                    existing_sections.append(current_section)
+
                 # check if sections are correct
                 if line.startswith('## '):
                     # before starting a new section, check if the previous one documented all overloads
@@ -167,3 +174,6 @@ if __name__ == '__main__':
     check_structure()
     check_examples()
     print(120 * '-')
+
+    if warnings > 0:
+        sys.exit(1)