🔥 consolidate documentation

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

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

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

@@ -0,0 +1,58 @@
+# operator>>(basic_json)
+
+```cpp
+std::istream& operator>>(std::istream& i, basic_json& j)
+```
+
+Deserializes an input stream to a JSON value.
+
+## Parameters
+
+`i` (in, out)
+:   input stream to read a serialized JSON value from
+
+`j` (in, out)
+:   JSON value to write the deserialized input to
+
+## Return value
+
+the stream `i`
+
+## Exceptions
+
+- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
+- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate 
+  error.
+- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
+
+## Complexity
+
+Linear in the length of the input. The parser is a predictive LL(1) parser.
+
+## Note
+
+A UTF-8 byte order mark is silently ignored.
+
+## Example
+
+??? example
+
+    The example below shows how a JSON value is constructed by reading a serialization from a stream.
+        
+    ```cpp
+    --8<-- "examples/operator_deserialize.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_deserialize.output"
+    ```
+
+## See also
+
+- [parse](parse.md) for a variant with a parser callback function to filter values while parsing
+
+## Version history
+
+- Added in version 1.0.0

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

@@ -3,6 +3,7 @@
 ```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.
 

doc/mkdocs/mkdocs.yml

@@ -151,6 +151,7 @@ nav:
         - api/basic_json/operator_ltlt.md
         - api/basic_json/operator_le.md
         - api/basic_json/operator_gt.md
+        - api/basic_json/operator_gtgt.md
         - api/basic_json/operator_ge.md
         - api/basic_json/operator+=.md
         - api/basic_json/operator_literal_json.md

include/nlohmann/json.hpp

@@ -3640,14 +3640,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return o;
     }
 
-    /*!
+    /// @brief serialize to stream
-    @brief serialize to stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
-    @deprecated This stream operator is deprecated and will be removed in
+    /// @deprecated This function is deprecated since 3.0.0 and will be removed in
-                future 4.0.0 of the library. Please use
+    ///             version 4.0.0 of the library. Please use
-                @ref operator<<(std::ostream&, const basic_json&)
+    ///             operator<<(std::ostream&, const basic_json&) instead; that is,
-                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    ///             replace calls like `j >> o;` with `o << j;`.
-    @since version 1.0.0; deprecated since version 3.0.0
-    */
     JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&))
     friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
     {
@@ -3761,6 +3759,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                : detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
     }
 
+    /// @brief generate SAX events
+    /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
+    /// @deprecated This function is deprecated since 3.8.0 and will be removed in
+    ///             version 4.0.0 of the library. Please use
+    ///             sax_parse(ptr, ptr + len) instead.
     template <typename SAX>
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...))
     JSON_HEDLEY_NON_NULL(2)
@@ -3777,45 +3780,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                : detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
     }
 #ifndef JSON_NO_IO
-    /*!
+    /// @brief deserialize from stream
-    @brief deserialize from stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
-    @deprecated This stream operator is deprecated and will be removed in
+    /// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in
-                version 4.0.0 of the library. Please use
+    ///             version 4.0.0 of the library. Please use
-                @ref operator>>(std::istream&, basic_json&)
+    ///             operator>>(std::istream&, basic_json&) instead; that is,
-                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    ///             replace calls like `j << i;` with `i >> j;`.
-    @since version 1.0.0; deprecated since version 3.0.0
-    */
     JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&))
     friend std::istream& operator<<(basic_json& j, std::istream& i)
     {
         return operator>>(i, j);
     }
 
-    /*!
+    /// @brief deserialize from stream
-    @brief deserialize from stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
-
-    Deserializes an input stream to a JSON value.
-
-    @param[in,out] i  input stream to read a serialized JSON value from
-    @param[in,out] j  JSON value to write the deserialized input to
-
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
-
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser.
-
-    @note A UTF-8 byte order mark is silently ignored.
-
-    @liveexample{The example below shows how a JSON value is constructed by
-    reading a serialization from a stream.,operator_deserialize}
-
-    @sa parse(std::istream&, const parser_callback_t) for a variant with a
-    parser callback function to filter values while parsing
-
-    @since version 1.0.0
-    */
     friend std::istream& operator>>(std::istream& i, basic_json& j)
     {
         parser(detail::input_adapter(i)).parse(false, j);

single_include/nlohmann/json.hpp

@@ -21141,14 +21141,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         return o;
     }
 
-    /*!
+    /// @brief serialize to stream
-    @brief serialize to stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/
-    @deprecated This stream operator is deprecated and will be removed in
+    /// @deprecated This function is deprecated since 3.0.0 and will be removed in
-                future 4.0.0 of the library. Please use
+    ///             version 4.0.0 of the library. Please use
-                @ref operator<<(std::ostream&, const basic_json&)
+    ///             operator<<(std::ostream&, const basic_json&) instead; that is,
-                instead; that is, replace calls like `j >> o;` with `o << j;`.
+    ///             replace calls like `j >> o;` with `o << j;`.
-    @since version 1.0.0; deprecated since version 3.0.0
-    */
     JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&))
     friend std::ostream& operator>>(const basic_json& j, std::ostream& o)
     {
@@ -21262,6 +21260,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                : detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
     }
 
+    /// @brief generate SAX events
+    /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/
+    /// @deprecated This function is deprecated since 3.8.0 and will be removed in
+    ///             version 4.0.0 of the library. Please use
+    ///             sax_parse(ptr, ptr + len) instead.
     template <typename SAX>
     JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...))
     JSON_HEDLEY_NON_NULL(2)
@@ -21278,45 +21281,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
                : detail::binary_reader<basic_json, decltype(ia), SAX>(std::move(ia)).sax_parse(format, sax, strict);
     }
 #ifndef JSON_NO_IO
-    /*!
+    /// @brief deserialize from stream
-    @brief deserialize from stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
-    @deprecated This stream operator is deprecated and will be removed in
+    /// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in
-                version 4.0.0 of the library. Please use
+    ///             version 4.0.0 of the library. Please use
-                @ref operator>>(std::istream&, basic_json&)
+    ///             operator>>(std::istream&, basic_json&) instead; that is,
-                instead; that is, replace calls like `j << i;` with `i >> j;`.
+    ///             replace calls like `j << i;` with `i >> j;`.
-    @since version 1.0.0; deprecated since version 3.0.0
-    */
     JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&))
     friend std::istream& operator<<(basic_json& j, std::istream& i)
     {
         return operator>>(i, j);
     }
 
-    /*!
+    /// @brief deserialize from stream
-    @brief deserialize from stream
+    /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/
-
-    Deserializes an input stream to a JSON value.
-
-    @param[in,out] i  input stream to read a serialized JSON value from
-    @param[in,out] j  JSON value to write the deserialized input to
-
-    @throw parse_error.101 in case of an unexpected token
-    @throw parse_error.102 if to_unicode fails or surrogate error
-    @throw parse_error.103 if to_unicode fails
-
-    @complexity Linear in the length of the input. The parser is a predictive
-    LL(1) parser.
-
-    @note A UTF-8 byte order mark is silently ignored.
-
-    @liveexample{The example below shows how a JSON value is constructed by
-    reading a serialization from a stream.,operator_deserialize}
-
-    @sa parse(std::istream&, const parser_callback_t) for a variant with a
-    parser callback function to filter values while parsing
-
-    @since version 1.0.0
-    */
     friend std::istream& operator>>(std::istream& i, basic_json& j)
     {
         parser(detail::input_adapter(i)).parse(false, j);