deploy: 2e91641de2

api/macros/json_brace_init_copy_semantics.md

@@ -38,6 +38,28 @@ The default value is `0` (disabled — existing behavior is preserved).
 
     This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
 
+!!! warning "Applies to every single-element list"
+
+    The macro does not only affect a single JSON value in braces. **Any** single-element braced list is treated as its
+    element, so it no longer creates a one-element array:
+
+    ```cpp
+    json j1 = {1};       // 1, not [1]
+    json j2 = {"text"};  // "text", not ["text"]
+    json j3 = {{1, 2}};  // [1,2], not [[1,2]]
+    ```
+
+    Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one
+    element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not
+    affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes
+    `[5]`.
+
+!!! note "ABI compatibility"
+
+    The value of this macro is encoded in the [namespace](../../features/namespace.md) (tag `_bics`), resulting in
+    distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program
+    without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
+
 !!! tip "Workaround without the macro"
 
     To explicitly create a single-element array without enabling this macro, use `json::array()`:

api/macros/json_brace_init_copy_semantics/index.md

@@ -33,6 +33,22 @@ Opt-in only
 
 This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
 
+Applies to every single-element list
+
+The macro does not only affect a single JSON value in braces. **Any** single-element braced list is treated as its element, so it no longer creates a one-element array:
+
+```
+json j1 = {1};       // 1, not [1]
+json j2 = {"text"};  // "text", not ["text"]
+json j3 = {{1, 2}};  // [1,2], not [[1,2]]
+```
+
+Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
+
+ABI compatibility
+
+The value of this macro is encoded in the [namespace](https://json.nlohmann.me/features/namespace/index.md) (tag `_bics`), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
+
 Workaround without the macro
 
 To explicitly create a single-element array without enabling this macro, use `json::array()`:

api/macros/json_use_implicit_conversions.md

@@ -24,6 +24,14 @@ By default, implicit conversions are enabled.
     You can prepare existing code by already defining `JSON_USE_IMPLICIT_CONVERSIONS` to `0` and replace any implicit
     conversions with calls to [`get`](../basic_json/get.md).
 
+!!! tip "Automatic migration"
+
+    The community-maintained clang-tidy check `modernize-nlohmann-json-explicit-conversions` rewrites implicit
+    conversions into explicit calls to [`get`](../basic_json/get.md); for example, `#!cpp int i = j;` becomes
+    `#!cpp int i = j.get<int>();`. The check is not part of clang-tidy itself, and it does not catch every case (for
+    example, constructing a `std::optional` from a JSON value), so review the result. See
+    [discussion #4610](https://github.com/nlohmann/json/discussions/4610) for how to build and use it.
+
 !!! hint "CMake option"
 
     Implicit conversions can also be controlled with the CMake option

api/macros/json_use_implicit_conversions/index.md

@@ -22,6 +22,10 @@ Implicit conversions will be switched off by default in the next major release o
 
 You can prepare existing code by already defining `JSON_USE_IMPLICIT_CONVERSIONS` to `0` and replace any implicit conversions with calls to [`get`](https://json.nlohmann.me/api/basic_json/get/index.md).
 
+Automatic migration
+
+The community-maintained clang-tidy check `modernize-nlohmann-json-explicit-conversions` rewrites implicit conversions into explicit calls to [`get`](https://json.nlohmann.me/api/basic_json/get/index.md); for example, `int i = j;` becomes `int i = j.get<int>();`. The check is not part of clang-tidy itself, and it does not catch every case (for example, constructing a `std::optional` from a JSON value), so review the result. See [discussion #4610](https://github.com/nlohmann/json/discussions/4610) for how to build and use it.
+
 CMake option
 
 Implicit conversions can also be controlled with the CMake option [`JSON_ImplicitConversions`](https://json.nlohmann.me/integration/cmake/#json_implicitconversions) (`ON` by default) which defines `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.