From 063a288a87b945d9edf2d0f4d5406b69f6a4af92 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Mon, 25 Apr 2022 20:41:55 +0200
Subject: [PATCH] :memo: document future behavior change

---
 .../docs/api/basic_json/operator_ValueType.md | 47 ++++++++++++-------
 .../macros/json_use_implicit_conversions.md   | 17 ++++++-
 2 files changed, 45 insertions(+), 19 deletions(-)

diff --git a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
index 1eec13553..7d14c5061 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md
@@ -27,33 +27,44 @@ Linear in the size of the JSON value.
 
 ## Notes
 
-By default `JSON_EXPLICIT` defined to the empty string, so the signature is:
+!!! note "Definition of `JSON_EXPLICIT`"
 
-```cpp
-template<typename ValueType>
-operator ValueType() const;
-```
+    By default `JSON_EXPLICIT` defined to the empty string, so the signature is:
+    
+    ```cpp
+    template<typename ValueType>
+    operator ValueType() const;
+    ```
+    
+    If [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) is set to `0`,
+    `JSON_EXPLICIT` is defined to `#!cpp explicit`:
 
-If [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) is set to `0`,
-`JSON_EXPLICIT` is defined to `#!cpp explicit`:
+    ```cpp
+    template<typename ValueType>
+    explicit operator ValueType() const;
+    ```
+    
+    That is, implicit conversions can be switched off by defining
+    [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0`.
 
-```cpp
-template<typename ValueType>
-explicit operator ValueType() const;
-```
+!!! info "Future behavior change"
+
+    Implicit conversions will be switched off by default in the next major release of the library. That is,
+    `JSON_EXPLICIT` will be set to `#!cpp explicit` by default.
+
+    You can prepare existing code by already defining
+    [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0` and adjust any implicit
+    conversions by calls to [`get`](../basic_json/get.md).
 
-That is, implicit conversions can be switched off by defining
-[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
 
 ## Examples
 
 ??? example
 
-    The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers, (2) A JSON array can be converted to a standard
-    `std::vector<short>`, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string, json>`.
+    The example below shows several conversions from JSON values to other types. There a few things to note: (1)
+    Floating-point numbers can be converted to integers, (2) A JSON array can be converted to a standard
+    `std::vector<short>`, (3) A JSON object can be converted to C++ associative containers such as
+    `std::unordered_map<std::string, json>`.
         
     ```cpp
     --8<-- "examples/operator__ValueType.cpp"
diff --git a/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md b/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md
index 9a3a1e203..c38d583a5 100644
--- a/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md
+++ b/doc/mkdocs/docs/api/macros/json_use_implicit_conversions.md
@@ -4,7 +4,8 @@
 #define JSON_USE_IMPLICIT_CONVERSIONS /* value */
 ```
 
-When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on.
+When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The
+value is directly affecting [`operator ValueType`](../basic_json/operator_ValueType.md).
 
 Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which
 sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
@@ -17,6 +18,15 @@ By default, implicit conversions are enabled.
 #define JSON_USE_IMPLICIT_CONVERSIONS 1
 ```
 
+## Notes
+
+!!! info "Future behavior change"
+
+    Implicit conversions will be switched off by default in the next major release of the library.
+
+    You can prepare existing code by already defining `JSON_USE_IMPLICIT_CONVERSIONS` to `0` and adjust any implicit
+    conversions by calls to [`get`](../basic_json/get.md).
+
 ## Examples
 
 ??? example
@@ -36,6 +46,11 @@ By default, implicit conversions are enabled.
     auto s = j.get<std::string>();
     ```
 
+## See also
+
+- [**operator ValueType**](../basic_json/operator_ValueType.md) - get a value (implicit)
+- [**get**](../basic_json/get.md) - get a value (explicit)
+
 ## Version history
 
 - Added in version 3.9.0.