Review and extend the documentation, and check it in CI

A review of all documentation pages found factual errors, dead links, missing cross-references, and gaps in examples. This fixes them and adds checks so the same problems are caught automatically. Fixes: - wrong signatures and version histories (operator!= C++20 member, binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...) - stale descriptions (number parsing since #5283, UBJSON table, SAX example that no longer compiled, tsl::ordered_map advice) - dead internal and external links; repology.org badges (the domain is suspended) replaced by badges that query the registries directly - deprecation notes link the migration guide; the guide itself fixed Additions: - "See also" sections, cross-references, 25 runnable examples, 12 Mermaid diagrams, new API pages for json_pointer::operator<=> and byte_container_with_subtype::operator==/!= - landing page, guides for untrusted input and performance - "unreleased" badge after versions newer than the latest release Checks: - strict documentation build (broken links/anchors fail it); CI and the publish workflow fetch the full history the build needs - weekly external link check, Mermaid syntax check in CI - check_structure.py: example titles, heading levels, alt texts, header links, docset index coverage; its unused-example check works again - all examples produce the same output on every platform Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-04 21:50:33 +00:00 · 2026-09-29 17:05:35 +02:00
parent 633de8e44b
commit 526b6d3fd6
271 changed files with 5227 additions and 608 deletions
@@ -41,7 +41,7 @@ Exceptions are used widely within the library. They can, however, be switched of

 Note that [`JSON_THROW_USER`](../api/macros/json_throw_user.md) should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.

-??? example
+??? example "Example: switch off exceptions and log errors before aborting"

    The code below switches off exceptions and creates a log entry with a detailed error message in case of errors.

@@ -67,7 +67,7 @@ See [documentation of `JSON_TRY_USER`, `JSON_CATCH_USER` and `JSON_THROW_USER`](

 Exceptions in the library are thrown in the local context of the JSON value they are detected. This makes detailed diagnostics messages, and hence debugging, difficult.

-??? example
+??? example "Example: standard diagnostic message"

    ```cpp
    --8<-- "examples/diagnostics_standard.cpp"
@@ -85,7 +85,7 @@ To create better diagnostics messages, each JSON value needs a pointer to its pa

 As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) to `1` before including `json.hpp`.

-??? example
+??? example "Example: extended diagnostic message with `JSON_DIAGNOSTICS`"

    ```cpp
    --8<-- "examples/diagnostics_extended.cpp"
@@ -118,7 +118,7 @@ Exceptions have ids 1xx.
    is the index of the terminating null byte or the end of file. This also
    holds true when reading a byte vector (CBOR or MessagePack).

-??? example
+??? example "Example: catch a `parse_error` exception"

    The following code shows how a `parse_error` exception can be caught.

@@ -395,7 +395,7 @@ the expected semantics.

 Exceptions have ids 2xx.

-??? example
+??? example "Example: catch an `invalid_iterator` exception"

    The following code shows how an `invalid_iterator` exception can be caught.

@@ -421,7 +421,7 @@ The iterators passed to constructor `basic_json(InputIT first, InputIT last)` ar

 ### json.exception.invalid_iterator.202

-In the [erase](../api/basic_json/erase.md) or insert function, the passed iterator `pos` does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.
+In the [erase](../api/basic_json/erase.md) or [insert](../api/basic_json/insert.md) function, the passed iterator `pos` does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.

 !!! failure "Example messages"

@@ -454,7 +454,7 @@ When an iterator range for a primitive type (number, boolean, or string) is pass

 ### json.exception.invalid_iterator.205

-When an iterator for a primitive type (number, boolean, or string) is passed to an [erase](../api/basic_json/erase.md) function, the iterator has to be the `begin()` iterator, because it is the only way to address the stored value. All other iterators are invalid.
+When an iterator for a primitive type (number, boolean, or string) is passed to an [erase](../api/basic_json/erase.md) function, the iterator has to be the [`begin()`](../api/basic_json/begin.md) iterator, because it is the only way to address the stored value. All other iterators are invalid.

 !!! failure "Example message"

@@ -545,7 +545,7 @@ The order of object iterators cannot be compared, because JSON objects are unord

 ### json.exception.invalid_iterator.214

-Cannot retrieve value from iterator: The iterator either refers to a null value, or it refers to a primitive type (number, boolean, or string), but does not match the iterator returned by `begin()`.
+Cannot retrieve value from iterator: The iterator either refers to a null value, or it refers to a primitive type (number, boolean, or string), but does not match the iterator returned by [`begin()`](../api/basic_json/begin.md).

 !!! failure "Example message"

@@ -559,7 +559,7 @@ This exception is thrown in case of a type error; that is, a library function is

 Exceptions have ids 3xx.

-??? example
+??? example "Example: catch a `type_error` exception"

    The following code shows how a `type_error` exception can be caught.

@@ -611,7 +611,7 @@ To retrieve a reference to a value stored in a `basic_json` object with `get_ref

 ### json.exception.type_error.304

-The `at()` member functions can only be executed for certain JSON types.
+The [`at()`](../api/basic_json/at.md) member functions can only be executed for certain JSON types.

 !!! failure "Example messages"

@@ -624,7 +624,7 @@ The `at()` member functions can only be executed for certain JSON types.

 ### json.exception.type_error.305

-The `operator[]` member functions can only be executed for certain JSON types.
+The [`operator[]`](../api/basic_json/operator%5B%5D.md) member functions can only be executed for certain JSON types.

 !!! failure "Example messages"

@@ -637,7 +637,7 @@ The `operator[]` member functions can only be executed for certain JSON types.

 ### json.exception.type_error.306

-The `value()` member functions can only be executed for certain JSON types.
+The [`value()`](../api/basic_json/value.md) member functions can only be executed for certain JSON types.

 !!! failure "Example message"

@@ -657,7 +657,7 @@ The [`erase()`](../api/basic_json/erase.md) member functions can only be execute

 ### json.exception.type_error.308

-The `push_back()` and `operator+=` member functions can only be executed for certain JSON types.
+The [`push_back()`](../api/basic_json/push_back.md) and [`operator+=`](../api/basic_json/operator+=.md) member functions can only be executed for certain JSON types.

 !!! failure "Example message"

@@ -667,7 +667,7 @@ The `push_back()` and `operator+=` member functions can only be executed for cer

 ### json.exception.type_error.309

-The `insert()` member functions can only be executed for certain JSON types.
+The [`insert()`](../api/basic_json/insert.md) member functions can only be executed for certain JSON types.

 !!! failure "Example messages"

@@ -680,7 +680,7 @@ The `insert()` member functions can only be executed for certain JSON types.

 ### json.exception.type_error.310

-The `swap()` member functions can only be executed for certain JSON types.
+The [`swap()`](../api/basic_json/swap.md) member functions can only be executed for certain JSON types.

 !!! failure "Example message"

@@ -690,7 +690,7 @@ The `swap()` member functions can only be executed for certain JSON types.

 ### json.exception.type_error.311

-The `emplace()` and `emplace_back()` member functions can only be executed for certain JSON types.
+The [`emplace()`](../api/basic_json/emplace.md) and [`emplace_back()`](../api/basic_json/emplace_back.md) member functions can only be executed for certain JSON types.

 !!! failure "Example messages"

@@ -703,7 +703,7 @@ The `emplace()` and `emplace_back()` member functions can only be executed for c

 ### json.exception.type_error.312

-The `update()` member functions can only be executed for certain JSON types.
+The [`update()`](../api/basic_json/update.md) member functions can only be executed for certain JSON types.

 !!! failure "Example message"

@@ -713,7 +713,7 @@ The `update()` member functions can only be executed for certain JSON types.

 ### json.exception.type_error.313

-The `unflatten` function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well-defined.
+The [`unflatten()`](../api/basic_json/unflatten.md) function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well-defined.

 !!! failure "Example message"

@@ -723,7 +723,7 @@ The `unflatten` function converts an object whose keys are JSON Pointers back in

 ### json.exception.type_error.314

-The `unflatten` function only works for an object whose keys are JSON Pointers.
+The [`unflatten()`](../api/basic_json/unflatten.md) function only works for an object whose keys are JSON Pointers.

 !!! failure "Example message"

@@ -735,7 +735,7 @@ The `unflatten` function only works for an object whose keys are JSON Pointers.

 ### json.exception.type_error.315

-The `unflatten()` function only works for an object whose keys are JSON Pointers and whose values are primitive.
+The [`unflatten()`](../api/basic_json/unflatten.md) function only works for an object whose keys are JSON Pointers and whose values are primitive.

 !!! failure "Example message"

@@ -747,7 +747,7 @@ The `unflatten()` function only works for an object whose keys are JSON Pointers

 ### json.exception.type_error.316

-The `dump()` function only works with UTF-8 encoded strings; that is, if you assign a `std::string` to a JSON value, make sure it is UTF-8 encoded.
+The [`dump()`](../api/basic_json/dump.md) function only works with UTF-8 encoded strings; that is, if you assign a `std::string` to a JSON value, make sure it is UTF-8 encoded. See the FAQ entry on [serializing untrusted or invalid UTF-8](faq.md#serializing-untrusted-or-invalid-utf-8) for background and the recommended fix.

 !!! failure "Example message"

@@ -788,7 +788,7 @@ This exception is thrown in case a library function is called on an input parame

 Exceptions have ids 4xx.

-??? example
+??? example "Example: catch an `out_of_range` exception"

    The following code shows how an `out_of_range` exception can be caught.

@@ -1009,7 +1009,7 @@ other exception types.

 Exceptions have ids 5xx.

-??? example
+??? example "Example: catch an `other_error` exception"

    The following code shows how an `other_error` exception can be caught.