From 24606215547fcfdeb942333a1eea88c5d3eab01d Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Tue, 28 Jan 2025 21:34:07 +0100 Subject: [PATCH] :memo: some documentation updates Signed-off-by: Niels Lohmann --- .../api/json_pointer/operator_string_t.md | 4 ++++ docs/mkdocs/docs/api/macros/json_assert.md | 4 ++++ .../api/macros/json_diagnostic_positions.md | 6 ++++++ .../docs/api/macros/json_diagnostics.md | 7 ++++++- .../macros/json_disable_enum_serialization.md | 4 +++- .../docs/api/macros/json_use_global_udls.md | 1 + .../macros/json_use_implicit_conversions.md | 1 + ...n_use_legacy_discarded_value_comparison.md | 4 ++++ docs/mkdocs/docs/features/assertions.md | 4 ++++ docs/mkdocs/docs/features/macros.md | 19 +++++++++++++++++-- 10 files changed, 50 insertions(+), 4 deletions(-) diff --git a/docs/mkdocs/docs/api/json_pointer/operator_string_t.md b/docs/mkdocs/docs/api/json_pointer/operator_string_t.md index 74105a4f1e..89898fa4f6 100644 --- a/docs/mkdocs/docs/api/json_pointer/operator_string_t.md +++ b/docs/mkdocs/docs/api/json_pointer/operator_string_t.md @@ -42,6 +42,10 @@ operator string_t() const --8<-- "examples/json_pointer__operator_string_t.output" ``` +## See also + +- [string_t](../basic_json/string_t.md)- type for strings + ## Version history - Since version 2.0.0. diff --git a/docs/mkdocs/docs/api/macros/json_assert.md b/docs/mkdocs/docs/api/macros/json_assert.md index a093341a1b..a35f794ce0 100644 --- a/docs/mkdocs/docs/api/macros/json_assert.md +++ b/docs/mkdocs/docs/api/macros/json_assert.md @@ -79,6 +79,10 @@ Therefore, assertions can be switched off by defining `NDEBUG`. assertion error in operator[] ``` +## See also + +- [Runtime Assertions](../../features/assertions.md) - overview documentation + ## Version history - Added in version 3.9.0. diff --git a/docs/mkdocs/docs/api/macros/json_diagnostic_positions.md b/docs/mkdocs/docs/api/macros/json_diagnostic_positions.md index 18d0db9933..514a9eeb64 100644 --- a/docs/mkdocs/docs/api/macros/json_diagnostic_positions.md +++ b/docs/mkdocs/docs/api/macros/json_diagnostic_positions.md @@ -108,6 +108,12 @@ When the macro is not defined, the library will define it to its default value. ``` The output shows the exception with diagnostic path info and start/end positions. + +## See also + +- [:simple-cmake: JSON_Diagnostic_Positions](../../integration/cmake.md#json_diagnostic_positions) - CMake option to control the macro +- [JSON_DIAGNOSTICS](json_diagnostics.md) - macro to control extended diagnostics + ## Version history - Added in version 3.12.0. diff --git a/docs/mkdocs/docs/api/macros/json_diagnostics.md b/docs/mkdocs/docs/api/macros/json_diagnostics.md index 0a3aa5599e..3a553a5a1b 100644 --- a/docs/mkdocs/docs/api/macros/json_diagnostics.md +++ b/docs/mkdocs/docs/api/macros/json_diagnostics.md @@ -82,7 +82,12 @@ When the macro is not defined, the library will define it to its default value. --8<-- "examples/diagnostic_positions_exception.output" ``` The output shows the exception with start/end positions only. - + +## See also + +- [:simple-cmake: JSON_Diagnostics](../../integration/cmake.md#json_diagnostics) - CMake option to control the macro +- [JSON_DIAGNOSTIC_POSITIONS](json_diagnostic_positions.md) - macro to access positions of elements + ## Version history - Added in version 3.10.0. diff --git a/docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md b/docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md index 6440e34e32..6acfdc2a1c 100644 --- a/docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md +++ b/docs/mkdocs/docs/api/macros/json_disable_enum_serialization.md @@ -145,7 +145,9 @@ The default value is `0`. ## See also -- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) +- [:simple-cmake: JSON_DisableEnumSerialization](../../integration/cmake.md#json_disableenumserialization) - CMake option to control + the macro +- [`NLOHMANN_JSON_SERIALIZE_ENUM`](nlohmann_json_serialize_enum.md) - serialize/deserialize an enum ## Version history diff --git a/docs/mkdocs/docs/api/macros/json_use_global_udls.md b/docs/mkdocs/docs/api/macros/json_use_global_udls.md index 69db9e77c3..3110d4662d 100644 --- a/docs/mkdocs/docs/api/macros/json_use_global_udls.md +++ b/docs/mkdocs/docs/api/macros/json_use_global_udls.md @@ -92,6 +92,7 @@ When the macro is not defined, the library will define it to its default value. - [`operator""_json`](../operator_literal_json.md) - [`operator""_json_pointer`](../operator_literal_json_pointer.md) +- [:simple-cmake: JSON_GlobalUDLs](../../integration/cmake.md#json_globaludls) - CMake option to control the macro ## Version history diff --git a/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md b/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md index 4d962c2ee8..0a5ad4df46 100644 --- a/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md +++ b/docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md @@ -53,6 +53,7 @@ By default, implicit conversions are enabled. - [**operator ValueType**](../basic_json/operator_ValueType.md) - get a value (implicit) - [**get**](../basic_json/get.md) - get a value (explicit) +- [:simple-cmake: JSON_ImplicitConversions](../../integration/cmake.md#json_implicitconversions) - CMake option to control the macro ## Version history diff --git a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md index 65f3f1767d..b14266304a 100644 --- a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md +++ b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md @@ -72,6 +72,10 @@ When the macro is not defined, the library will define it to its default value. ... ``` +### See also + +- [:simple-cmake: JSON_LegacyDiscardedValueComparison](../../integration/cmake.md#json_legacydiscardedvaluecomparison) - CMake option to control the macro + ## Version history - Added in version 3.11.0. diff --git a/docs/mkdocs/docs/features/assertions.md b/docs/mkdocs/docs/features/assertions.md index 32b4e019b1..9f62249a2e 100644 --- a/docs/mkdocs/docs/features/assertions.md +++ b/docs/mkdocs/docs/features/assertions.md @@ -138,3 +138,7 @@ result in undefined behavior. Since version 3.11.4, this library checks for `nul ``` [json.exception.parse_error.101] parse error: attempting to parse an empty input; check that your input string or stream contains the expected JSON ``` + +## See also + +- [JSON_ASSERT](../api/macros/json_assert.md) - control behavior of runtime assertions diff --git a/docs/mkdocs/docs/features/macros.md b/docs/mkdocs/docs/features/macros.md index 488261a65c..211f064b96 100644 --- a/docs/mkdocs/docs/features/macros.md +++ b/docs/mkdocs/docs/features/macros.md @@ -24,11 +24,26 @@ When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to th exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead. -The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets -`JSON_DIAGNOSTICS` accordingly. +The diagnostics messages can also be controlled with the CMake option +[`JSON_Diagnostics`](../integration/cmake.md#json_diagnostics) (`OFF` by default) which sets `JSON_DIAGNOSTICS` +accordingly. See [full documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). +## `JSON_DIAGNOSTIC_POSITIONS` + +When enabled, two new member functions [`start_pos()`](../api/basic_json/start_pos.md) and +[`end_pos()`](../api/basic_json/end_pos.md) are added to [`basic_json`](../api/basic_json/index.md) values. If the value +was created by calling the[`parse`](../api/basic_json/parse.md) function, then these functions allow to query the byte +positions of the value in the input it was parsed from. The byte positions are also used in exceptions to help locate +errors. + +The diagnostics positions can also be controlled with the CMake option +[`JSON_Diagnostic_Positions`](../integration/cmake.md#json_diagnostic_positions) (`OFF` by default) which sets +`JSON_DIAGNOSTIC_POSITIONS` accordingly. + +See [full documentation of `JSON_DIAGNOSTIC_POSITIONS`](../api/macros/json_diagnostic_positions.md) + ## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20` The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view`