🔥 consolidate documentation

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

@@ -94,7 +94,7 @@ The class satisfies the following concept requirements:
 - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
 - initializer_list_t
 - [**input_format_t**](input_format_t.md) - type to choose the format to parse
-- json_sax_t
+- [**json_sax_t**](../json_sax/index.md) - type for SAX events
 
 ### Exceptions
 
@@ -289,9 +289,8 @@ Access to the JSON value
 
 ## Helper classes
 
-- std::hash<nlohmann::json\>
+- [**std::hash&lt;basic_json&gt;**](std_hash.md) - return a hash value for a JSON object
-- std::less<nlohmann::value_t\>
+- [**std::swap&lt;basic_json&gt;**](std_swap.md) - exchanges the values of two JSON objects
-- std::swap<nlohmann::json\>
 
 ## See also
 

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

@@ -0,0 +1,16 @@
+# std::hash<basic_json\>
+
+```cpp
+namespace std {
+    struct hash<nlohmann::basic_json>;
+}
+```
+
+Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the
+type of the JSON value is taken into account to have different hash values for `#!json null`, `#!cpp 0`, `#!cpp 0U`, and
+`#!cpp false`, etc.
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended for arbitrary basic_json types in version 3.10.5.

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

@@ -0,0 +1,27 @@
+# std::swap<basic_json\>
+
+```cpp
+namespace std {
+    void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2);
+}
+```
+
+Exchanges the values of two JSON objects.
+
+## Possible implementation
+
+```cpp
+void swap(nlohmann::basic_json& j1, nlohmann::basic_json& j2)
+{
+    j1.swap(j2);
+}
+```
+
+## See also
+
+- [swap](swap.md)
+
+## Version history
+
+- Added in version 1.0.0.
+- Extended for arbitrary basic_json types in version 3.10.5.

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

@@ -142,6 +142,10 @@ Constant.
     --8<-- "examples/swap__binary_t.output"
     ```
 
+## See also
+
+- [std::swap<basic_json\>](std_swap.md)
+
 ## Version history
 
 1. Since version 1.0.0.

doc/mkdocs/mkdocs.yml

@@ -114,6 +114,7 @@ nav:
         - 'get_ptr': api/basic_json/get_ptr.md
         - 'get_ref': api/basic_json/get_ref.md
         - 'get_to': api/basic_json/get_to.md
+        - 'std::hash<basic_json>': api/basic_json/std_hash.md
         - 'input_format_t': api/basic_json/input_format_t.md
         - 'insert': api/basic_json/insert.md
         - 'invalid_iterator': api/basic_json/invalid_iterator.md
@@ -170,6 +171,7 @@ nav:
         - 'size': api/basic_json/size.md
         - 'string_t': api/basic_json/string_t.md
         - 'swap': api/basic_json/swap.md
+        - 'std::swap<basic_json>': api/basic_json/std_swap.md
         - 'to_bson': api/basic_json/to_bson.md
         - 'to_cbor': api/basic_json/to_cbor.md
         - 'to_msgpack': api/basic_json/to_msgpack.md

include/nlohmann/json.hpp

@@ -4678,15 +4678,11 @@ std::string to_string(const NLOHMANN_BASIC_JSON_TPL& j)
 namespace std // NOLINT(cert-dcl58-cpp)
 {
 
-/// hash value for JSON objects
+/// @brief hash value for JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_hash/
 NLOHMANN_BASIC_JSON_TPL_DECLARATION
 struct hash<nlohmann::NLOHMANN_BASIC_JSON_TPL>
 {
-    /*!
-    @brief return a hash value for a JSON object
-
-    @since version 1.0.0, extended for arbitrary basic_json types in 3.10.5.
-    */
     std::size_t operator()(const nlohmann::NLOHMANN_BASIC_JSON_TPL& j) const
     {
         return nlohmann::detail::hash(j);
@@ -4713,11 +4709,8 @@ struct less< ::nlohmann::detail::value_t>
 // C++20 prohibit function specialization in the std namespace.
 #ifndef JSON_HAS_CPP_20
 
-/*!
+/// @brief exchanges the values of two JSON objects
-@brief exchanges the values of two JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_swap/
-
-@since version 1.0.0, extended for arbitrary basic_json types in 3.10.5.
-*/
 NLOHMANN_BASIC_JSON_TPL_DECLARATION
 inline void swap(nlohmann::NLOHMANN_BASIC_JSON_TPL& j1, nlohmann::NLOHMANN_BASIC_JSON_TPL& j2) noexcept(  // NOLINT(readability-inconsistent-declaration-parameter-name)
     is_nothrow_move_constructible<nlohmann::NLOHMANN_BASIC_JSON_TPL>::value&&                          // NOLINT(misc-redundant-expression)

single_include/nlohmann/json.hpp

@@ -21709,15 +21709,11 @@ std::string to_string(const NLOHMANN_BASIC_JSON_TPL& j)
 namespace std // NOLINT(cert-dcl58-cpp)
 {
 
-/// hash value for JSON objects
+/// @brief hash value for JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_hash/
 NLOHMANN_BASIC_JSON_TPL_DECLARATION
 struct hash<nlohmann::NLOHMANN_BASIC_JSON_TPL>
 {
-    /*!
-    @brief return a hash value for a JSON object
-
-    @since version 1.0.0, extended for arbitrary basic_json types in 3.10.5.
-    */
     std::size_t operator()(const nlohmann::NLOHMANN_BASIC_JSON_TPL& j) const
     {
         return nlohmann::detail::hash(j);
@@ -21744,11 +21740,8 @@ struct less< ::nlohmann::detail::value_t>
 // C++20 prohibit function specialization in the std namespace.
 #ifndef JSON_HAS_CPP_20
 
-/*!
+/// @brief exchanges the values of two JSON objects
-@brief exchanges the values of two JSON objects
+/// @sa https://json.nlohmann.me/api/basic_json/std_swap/
-
-@since version 1.0.0, extended for arbitrary basic_json types in 3.10.5.
-*/
 NLOHMANN_BASIC_JSON_TPL_DECLARATION
 inline void swap(nlohmann::NLOHMANN_BASIC_JSON_TPL& j1, nlohmann::NLOHMANN_BASIC_JSON_TPL& j2) noexcept(  // NOLINT(readability-inconsistent-declaration-parameter-name)
     is_nothrow_move_constructible<nlohmann::NLOHMANN_BASIC_JSON_TPL>::value&&                          // NOLINT(misc-redundant-expression)