From f67b3de5c441b3dbfd0cc33fcfebf64c7d96abab Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Thu, 9 Jul 2026 12:45:11 +0200
Subject: [PATCH] :memo: Fix documentation gaps for 3.13.0 release (todos
 138-142)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Todo 138: Add "Known issues" section to modules.md with compiler-specific troubleshooting (GCC redefinition, MSVC symbol export). Add pointer note to quality_assurance.md.
- Todo 139: Document CBOR/MessagePack half-precision float encoding for NaN/Infinity (0xF9/0xCA with exact byte sequences). Explain pre-3.13.0 double-precision bug mechanism without issue citations.
- Todo 140: Document CBOR negative-integer-overflow rejection (parse_error.112) for magnitudes exceeding int64_t range (already implemented in rev 1).
- Todo 141: Update version history in value.md and operator[].md with behavior-change details, removing issue citations per citation policy (prose is self-contained).
- Todo 142: Global sed replace of 3.12.x → 3.13.0 placeholder across all 20 documentation files.

Revision 2 incorporates feedback to reduce changelog-like issue citations. Only citations that add unique troubleshooting value are retained (#5103 for GCC workaround, #3970 for MSVC symbol export). "Known issues" section follows PR #5252's visual pattern (info admonition with bold-bullet format).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 docs/mkdocs/docs/api/basic_json/accept.md     |  2 +-
 docs/mkdocs/docs/api/basic_json/format_as.md  |  2 +-
 docs/mkdocs/docs/api/basic_json/operator[].md |  3 ++-
 docs/mkdocs/docs/api/basic_json/parse.md      |  2 +-
 docs/mkdocs/docs/api/basic_json/patch.md      |  2 +-
 .../docs/api/basic_json/patch_inplace.md      |  2 +-
 docs/mkdocs/docs/api/basic_json/sax_parse.md  |  2 +-
 .../docs/api/basic_json/std_formatter.md      |  2 +-
 docs/mkdocs/docs/api/basic_json/value.md      |  4 +++-
 docs/mkdocs/docs/api/json_pointer/front.md    |  2 +-
 .../mkdocs/docs/api/json_pointer/pop_front.md |  2 +-
 .../docs/api/json_pointer/push_front.md       |  2 +-
 .../macros/json_brace_init_copy_semantics.md  |  2 +-
 .../mkdocs/docs/api/macros/json_has_cpp_11.md |  2 +-
 .../docs/api/macros/json_has_std_format.md    |  2 +-
 .../macros/nlohmann_define_type_with_names.md |  2 +-
 .../nlohmann_json_serialize_enum_strict.md    |  2 +-
 docs/mkdocs/docs/api/operator_literal_json.md |  2 +-
 .../docs/api/operator_literal_json_pointer.md |  2 +-
 .../docs/community/quality_assurance.md       |  2 ++
 .../docs/features/binary_formats/cbor.md      | 17 ++++++++++++++++-
 .../features/binary_formats/messagepack.md    | 11 +++++++++--
 docs/mkdocs/docs/features/modules.md          | 19 +++++++++++++++++++
 docs/mkdocs/docs/home/exceptions.md           |  5 ++++-
 docs/mkdocs/docs/home/faq.md                  |  2 +-
 25 files changed, 73 insertions(+), 24 deletions(-)

diff --git a/docs/mkdocs/docs/api/basic_json/accept.md b/docs/mkdocs/docs/api/basic_json/accept.md
index 9e495cdef..74c006665 100644
--- a/docs/mkdocs/docs/api/basic_json/accept.md
+++ b/docs/mkdocs/docs/api/basic_json/accept.md
@@ -109,7 +109,7 @@ A UTF-8 byte order mark is silently ignored.
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
-- Added `ignore_trailing_commas` in version 3.12.x.
+- Added `ignore_trailing_commas` in version 3.13.0.
 
 !!! warning "Deprecation"
 
diff --git a/docs/mkdocs/docs/api/basic_json/format_as.md b/docs/mkdocs/docs/api/basic_json/format_as.md
index b35d0ddcd..1d20416c3 100644
--- a/docs/mkdocs/docs/api/basic_json/format_as.md
+++ b/docs/mkdocs/docs/api/basic_json/format_as.md
@@ -92,4 +92,4 @@ std::string format_as(const BasicJsonType& j)
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json/operator[].md b/docs/mkdocs/docs/api/basic_json/operator[].md
index 5109cdcac..4df77f14b 100644
--- a/docs/mkdocs/docs/api/basic_json/operator[].md
+++ b/docs/mkdocs/docs/api/basic_json/operator[].md
@@ -251,5 +251,6 @@ Strong exception safety: if an exception occurs, the original value stays intact
 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.
-3. Added in version 3.11.0.
+3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
+   already supported by [`at`](at.md), [`value`](value.md), [`find`](find.md), and other lookup functions.
 4. Added in version 2.0.0.
diff --git a/docs/mkdocs/docs/api/basic_json/parse.md b/docs/mkdocs/docs/api/basic_json/parse.md
index 4da93ae42..4291d6931 100644
--- a/docs/mkdocs/docs/api/basic_json/parse.md
+++ b/docs/mkdocs/docs/api/basic_json/parse.md
@@ -235,7 +235,7 @@ Invalid Unicode escapes and unpaired surrogates in the input are reported as
 - Overload for contiguous containers (1) added in version 2.0.3.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
-- Added `ignore_trailing_commas` in version 3.12.x.
+- Added `ignore_trailing_commas` in version 3.13.0.
 
 !!! warning "Deprecation"
 
diff --git a/docs/mkdocs/docs/api/basic_json/patch.md b/docs/mkdocs/docs/api/basic_json/patch.md
index 1ec517461..432e7c128 100644
--- a/docs/mkdocs/docs/api/basic_json/patch.md
+++ b/docs/mkdocs/docs/api/basic_json/patch.md
@@ -74,4 +74,4 @@ is thrown. In any case, the original value is not changed: the patch is applied
 
 - Added in version 2.0.0.
 - Added [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's
-  target location has a non-object/non-array parent in version 3.12.x.
+  target location has a non-object/non-array parent in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json/patch_inplace.md b/docs/mkdocs/docs/api/basic_json/patch_inplace.md
index 8f88c612f..ae2b5e6a9 100644
--- a/docs/mkdocs/docs/api/basic_json/patch_inplace.md
+++ b/docs/mkdocs/docs/api/basic_json/patch_inplace.md
@@ -71,4 +71,4 @@ function throws an exception.
 
 - Added in version 3.11.0.
 - Added [`out_of_range.411`](../../home/exceptions.md#jsonexceptionout_of_range411) and stopped relying on an internal assertion when an "add" operation's
-  target location has a non-object/non-array parent in version 3.12.x.
+  target location has a non-object/non-array parent in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json/sax_parse.md b/docs/mkdocs/docs/api/basic_json/sax_parse.md
index f0900941c..e93e850f2 100644
--- a/docs/mkdocs/docs/api/basic_json/sax_parse.md
+++ b/docs/mkdocs/docs/api/basic_json/sax_parse.md
@@ -126,7 +126,7 @@ A UTF-8 byte order mark is silently ignored.
 
 - Added in version 3.2.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
-- Added `ignore_trailing_commas` in version 3.12.x.
+- Added `ignore_trailing_commas` in version 3.13.0.
 
 !!! warning "Deprecation"
 
diff --git a/docs/mkdocs/docs/api/basic_json/std_formatter.md b/docs/mkdocs/docs/api/basic_json/std_formatter.md
index be1d2d22e..e7e889aee 100644
--- a/docs/mkdocs/docs/api/basic_json/std_formatter.md
+++ b/docs/mkdocs/docs/api/basic_json/std_formatter.md
@@ -54,4 +54,4 @@ provides `<format>`, controlled by the [`JSON_HAS_STD_FORMAT`](../macros/json_ha
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/basic_json/value.md b/docs/mkdocs/docs/api/basic_json/value.md
index 7d1cac8cf..4666f1b4a 100644
--- a/docs/mkdocs/docs/api/basic_json/value.md
+++ b/docs/mkdocs/docs/api/basic_json/value.md
@@ -184,4 +184,6 @@ changes to any JSON value.
 
 1. Added in version 1.0.0. Changed parameter `default_value` type from `const ValueType&` to `ValueType&&` in version 3.11.0.
 2. Added in version 3.11.0. Made `ValueType` the first template parameter in version 3.11.2.
-3. Added in version 2.0.2. Extended to work with arrays in version 3.12.x.
+3. Added in version 2.0.2. Extended to work with arrays in version 3.13.0, including fixing an issue where resolving
+   `ptr` through an array unexpectedly threw `out_of_range` instead of returning the resolved element (or
+   `default_value`, as documented).
diff --git a/docs/mkdocs/docs/api/json_pointer/front.md b/docs/mkdocs/docs/api/json_pointer/front.md
index ae078d19c..afc6f5ca7 100644
--- a/docs/mkdocs/docs/api/json_pointer/front.md
+++ b/docs/mkdocs/docs/api/json_pointer/front.md
@@ -36,4 +36,4 @@ Constant.
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/json_pointer/pop_front.md b/docs/mkdocs/docs/api/json_pointer/pop_front.md
index ecd13ad28..e77980bb4 100644
--- a/docs/mkdocs/docs/api/json_pointer/pop_front.md
+++ b/docs/mkdocs/docs/api/json_pointer/pop_front.md
@@ -32,4 +32,4 @@ Linear in the number of reference tokens in the `json_pointer`.
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/json_pointer/push_front.md b/docs/mkdocs/docs/api/json_pointer/push_front.md
index dd522a48d..387e86e48 100644
--- a/docs/mkdocs/docs/api/json_pointer/push_front.md
+++ b/docs/mkdocs/docs/api/json_pointer/push_front.md
@@ -35,4 +35,4 @@ Linear in the number of reference tokens in the `json_pointer`.
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md b/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md
index b821a046d..970c20537 100644
--- a/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md
+++ b/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md
@@ -92,4 +92,4 @@ The default value is `0` (disabled — existing behavior is preserved).
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/macros/json_has_cpp_11.md b/docs/mkdocs/docs/api/macros/json_has_cpp_11.md
index 6a30b55f0..053214bb3 100644
--- a/docs/mkdocs/docs/api/macros/json_has_cpp_11.md
+++ b/docs/mkdocs/docs/api/macros/json_has_cpp_11.md
@@ -44,4 +44,4 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu
 
 - Added in version 3.10.5.
 - Added `JSON_HAS_CPP_23` in version 3.12.0.
-- Added `JSON_HAS_CPP_26` in version 3.12.x.
+- Added `JSON_HAS_CPP_26` in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/macros/json_has_std_format.md b/docs/mkdocs/docs/api/macros/json_has_std_format.md
index ad5b85fed..8f61d0fed 100644
--- a/docs/mkdocs/docs/api/macros/json_has_std_format.md
+++ b/docs/mkdocs/docs/api/macros/json_has_std_format.md
@@ -38,4 +38,4 @@ When the macro is not defined, the library will define it to its default value.
 
 ## Version history
 
-- Added in version 3.12.x.
+- Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md
index d8640496a..9ce239645 100644
--- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md
+++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_with_names.md
@@ -75,4 +75,4 @@ For further information please refer to the corresponding macros without `WITH_N
 
 ## Version history
 
-1. Added in version 3.12.x.
+1. Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md b/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md
index 7b100748b..73a3a7da4 100644
--- a/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md
+++ b/docs/mkdocs/docs/api/macros/nlohmann_json_serialize_enum_strict.md
@@ -102,4 +102,4 @@ inline void from_json(const BasicJsonType& j, type& e);
 
 ## Version history
 
-Added in version 3.12.x.
+Added in version 3.13.0.
diff --git a/docs/mkdocs/docs/api/operator_literal_json.md b/docs/mkdocs/docs/api/operator_literal_json.md
index 74cc9450c..babce5799 100644
--- a/docs/mkdocs/docs/api/operator_literal_json.md
+++ b/docs/mkdocs/docs/api/operator_literal_json.md
@@ -64,4 +64,4 @@ Linear.
 
 - Added in version 1.0.0.
 - Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.
-- Added `char8_t*` overload in 3.12.x.
+- Added `char8_t*` overload in 3.13.0.
diff --git a/docs/mkdocs/docs/api/operator_literal_json_pointer.md b/docs/mkdocs/docs/api/operator_literal_json_pointer.md
index f027df061..e1b729467 100644
--- a/docs/mkdocs/docs/api/operator_literal_json_pointer.md
+++ b/docs/mkdocs/docs/api/operator_literal_json_pointer.md
@@ -63,4 +63,4 @@ Linear.
 
 - Added in version 2.0.0.
 - Moved to namespace `nlohmann::literals::json_literals` in 3.11.0.
-- Added `char8_t*` overload in 3.12.x.
+- Added `char8_t*` overload in 3.13.0.
diff --git a/docs/mkdocs/docs/community/quality_assurance.md b/docs/mkdocs/docs/community/quality_assurance.md
index 31990fa83..7c315f463 100644
--- a/docs/mkdocs/docs/community/quality_assurance.md
+++ b/docs/mkdocs/docs/community/quality_assurance.md
@@ -10,6 +10,8 @@ violations will result in a failed build.
 
     Any compiler with complete C++11 support can compile the library without warnings.
 
+Note: C++20 modules support may hit compiler-specific issues not covered by the general compiler matrix below. See [Modules](../features/modules.md#known-issues) for known issues and workarounds.
+
 - [x] The library is compiled with 50+ different C++ compilers with different operating systems and platforms,
   including the oldest versions known to compile the library.
 
diff --git a/docs/mkdocs/docs/features/binary_formats/cbor.md b/docs/mkdocs/docs/features/binary_formats/cbor.md
index 1bd28c8da..d385c2a4c 100644
--- a/docs/mkdocs/docs/features/binary_formats/cbor.md
+++ b/docs/mkdocs/docs/features/binary_formats/cbor.md
@@ -66,7 +66,15 @@ see "binary" cells in the table above.
 
 !!! 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`.
+    `NaN`, `Infinity`, and `-Infinity` are serialized as a CBOR half-precision float (type 0xF9, 3 bytes total):
+    `NaN` as `0xF9 0x7E 0x00`, `Infinity` as `0xF9 0x7C 0x00`, and `-Infinity` as `0xF9 0xFC 0x00`. This behavior
+    differs from the normal JSON serialization which serializes NaN or Infinity to `null`.
+
+!!! note
+
+    Prior to version 3.13.0, NaN and Infinity were instead serialized as a CBOR double-precision float (type 0xFB,
+    9 bytes total), because the check used to select a smaller encoding compared magnitudes with NaN, which is
+    always `false` and caused the intended half-precision path to be skipped.
 
 !!! info "Unused CBOR types"
 
@@ -160,6 +168,13 @@ The library maps CBOR types to JSON value types as follows:
      - simple values (0xE0..0xF3, 0xF8)
      - undefined (0xF7)
 
+!!! warning "Negative integer overflow"
+
+    CBOR negative integers (major type 1) are decoded as `-1 - n`. If the encoded magnitude `n` is too large for the
+    result to fit into `number_integer_t` (`std::int64_t` by default), parsing fails with a
+    [`parse_error.112`](../../home/exceptions.md#jsonexceptionparse_error112) exception rather than overflowing
+    silently.
+
 !!! 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.
diff --git a/docs/mkdocs/docs/features/binary_formats/messagepack.md b/docs/mkdocs/docs/features/binary_formats/messagepack.md
index b2f69f174..bd0c840f2 100644
--- a/docs/mkdocs/docs/features/binary_formats/messagepack.md
+++ b/docs/mkdocs/docs/features/binary_formats/messagepack.md
@@ -67,8 +67,15 @@ specification:
 
 !!! info "NaN/infinity handling"
 
-    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`.
+    `NaN`, `Infinity`, and `-Infinity` are serialized as a MessagePack float 32 (type 0xCA, 5 bytes total),
+    regardless of magnitude, in contrast to the [dump](../../api/basic_json/dump.md) function which serializes NaN
+    or Infinity to `null`.
+
+!!! note
+
+    Prior to version 3.13.0, NaN and Infinity were instead serialized as a MessagePack float 64 (type 0xCB, 9 bytes
+    total), because the check used to select the smaller float 32 encoding compared magnitudes with NaN, which is
+    always `false` and caused the float 32 path to be skipped.
 
 ??? example
 
diff --git a/docs/mkdocs/docs/features/modules.md b/docs/mkdocs/docs/features/modules.md
index 53dc2b36f..6708f1d81 100644
--- a/docs/mkdocs/docs/features/modules.md
+++ b/docs/mkdocs/docs/features/modules.md
@@ -27,6 +27,7 @@ json data = json::parse(f);
 It should be noted that as modules do not export macros, the `nlohmann.json` module will not export any macros.
 
 ## Exported symbols
+
 Only the following symbols are exported from `nlohmann.json`:
 
 - `nlohmann::adl_serializer`
@@ -38,3 +39,21 @@ Only the following symbols are exported from `nlohmann.json`:
 - `nlohmann::to_string`
 - `nlohmann::literals::json_literals::operator""_json`
 - `nlohmann::literals::json_literals::operator""_json_pointer`
+
+Additionally, the following `nlohmann::detail` symbols are exported, solely to work around an MSVC compilation issue
+([#3970](https://github.com/nlohmann/json/issues/3970)). They are implementation details, not part of the public API,
+and should not be used directly:
+
+- `nlohmann::detail::json_sax_dom_callback_parser`
+- `nlohmann::detail::unknown_size`
+
+## Known issues
+
+C++20 modules support is exercised in CI against current GCC and Clang on Ubuntu, and the default MSVC toolset on Windows Server 2022 — there is no documented minimum compiler version, unlike feature-test-macro-gated features such as [`JSON_HAS_RANGES`](../api/macros/json_has_ranges.md).
+
+!!! info "Known compiler issues"
+
+    - **GCC** may emit "redefinition" errors when `#include <nlohmann/json.hpp>` appears in a module preamble together with other imports. This is an upstream GCC bug, not yet resolved as of GCC 16. Workarounds: include `nlohmann/json.hpp` before other `#include`s, use `import nlohmann.json;` instead, or upgrade GCC. ([issue #5103](https://github.com/nlohmann/json/issues/5103))
+    - **MSVC** could fail with `C2039: 'json_sax_dom_callback_parser' is not a member of ... detail`; fixed by exporting the required internal symbols from `json.cppm` (see [Exported symbols](#exported-symbols) above). ([issue #3970](https://github.com/nlohmann/json/issues/3970))
+
+    If you hit a different module-related build failure, search [existing issues](https://github.com/nlohmann/json/issues?q=is%3Aissue+modules) before filing a new one.
diff --git a/docs/mkdocs/docs/home/exceptions.md b/docs/mkdocs/docs/home/exceptions.md
index d6e626920..859ebeb48 100644
--- a/docs/mkdocs/docs/home/exceptions.md
+++ b/docs/mkdocs/docs/home/exceptions.md
@@ -326,6 +326,9 @@ An unexpected byte was read in a [binary format](../features/binary_formats/inde
     ```
     [json.exception.parse_error.112] parse error at byte 15: syntax error while parsing BSON binary: byte array length cannot be negative, is -1
     ```
+    ```
+    [json.exception.parse_error.112] parse error at byte 9: syntax error while parsing CBOR value: negative integer overflow
+    ```
 
 ### json.exception.parse_error.113
 
@@ -893,7 +896,7 @@ A JSON Patch `add` operation cannot be applied because the target location's par
 
 !!! note
 
-    This exception was added in version 3.12.x. Before that, this situation hit an internal assertion (aborting the program in debug builds) or was silently ignored when assertions were disabled.
+    This exception was added in version 3.13.0. Before that, this situation hit an internal assertion (aborting the program in debug builds) or was silently ignored when assertions were disabled.
 
 ## Further exceptions
 
diff --git a/docs/mkdocs/docs/home/faq.md b/docs/mkdocs/docs/home/faq.md
index 4af6fc0fa..c92889eca 100644
--- a/docs/mkdocs/docs/home/faq.md
+++ b/docs/mkdocs/docs/home/faq.md
@@ -178,7 +178,7 @@ See [this section](../features/types/number_handling.md#number-serialization) on
     - Can I use `std::format("{}", j)` on a JSON value?
     - Can I use `fmt::format("{}", j)` or `fmt::print("{}", j)` (the [{fmt}](https://github.com/fmtlib/fmt) library) on a JSON value?
 
-`std::format` works out of the box since version 3.12.x, as long as the standard library provides
+`std::format` works out of the box since version 3.13.0, as long as the standard library provides
 `<format>` (see [`JSON_HAS_STD_FORMAT`](../api/macros/json_has_std_format.md)); see
 [`std::formatter<basic_json>`](../api/basic_json/std_formatter.md) for details, including the `#!cpp "{:#}"`
 pretty-print spec, indent widths (`#!cpp "{:2}"`), and custom indent characters (`#!cpp "{:.>#}"`).