Add note on derived return type for value function (#4628)

* 📝 add note on derived return type

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* 📝 add note on derived return type

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/at.md

@@ -215,8 +215,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
 ## See also
 
 - documentation on [checked access](../../features/element_access/checked_access.md)
-- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
-- see [`value`](value.md) for access with default value
+- [`operator[]`](operator%5B%5D.md) for unchecked access by reference
+- [`value`](value.md) for access with default value
 
 ## Version history
 

docs/mkdocs/docs/api/basic_json/value.md

@@ -103,6 +103,30 @@ changes to any JSON value.
 2. Logarithmic in the size of the container.
 3. Logarithmic in the size of the container.
 
+## Notes
+
+!!! warning "Return type"
+
+    The value function is a template, and the return type of the function is determined by the type of the provided
+    default value unless otherwise specified. This can have unexpected effects. In the example below, we store a 64-bit
+    unsigned integer. We get exactly that value when using [`operator[]`](operator[].md). However, when we call `value`
+    and provide `#!c 0` as default value, then `#!c -1` is returned. The occurs, because `#!c 0` has type `#!c int`
+    which overflows when handling the value `#!c 18446744073709551615`.
+
+    To address this issue, either provide a correctly typed default value or use the template parameter to specify the
+    desired return type. Note that this issue occurs even when a value is stored at the provided key, and the default
+    value is not used as the return value.
+
+    ```cpp
+    --8<-- "examples/value__return_type.cpp"
+    ```
+
+    Output:
+    
+    ```json
+    --8<-- "examples/value__return_type.output"
+    ```
+
 ## Examples
 
 ??? example "Example: (1) access specified object element with default value"