docs: qualify push_back({value}) and += {value} brace-init behavior (#6091)

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

docs/mkdocs/docs/api/basic_json/operator+=.md

@@ -27,6 +27,16 @@ reference operator+=(initializer_list_t init);
     `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
     Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
 
+    !!! note "Single braced JSON value"
+
+        For a call such as `#!cpp arr += {obj}`, where the initializer list contains a single JSON value `obj`,
+        compilers may disagree unless
+        [`JSON_BRACE_INIT_COPY_SEMANTICS`](../macros/json_brace_init_copy_semantics.md) is defined to `1`: GCC, for
+        example, selects this overload and appends a single-element array `[obj]`, whereas Clang selects the
+        `basic_json` overload and appends a copy of `obj`. With the macro, GCC and Clang both append a copy of `obj`.
+        To get a portable result without the macro, write `#!cpp arr += obj` to append a copy, or
+        `#!cpp arr += json::array({obj})` to append a single-element array.
+
 ## Iterator invalidation
 
 For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including

docs/mkdocs/docs/api/basic_json/push_back.md

@@ -27,6 +27,16 @@ void push_back(initializer_list_t init);
     `init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`.
     Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`.
 
+    !!! note "Single braced JSON value"
+
+        For a call such as `#!cpp arr.push_back({obj})`, where the initializer list contains a single JSON value `obj`,
+        compilers may disagree unless
+        [`JSON_BRACE_INIT_COPY_SEMANTICS`](../macros/json_brace_init_copy_semantics.md) is defined to `1`: GCC, for
+        example, selects this overload and appends a single-element array `[obj]`, whereas Clang selects the
+        `basic_json` overload and appends a copy of `obj`. With the macro, GCC and Clang both append a copy of `obj`.
+        To get a portable result without the macro, write `#!cpp arr.push_back(obj)` to append a copy, or
+        `#!cpp arr.push_back(json::array({obj}))` to append a single-element array.
+
 ## Iterator invalidation
 
 For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including

docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md

@@ -27,9 +27,13 @@ The default value is `0` (disabled — existing behavior is preserved).
     json j{obj};
     ```
 
-    creates a single-element **array** `[{"key":"value"}]` instead of a copy of `obj`. This behavior is
-    compiler-dependent for older compilers (GCC wrapped, Clang did not), but starting from Clang 20, both compilers
-    behave the same way.
+    creates a single-element **array** `[{"key":"value"}]` instead of a copy of `obj`. For this constructor, the
+    behavior was compiler-dependent for older compilers (GCC wrapped, Clang did not), but starting from Clang 20, both
+    compilers behave the same way.
+
+    The calls `#!cpp arr.push_back({obj})` and `#!cpp arr += {obj}` are still compiler-dependent without the macro,
+    even with Clang 20 and later: GCC converts `{obj}` to a single-element array and appends that array, whereas Clang
+    appends a copy of `obj`. With the macro defined to `1`, both compilers append a copy of `obj`.
 
     Enabling this macro opts into copy/move semantics for this case
     (see [#5074](https://github.com/nlohmann/json/issues/5074)).