From 093505abf16abb4c57c00300dfb32fcdae9be911 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Thu, 9 Jul 2026 13:26:14 +0200
Subject: [PATCH] :memo: Document integer type selection, type_name() invalid
 value, and std::optional get() fix

- number_handling.md: clarify that positive/negative integers select
  unsigned/signed storage based on the leading minus sign (todo 143).
- type_name.md: document the new "invalid" return value for corrupted
  JSON values (todo 145).
- get.md: note that get<std::optional<T>>() was unreachable in every
  configuration prior to 3.13.0 due to an internal macro-guard bug,
  unrelated to JSON_USE_IMPLICIT_CONVERSIONS's actual effect (todo 144).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 docs/mkdocs/docs/api/basic_json/get.md             | 7 +++++++
 docs/mkdocs/docs/api/basic_json/type_name.md       | 7 +++++++
 docs/mkdocs/docs/features/types/number_handling.md | 4 ++++
 3 files changed, 18 insertions(+)

diff --git a/docs/mkdocs/docs/api/basic_json/get.md b/docs/mkdocs/docs/api/basic_json/get.md
index adf63b8a7..8329de919 100644
--- a/docs/mkdocs/docs/api/basic_json/get.md
+++ b/docs/mkdocs/docs/api/basic_json/get.md
@@ -114,6 +114,13 @@ overload (3).
     See [Number conversion](../../features/types/number_handling.md#number-conversion)
     for more information.
 
+!!! note "`std::optional` conversions"
+
+    Prior to version 3.13.0, `#!cpp get<std::optional<T>>()` (and other conversions to `std::optional<T>`) failed to
+    compile in every configuration, due to an internal implementation bug that made the `from_json` overload for
+    `std::optional` unreachable regardless of the [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md)
+    setting. This has been fixed.
+
 ## Examples
 
 ??? example
diff --git a/docs/mkdocs/docs/api/basic_json/type_name.md b/docs/mkdocs/docs/api/basic_json/type_name.md
index 389c2b1dd..2022b8897 100644
--- a/docs/mkdocs/docs/api/basic_json/type_name.md
+++ b/docs/mkdocs/docs/api/basic_json/type_name.md
@@ -21,6 +21,12 @@ a string representation of the type ([`value_t`](value_t.md)):
 | array                                              | `"array"`     |
 | binary                                             | `"binary"`    |
 | discarded                                          | `"discarded"` |
+| invalid (corrupted value)                          | `"invalid"`   |
+
+!!! note "The \"invalid\" type"
+
+    The `"invalid"` return value indicates a corrupted JSON value — this can occur if an enum value falls outside the
+    range of valid `value_t` values. This is useful for diagnosing data corruption or internal errors.
 
 ## Exception safety
 
@@ -52,3 +58,4 @@ Constant.
 - Part of the public API version since 2.1.0.
 - Changed return value to `const char*` and added `noexcept` in version 3.0.0.
 - Added support for binary type in version 3.8.0.
+- Added `"invalid"` return value for corrupted JSON values in version 3.13.0.
diff --git a/docs/mkdocs/docs/features/types/number_handling.md b/docs/mkdocs/docs/features/types/number_handling.md
index 7fa31fb97..cf37b044a 100644
--- a/docs/mkdocs/docs/features/types/number_handling.md
+++ b/docs/mkdocs/docs/features/types/number_handling.md
@@ -63,6 +63,10 @@ In the default [`json`](../../api/json.md) type, numbers are stored as `#!c std:
 number without loss of precision. If this is impossible (e.g., if the number is too large), the number is stored as
 `#!c double`.
 
+Positive integers are stored as `#!c std::uint64_t`, while negative integers are stored as `#!c std::int64_t`. This
+distinction is determined at parse time: if the JSON number has a leading minus sign, it uses signed integer storage;
+otherwise, it uses unsigned integer storage.
+
 !!! info "Notes"
 
     - Numbers with a decimal digit or scientific notation are always stored as `#!c double`.