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,24 +1,21 @@
 # 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"
 
-	- [BJData Specification](https://neurojson.org/bjdata/draft2)
+    - [BJData Specification](https://neurojson.org/bjdata/draft2)
 
 ## Serialization
 
@@ -55,67 +52,59 @@ The library uses the following mapping from JSON values types to BJData types ac
 
 !!! success "Complete mapping"
 
-	The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value.
+    The mapping is **complete** in the sense that any JSON value type can be converted to a BJData value.
 
-	Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`.
+    Any BJData output created by `to_bjdata` can be successfully parsed by `from_bjdata`.
 
 !!! warning "Size constraints"
 
-	The following values can **not** be converted to a BJData value:
+    The following values can **not** be converted to a BJData value:
 
       - strings with more than 18446744073709551615 bytes, i.e., $2^{64}-1$ bytes (theoretical)
 
 !!! info "Unused BJData markers"
 
-	The following markers are not used in the conversion:
+    The following markers are not used in the conversion:
 
     - `Z`: no-op values are not created.
     - `C`: single-byte strings are serialized with `S` markers.
 
 !!! 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
+    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
 
@@ -196,8 +179,7 @@ The library maps BJData types to JSON value types as follows:
 
 !!! success "Complete mapping"
 
-	The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
+    The mapping is **complete** in the sense that any BJData value can be converted to a JSON value.
-
 
 ??? example
 

docs/mkdocs/docs/features/binary_formats/bson.md

@@ -6,8 +6,8 @@ representation of data types that are not part of the JSON spec. For example, BS
 
 !!! abstract "References"
 
-	- [BSON Website](http://bsonspec.org) - the main source on BSON
+    - [BSON Website](http://bsonspec.org) - the main source on BSON
-	- [BSON Specification](http://bsonspec.org/spec.html) - the specification
+    - [BSON Specification](http://bsonspec.org/spec.html) - the specification
    
 
 ## Serialization

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

@@ -5,13 +5,14 @@ small code size, fairly small message size, and extensibility without the need f
 
 !!! abstract "References"
 
-  	- [CBOR Website](http://cbor.io) - the main source on CBOR
+      - [CBOR Website](http://cbor.io) - the main source on CBOR
     - [CBOR Playground](http://cbor.me) - an interactive webpage to translate between JSON and CBOR
     - [RFC 7049](https://tools.ietf.org/html/rfc7049) - the CBOR specification
 
 ## 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 |
 |-----------------|--------------------------------------------|-----------------------------------|------------|
@@ -61,15 +62,15 @@ see "binary" cells in the table above.
 
 !!! success "Complete mapping"
 
-	The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value.
+    The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value.
 
 !!! info "NaN/infinity handling"
 
-	If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`.
+    If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`.
 
 !!! info "Unused CBOR types"
 
-	The following CBOR types are not used in the conversion:
+    The following CBOR types are not used in the conversion:
 
       - UTF-8 strings terminated by "break" (0x7F)
       - arrays terminated by "break" (0x9F)
@@ -149,7 +150,7 @@ The library maps CBOR types to JSON value types as follows:
 
 !!! warning "Incomplete mapping"
 
-	The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:
+    The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors:
 
      - date/time (0xC0..0xC1)
      - bignum (0xC2..0xC3)
@@ -161,7 +162,7 @@ The library maps CBOR types to JSON value types as follows:
 
 !!! warning "Object keys"
 
-	CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
+    CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
 
 !!! warning "Tagged items"
 

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

@@ -1,15 +1,18 @@
 # 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"
 
-	- [MessagePack website](https://msgpack.org)
+    - [MessagePack website](https://msgpack.org)
-	- [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md)
+    - [MessagePack specification](https://github.com/msgpack/msgpack/blob/master/spec.md)
 
 ## 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 |
 |-----------------|------------------------------------------|------------------|------------|
@@ -49,22 +52,23 @@ The library uses the following mapping from JSON values types to MessagePack typ
 
 !!! success "Complete mapping"
 
-	The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value.
+    The mapping is **complete** in the sense that any JSON value type can be converted to a MessagePack value.
 
-	Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
+    Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
 
 !!! warning "Size constraints"
 
-	The following values can **not** be converted to a MessagePack value:
+    The following values can **not** be converted to a MessagePack value:
 
-	  - strings with more than 4294967295 bytes
+      - strings with more than 4294967295 bytes
-	  - byte strings with more than 4294967295 bytes
+      - byte strings with more than 4294967295 bytes
-	  - arrays with more than 4294967295 elements
+      - arrays with more than 4294967295 elements
-	  - objects with more than 4294967295 elements
+      - objects with more than 4294967295 elements
 
 !!! 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
 
@@ -123,7 +127,7 @@ The library maps MessagePack types to JSON value types as follows:
 
 !!! info
 
-	Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
+    Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
 
 
 ??? example

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

@@ -1,10 +1,11 @@
 # 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"
 
-	- [UBJSON Website](http://ubjson.org)
+    - [UBJSON Website](http://ubjson.org)
 
 ## Serialization
 
@@ -36,50 +37,43 @@ The library uses the following mapping from JSON values types to UBJSON types ac
 
 !!! success "Complete mapping"
 
-	The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value.
+    The mapping is **complete** in the sense that any JSON value type can be converted to a UBJSON value.
 
-	Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`.
+    Any UBJSON output created by `to_ubjson` can be successfully parsed by `from_ubjson`.
 
 !!! warning "Size constraints"
 
-	The following values can **not** be converted to a UBJSON value:
+    The following values can **not** be converted to a UBJSON value:
 
       - strings with more than 9223372036854775807 bytes (theoretical)
 
 !!! info "Unused UBJSON markers"
 
-	The following markers are not used in the conversion:
+    The following markers are not used in the conversion:
     
     - `Z`: no-op values are not created.
     - `C`: single-byte strings are serialized with `S` markers.
 
 !!! 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
 
@@ -117,8 +111,7 @@ The library maps UBJSON types to JSON value types as follows:
 
 !!! success "Complete mapping"
 
-	The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
+    The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
-
 
 ??? example
 

docs/mkdocs/docs/features/comments.md

@@ -5,9 +5,9 @@ This library does not support comments *by default*. It does so for three reason
 1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
 2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
 
-	> 	I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.  I know that the lack of comments makes some people sad, but it shouldn't. 
+    >     I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.  I know that the lack of comments makes some people sad, but it shouldn't. 
 
-	> 	Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
+    >     Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
 
 3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
 

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/docs/home/faq.md

@@ -44,7 +44,7 @@ for objects.
 
 !!! question
 
-	Can you add an option to ignore trailing commas?
+    Can you add an option to ignore trailing commas?
 
 This library does not support any feature which would jeopardize interoperability.
 
@@ -53,9 +53,9 @@ This library does not support any feature which would jeopardize interoperabilit
 
 !!! question "Questions"
 
-	- Why is the parser complaining about a Chinese character?
+    - Why is the parser complaining about a Chinese character?
-	- Does the library support Unicode?
+    - Does the library support Unicode?
-	- I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"`
+    - I get an exception `[json.exception.parse_error.101] parse error at line 1, column 53: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"Testé$')"`
 
 The library supports **Unicode input** as follows:
 
@@ -124,7 +124,7 @@ Yes, see [Parsing and exceptions](../features/parsing/parse_exceptions.md).
 
 !!! question
 
-	Can I get the key of the object item that caused an exception?
+    Can I get the key of the object item that caused an exception?
 
 Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to get [extended diagnostics messages](exceptions.md#extended-diagnostic-messages).
 
@@ -136,18 +136,18 @@ Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_d
 
 !!! question
 
-	- It seems that precision is lost when serializing a double.
+    - It seems that precision is lost when serializing a double.
-	- Can I change the precision for floating-point serialization?
+    - Can I change the precision for floating-point serialization?
 
 The library uses `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) digits for serialization. This value is sufficient to guarantee roundtripping. If one uses more than this number of digits of precision, then string -> value -> string is not guaranteed to round-trip.
 
 !!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)"
 
-	The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow. 
+    The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow. 
 
 !!! tip
 
-	The website https://float.exposed gives a good insight into the internal storage of floating-point numbers.
+    The website https://float.exposed gives a good insight into the internal storage of floating-point numbers.
 
 See [this section](../features/types/number_handling.md#number-serialization) on the library's number handling for more information.
 
@@ -157,7 +157,7 @@ See [this section](../features/types/number_handling.md#number-serialization) on
 
 !!! question
 
-	Why does the code not compile with Android SDK?
+    Why does the code not compile with Android SDK?
 
 Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your `Application.mk`. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
 
@@ -174,7 +174,7 @@ The code compiles successfully with [Android NDK](https://developer.android.com/
 
 !!! question "Questions"
 
-	- Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)?
+    - Why do I get a compilation error `'to_string' is not a member of 'std'` (or similarly, for `strtod` or `strtof`)?
-	- Why does the code not compile with MinGW or Android SDK?
+    - Why does the code not compile with MinGW or Android SDK?
 
 This is not an issue with the code,  but rather with the compiler itself. On Android, see above to build with a newer environment.  For MinGW, please refer to [this site](http://tehsausage.com/mingw-to-string) and [this discussion](https://github.com/nlohmann/json/issues/136) for information on how to fix this bug. For Android NDK using `APP_STL := gnustl_static`, please refer to [this discussion](https://github.com/nlohmann/json/issues/219).

docs/mkdocs/docs/home/releases.md

@@ -252,18 +252,18 @@ http://nlohmann.github.io/json/doxygen/classnlohmann_1_1basic__json_a0a45fc74063
 - Fixed documentation of parse function. #1473
 - Suppressed warning that cannot be fixed inside the library. #1401 #1468
 - Imroved package manager suppert:
-	- Updated Buckaroo instructions. #1495
+    - Updated Buckaroo instructions. #1495
-	- Improved Meson support. #1463
+    - Improved Meson support. #1463
-	- Added Conda package manager documentation. #1430
+    - Added Conda package manager documentation. #1430
-	- Added NuGet package manager documentation. #1132
+    - Added NuGet package manager documentation. #1132
 - Continuous Integration
-	- Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder.
+    - Removed unstable or deprecated Travis builders (Xcode 6.4 - 8.2) and added Xcode 10.1 builder.
-	- Added Clang 7 to Travis CI.
+    - Added Clang 7 to Travis CI.
-	- Fixed AppVeyor x64 builds. #1374 #1414
+    - Fixed AppVeyor x64 builds. #1374 #1414
 - Updated thirdparty libraries:
-	- Catch 1.12.0 -> 1.12.2
+    - Catch 1.12.0 -> 1.12.2
-	- Google Benchmark 1.3.0 -> 1.4.1
+    - Google Benchmark 1.3.0 -> 1.4.1
-	- Doxygen 1.8.15 -> 1.8.16
+    - Doxygen 1.8.15 -> 1.8.16
 
 ### :fire: Deprecated functions
 

docs/mkdocs/docs/integration/cmake.md

@@ -119,7 +119,7 @@ automatically download a release as a dependency at configure type.
     )
     ```
 
-	However, the repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on
+    However, the repository <https://github.com/nlohmann/json> download size is quite large. You might want to depend on
     a smaller repository. For instance, you might want to replace the URL in the example by
     <https://github.com/ArthurSonzogni/nlohmann_json_cmake_fetchcontent>.
 

docs/mkdocs/docs/integration/package_managers.md

@@ -30,29 +30,29 @@ instead. See [nlohmann-json](https://formulae.brew.sh/formula/nlohmann-json) for
 
 ??? example
 
-	1. Create the following file:
+    1. Create the following file:
 
         ```cpp title="example.cpp"
         --8<-- "integration/example.cpp"
         ```
 
-	2. Install the package
+    2. Install the package
 
-		```sh
+        ```sh
-		brew install nlohmann-json
+        brew install nlohmann-json
-		```
+        ```
 
-	3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with
+    3. Determine the include path, which defaults to `/usr/local/Cellar/nlohmann-json/$version/include`, where `$version` is the version of the library, e.g. `3.7.3`. The path of the library can be determined with
 
-		```sh
+        ```sh
-		brew list nlohmann-json
+        brew list nlohmann-json
-		```
+        ```
 
-	4. Compile the code. For instance, the code can be compiled using Clang with
+    4. Compile the code. For instance, the code can be compiled using Clang with
 
-		```sh
+        ```sh
-		clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example
+        clang++ example.cpp -I/usr/local/Cellar/nlohmann-json/3.7.3/include -std=c++11 -o example
-		```
+        ```
 
 :material-update: The [formula](https://formulae.brew.sh/formula/nlohmann-json) is updated automatically.
 
@@ -68,7 +68,7 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
 
 ??? example
 
-	1. Create the following files:
+    1. Create the following files:
 
         ```ini title="Conanfile.txt"
         --8<-- "integration/conan/Conanfile.txt"
@@ -82,15 +82,15 @@ If you are using [Conan](https://www.conan.io/) to manage your dependencies, mer
         --8<-- "integration/conan/example.cpp"
         ```
 
-	2. Build:
+    2. Build:
 
-		```sh
+        ```sh
-		mkdir build
+        mkdir build
-		cd build
+        cd build
-		conan install ..
+        conan install ..
-		cmake ..
+        cmake ..
-		cmake --build .
+        cmake --build .
-		```
+        ```
 
 :material-update: The [package](https://conan.io/center/nlohmann_json) is updated automatically.
 
@@ -112,7 +112,7 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
 
 ??? example
 
-	1. Create the following files:
+    1. Create the following files:
 
         ```cmake title="CMakeLists.txt"
         --8<-- "integration/vcpkg/CMakeLists.txt"
@@ -128,14 +128,14 @@ If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project fo
         vcpkg install nlohmann-json
         ```
 
-	3. Build:
+    3. Build:
 
-		```sh
+        ```sh
-		mkdir build
+        mkdir build
-		cd build
+        cd build
-		cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
+        cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
-		cmake --build .
+        cmake --build .
-		```
+        ```
 
     Note you need to adjust `/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake` to your system.
 

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)