🔥 consolidate documentation

doc/mkdocs/docs/api/basic_json/index.md

@@ -279,7 +279,7 @@ Access to the JSON value
 
 ## Non-member functions
 
-- operator<<(std::ostream&) - serialize to stream
+- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream
 - operator>>(std::istream&) - deserialize from stream
 
 ## Literals

doc/mkdocs/docs/api/basic_json/operator_ltlt.md

@@ -0,0 +1,55 @@
+# operator<<(basic_json)
+
+```cpp
+std::ostream& operator<<(std::ostream& o, const basic_json& j)
+```
+Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the
+[`dump`](dump.md) member function.
+
+- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
+  instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result
+  is the same as calling `dump(4)`.
+- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
+  the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character.
+
+## Parameters
+
+`o` (in, out)
+:   stream to serialize to
+
+`j` (in)
+:   JSON value to serialize
+
+## Return value
+
+the stream `o`
+
+## Exceptions
+
+Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value
+is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set.
+
+## Complexity
+
+Linear.
+
+## Example
+
+??? example
+
+    The example below shows the serialization with different parameters to `width` to adjust the indentation level.
+        
+    ```cpp
+    --8<-- "examples/operator_serialize.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_serialize.output"
+    ```
+
+## Version history
+
+- Added in version 1.0.0
+- Support for indentation character added in version 3.0.0.

doc/mkdocs/mkdocs.yml

@@ -148,6 +148,7 @@ nav:
         - api/basic_json/operator_eq.md
         - api/basic_json/operator_ne.md
         - api/basic_json/operator_lt.md
+        - api/basic_json/operator_ltlt.md
         - api/basic_json/operator_le.md
         - api/basic_json/operator_gt.md
         - api/basic_json/operator_ge.md

include/nlohmann/json.hpp

@@ -3638,37 +3638,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /// @name serialization
     /// @{
 #ifndef JSON_NO_IO
-    /*!
-    @brief serialize to stream
-
-    Serialize the given JSON value @a j to the output stream @a o. The JSON
-    value will be serialized using the @ref dump member function.
-
-    - The indentation of the output can be controlled with the member variable
-      `width` of the output stream @a o. For instance, using the manipulator
-      `std::setw(4)` on @a o sets the indentation level to `4` and the
-      serialization result is the same as calling `dump(4)`.
-
-    - The indentation character can be controlled with the member variable
-      `fill` of the output stream @a o. For instance, the manipulator
-      `std::setfill('\\t')` sets indentation to use a tab character rather than
-      the default space character.
-
-    @param[in,out] o  stream to serialize to
-    @param[in] j  JSON value to serialize
-
-    @return the stream @a o
-
-    @throw type_error.316 if a string stored inside the JSON value is not
-                          UTF-8 encoded
-
-    @complexity Linear.
-
-    @liveexample{The example below shows the serialization with different
-    parameters to `width` to adjust the indentation level.,operator_serialize}
-
-    @since version 1.0.0; indentation character added in version 3.0.0
-    */
+    /// @brief serialize to stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
     friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
     {
         // read width member and use it as indentation parameter if nonzero

single_include/nlohmann/json.hpp

@@ -21139,37 +21139,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /// @name serialization
     /// @{
 #ifndef JSON_NO_IO
-    /*!
-    @brief serialize to stream
-
-    Serialize the given JSON value @a j to the output stream @a o. The JSON
-    value will be serialized using the @ref dump member function.
-
-    - The indentation of the output can be controlled with the member variable
-      `width` of the output stream @a o. For instance, using the manipulator
-      `std::setw(4)` on @a o sets the indentation level to `4` and the
-      serialization result is the same as calling `dump(4)`.
-
-    - The indentation character can be controlled with the member variable
-      `fill` of the output stream @a o. For instance, the manipulator
-      `std::setfill('\\t')` sets indentation to use a tab character rather than
-      the default space character.
-
-    @param[in,out] o  stream to serialize to
-    @param[in] j  JSON value to serialize
-
-    @return the stream @a o
-
-    @throw type_error.316 if a string stored inside the JSON value is not
-                          UTF-8 encoded
-
-    @complexity Linear.
-
-    @liveexample{The example below shows the serialization with different
-    parameters to `width` to adjust the indentation level.,operator_serialize}
-
-    @since version 1.0.0; indentation character added in version 3.0.0
-    */
+    /// @brief serialize to stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
     friend std::ostream& operator<<(std::ostream& o, const basic_json& j)
     {
         // read width member and use it as indentation parameter if nonzero