🔥 consolidate documentation

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

@@ -42,6 +42,48 @@ class basic_json;
 
 Todo
 
+## Requirements
+
+The class satisfies the following concept requirements:
+
+### Basic
+
+- [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible): JSON values can be default
+  constructed. The result will be a JSON null value.
+- [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible): A JSON value can be constructed
+  from an rvalue argument.
+- [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible): A JSON value can be
+  copy-constructed from an lvalue expression.
+- [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable): A JSON value van be assigned from an
+  rvalue argument.
+- [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable): A JSON value can be copy-assigned from
+  an lvalue expression.
+- [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible): JSON values can be destructed.
+
+### Layout
+
+- [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType): JSON values have
+  [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout): All non-static data
+  members are private and standard layout types, the class has no virtual functions or (virtual) base classes.
+
+### Library-wide
+
+- [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable): JSON values can be compared with
+  `==`, see [`operator==`](operator_eq.md).
+- [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable): JSON values can be compared with
+  `<`, see [`operator<`](operator_le).
+- [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable): Any JSON lvalue or rvalue of can be swapped with
+  any lvalue or rvalue of other compatible types, using unqualified function `swap`.
+- [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer): JSON values can be compared against
+  `std::nullptr_t` objects which are used to model the `null` value.
+
+### Container
+
+- [Container](https://en.cppreference.com/w/cpp/named_req/Container): JSON values can be used like STL containers and
+  provide iterator access.
+- [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer): JSON values can be used like
+  STL containers and provide reverse iterator access.
+
 ## Member types
 
 - [**adl_serializer**](../adl_serializer) - the default serializer
@@ -183,7 +225,7 @@ Access to the JSON value
 - [**erase**](erase.md) - remove elements
 - [**insert**](insert.md) - inserts elements
 - [**update**](update.md) - updates a JSON object from another object, overwriting existing keys 
-- swap - exchanges the values
+- [**swap**](swap.md) - exchanges the values
 
 ### Lexicographical comparison operators
 
@@ -250,3 +292,7 @@ Access to the JSON value
 - std::hash<nlohmann::json\>
 - std::less<nlohmann::value_t\>
 - std::swap<nlohmann::json\>
+
+## See also
+
+- [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259)

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

@@ -0,0 +1,153 @@
+# basic_json::swap
+
+```cpp
+// (1)
+void swap(reference other) noexcept;
+
+// (2)
+void swap(reference left, reference right) noexcept;
+
+// (3)
+void swap(array_t& other);
+
+// (4)
+void swap(object_t& other);
+
+// (5)
+void swap(string_t& other);
+
+// (6)
+void swap(binary_t& other);
+
+// (7)
+void swap(typename binary_t::container_type& other);
+```
+
+1. Exchanges the contents of the JSON value with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. 
+2. Exchanges the contents of the JSON value from `left` with those of `right`. Does not invoke any move, copy, or swap
+   operations on individual elements. All iterators and references remain valid. The past-the-end iterator is
+   invalidated. Implemented as a friend function callable via ADL.
+3. Exchanges the contents of a JSON array with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. 
+4. Exchanges the contents of a JSON object with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+5. Exchanges the contents of a JSON string with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+6. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated.
+7. Exchanges the contents of a binary value with those of `other`. Does not invoke any move, copy, or swap operations on
+   individual elements. All iterators and references remain valid. The past-the-end iterator is invalidated. Unlike
+   version (6), no binary subtype is involved.
+
+## Parameters
+
+`other` (in, out)
+:   value to exchange the contents with
+
+`left` (in, out)
+:   value to exchange the contents with
+
+`right` (in, out)
+:   value to exchange the contents with
+
+## Exceptions
+
+1. No-throw guarantee: this function never throws exceptions.
+2. No-throw guarantee: this function never throws exceptions.
+3. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   arrays; example: `"cannot use swap() with boolean"`
+4. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   objects; example: `"cannot use swap() with boolean"`
+5. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   strings; example: `"cannot use swap() with boolean"`
+6. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   binaries; example: `"cannot use swap() with boolean"`
+7. Throws [`type_error.310`](../../home/exceptions.md#jsonexceptiontype_error310) if called on JSON values other than
+   binaries; example: `"cannot use swap() with boolean"`
+
+## Complexity
+
+Constant.
+
+## Example
+
+??? example "Example: Swap JSON value (1, 2)"
+
+    The example below shows how JSON values can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__reference.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__reference.output"
+    ```
+
+??? example "Example: Swap array (3)"
+
+    The example below shows how arrays can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__array_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__array_t.output"
+    ```
+
+??? example "Example: Swap object (4)"
+
+    The example below shows how objects can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__object_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__object_t.output"
+    ```
+
+??? example "Example: Swap string (5)"
+
+    The example below shows how strings can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__string_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__string_t.output"
+    ```
+
+??? example "Example: Swap string (6)"
+
+    The example below shows how binary values can be swapped with `swap()`.
+    
+    ```cpp
+    --8<-- "examples/swap__binary_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/swap__binary_t.output"
+    ```
+
+## Version history
+
+1. Since version 1.0.0.
+2. Since version 1.0.0.
+3. Since version 1.0.0.
+4. Since version 1.0.0.
+5. Since version 1.0.0.
+6. Since version 3.8.0.
+7. Since version 3.8.0.

doc/mkdocs/mkdocs.yml

@@ -167,6 +167,7 @@ nav:
         - api/basic_json/sax_parse.md
         - api/basic_json/size.md
         - api/basic_json/string_t.md
+        - api/basic_json/swap.md
         - api/basic_json/to_bson.md
         - api/basic_json/to_cbor.md
         - api/basic_json/to_msgpack.md

include/nlohmann/json.hpp

@@ -91,69 +91,7 @@ namespace nlohmann
 /*!
 @brief a class to store JSON values
 
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
+@internal
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam BinaryType type for packed binary data for compatibility with binary
-serialization formats (`std::vector<std::uint8_t>` by default; will be used in
-@ref binary_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
-
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible):
-   JSON values can be default constructed. The result will be a JSON null
-   value.
- - [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible):
-   A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible):
-   A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable):
-   A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable):
-   A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible):
-   JSON values can be destructed.
-- Layout
- - [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType):
-   JSON values have
-   [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
-   All non-static data members are private and standard layout types, the
-   class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable):
-   JSON values can be compared with `==`, see @ref
-   operator==(const_reference,const_reference).
- - [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable):
-   JSON values can be compared with `<`, see @ref
-   operator<(const_reference,const_reference).
- - [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable):
-   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
-   other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer):
-   JSON values can be compared against `std::nullptr_t` objects which are used
-   to model the `null` value.
-- Container
- - [Container](https://en.cppreference.com/w/cpp/named_req/Container):
-   JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer);
-   JSON values can be used like STL containers and provide reverse iterator
-   access.
-
 @invariant The member variables @a m_value and @a m_type have the following
 relationship:
 - If `m_type == value_t::object`, then `m_value.object != nullptr`.
@@ -161,13 +99,9 @@ relationship:
 - If `m_type == value_t::string`, then `m_value.string != nullptr`.
 The invariants are checked by member function assert_invariant().
 
-@internal
 @note ObjectType trick from https://stackoverflow.com/a/9860911
 @endinternal
 
-@see [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange
-Format](https://tools.ietf.org/html/rfc8259)
-
 @since version 1.0.0
 
 @nosubgrouping
@@ -258,17 +192,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /// Classes to implement user-defined exceptions.
     /// @{
 
-    /// @copydoc detail::exception
     using exception = detail::exception;
-    /// @copydoc detail::parse_error
     using parse_error = detail::parse_error;
-    /// @copydoc detail::invalid_iterator
     using invalid_iterator = detail::invalid_iterator;
-    /// @copydoc detail::type_error
     using type_error = detail::type_error;
-    /// @copydoc detail::out_of_range
     using out_of_range = detail::out_of_range;
-    /// @copydoc detail::other_error
     using other_error = detail::other_error;
 
     /// @}
@@ -1010,33 +938,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
-    /*!
+    /// @brief explicitly create a binary array (without subtype)
-    @brief explicitly create a binary array (without subtype)
+    /// @sa https://json.nlohmann.me/api/basic_json/binary/
-
-    Creates a JSON binary array value from a given binary container. Binary
-    values are part of various binary formats, such as CBOR, MessagePack, and
-    BSON. This constructor is used to create a value for serialization to those
-    formats.
-
-    @note Note, this function exists because of the difficulty in correctly
-    specifying the correct template overload in the standard value ctor, as both
-    JSON arrays and JSON binary arrays are backed with some form of a
-    `std::vector`. Because JSON binary arrays are a non-standard extension it
-    was decided that it would be best to prevent automatic initialization of a
-    binary array type, for backwards compatibility and so it does not happen on
-    accident.
-
-    @param[in] init container containing bytes to use as binary type
-
-    @return JSON binary array value
-
-    @complexity Linear in the size of @a init.
-
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes to any JSON value.
-
-    @since version 3.8.0
-    */
     JSON_HEDLEY_WARN_UNUSED_RESULT
     static basic_json binary(const typename binary_t::container_type& init)
     {
@@ -3322,23 +3225,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of the JSON value with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other JSON value to exchange the contents with
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
-
-    @since version 1.0.0
-    */
     void swap(reference other) noexcept (
         std::is_nothrow_move_constructible<value_t>::value&&
         std::is_nothrow_move_assignable<value_t>::value&&
@@ -3354,24 +3242,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of the JSON value from @a left with those of @a right. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated. implemented as a friend function callable via ADL.
-
-    @param[in,out] left JSON value to exchange the contents with
-    @param[in,out] right JSON value to exchange the contents with
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
-
-    @since version 1.0.0
-    */
     friend void swap(reference left, reference right) noexcept (
         std::is_nothrow_move_constructible<value_t>::value&&
         std::is_nothrow_move_assignable<value_t>::value&&
@@ -3382,26 +3254,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         left.swap(right);
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON array with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other array to exchange the contents with
-
-    @throw type_error.310 when JSON value is not an array; example: `"cannot
-    use swap() with string"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how arrays can be swapped with
-    `swap()`.,swap__array_t}
-
-    @since version 1.0.0
-    */
     void swap(array_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for arrays
@@ -3415,26 +3269,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON object with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other object to exchange the contents with
-
-    @throw type_error.310 when JSON value is not an object; example:
-    `"cannot use swap() with string"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how objects can be swapped with
-    `swap()`.,swap__object_t}
-
-    @since version 1.0.0
-    */
     void swap(object_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for objects
@@ -3448,26 +3284,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other string to exchange the contents with
-
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__string_t}
-
-    @since version 1.0.0
-    */
     void swap(string_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for strings
@@ -3481,26 +3299,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other binary to exchange the contents with
-
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__binary_t}
-
-    @since version 3.8.0
-    */
     void swap(binary_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for strings
@@ -3514,7 +3314,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /// @copydoc swap(binary_t&)
+    /// @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
     void swap(typename binary_t::container_type& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for strings

single_include/nlohmann/json.hpp

@@ -17592,69 +17592,7 @@ namespace nlohmann
 /*!
 @brief a class to store JSON values
 
-@tparam ObjectType type for JSON objects (`std::map` by default; will be used
+@internal
-in @ref object_t)
-@tparam ArrayType type for JSON arrays (`std::vector` by default; will be used
-in @ref array_t)
-@tparam StringType type for JSON strings and object keys (`std::string` by
-default; will be used in @ref string_t)
-@tparam BooleanType type for JSON booleans (`bool` by default; will be used
-in @ref boolean_t)
-@tparam NumberIntegerType type for JSON integer numbers (`int64_t` by
-default; will be used in @ref number_integer_t)
-@tparam NumberUnsignedType type for JSON unsigned integer numbers (@c
-`uint64_t` by default; will be used in @ref number_unsigned_t)
-@tparam NumberFloatType type for JSON floating-point numbers (`double` by
-default; will be used in @ref number_float_t)
-@tparam BinaryType type for packed binary data for compatibility with binary
-serialization formats (`std::vector<std::uint8_t>` by default; will be used in
-@ref binary_t)
-@tparam AllocatorType type of the allocator to use (`std::allocator` by
-default)
-@tparam JSONSerializer the serializer to resolve internal calls to `to_json()`
-and `from_json()` (@ref adl_serializer by default)
-
-@requirement The class satisfies the following concept requirements:
-- Basic
- - [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible):
-   JSON values can be default constructed. The result will be a JSON null
-   value.
- - [MoveConstructible](https://en.cppreference.com/w/cpp/named_req/MoveConstructible):
-   A JSON value can be constructed from an rvalue argument.
- - [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible):
-   A JSON value can be copy-constructed from an lvalue expression.
- - [MoveAssignable](https://en.cppreference.com/w/cpp/named_req/MoveAssignable):
-   A JSON value van be assigned from an rvalue argument.
- - [CopyAssignable](https://en.cppreference.com/w/cpp/named_req/CopyAssignable):
-   A JSON value can be copy-assigned from an lvalue expression.
- - [Destructible](https://en.cppreference.com/w/cpp/named_req/Destructible):
-   JSON values can be destructed.
-- Layout
- - [StandardLayoutType](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType):
-   JSON values have
-   [standard layout](https://en.cppreference.com/w/cpp/language/data_members#Standard_layout):
-   All non-static data members are private and standard layout types, the
-   class has no virtual functions or (virtual) base classes.
-- Library-wide
- - [EqualityComparable](https://en.cppreference.com/w/cpp/named_req/EqualityComparable):
-   JSON values can be compared with `==`, see @ref
-   operator==(const_reference,const_reference).
- - [LessThanComparable](https://en.cppreference.com/w/cpp/named_req/LessThanComparable):
-   JSON values can be compared with `<`, see @ref
-   operator<(const_reference,const_reference).
- - [Swappable](https://en.cppreference.com/w/cpp/named_req/Swappable):
-   Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
-   other compatible types, using unqualified function call @ref swap().
- - [NullablePointer](https://en.cppreference.com/w/cpp/named_req/NullablePointer):
-   JSON values can be compared against `std::nullptr_t` objects which are used
-   to model the `null` value.
-- Container
- - [Container](https://en.cppreference.com/w/cpp/named_req/Container):
-   JSON values can be used like STL containers and provide iterator access.
- - [ReversibleContainer](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer);
-   JSON values can be used like STL containers and provide reverse iterator
-   access.
-
 @invariant The member variables @a m_value and @a m_type have the following
 relationship:
 - If `m_type == value_t::object`, then `m_value.object != nullptr`.
@@ -17662,13 +17600,9 @@ relationship:
 - If `m_type == value_t::string`, then `m_value.string != nullptr`.
 The invariants are checked by member function assert_invariant().
 
-@internal
 @note ObjectType trick from https://stackoverflow.com/a/9860911
 @endinternal
 
-@see [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange
-Format](https://tools.ietf.org/html/rfc8259)
-
 @since version 1.0.0
 
 @nosubgrouping
@@ -17759,17 +17693,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     /// Classes to implement user-defined exceptions.
     /// @{
 
-    /// @copydoc detail::exception
     using exception = detail::exception;
-    /// @copydoc detail::parse_error
     using parse_error = detail::parse_error;
-    /// @copydoc detail::invalid_iterator
     using invalid_iterator = detail::invalid_iterator;
-    /// @copydoc detail::type_error
     using type_error = detail::type_error;
-    /// @copydoc detail::out_of_range
     using out_of_range = detail::out_of_range;
-    /// @copydoc detail::other_error
     using other_error = detail::other_error;
 
     /// @}
@@ -18511,33 +18439,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
-    /*!
+    /// @brief explicitly create a binary array (without subtype)
-    @brief explicitly create a binary array (without subtype)
+    /// @sa https://json.nlohmann.me/api/basic_json/binary/
-
-    Creates a JSON binary array value from a given binary container. Binary
-    values are part of various binary formats, such as CBOR, MessagePack, and
-    BSON. This constructor is used to create a value for serialization to those
-    formats.
-
-    @note Note, this function exists because of the difficulty in correctly
-    specifying the correct template overload in the standard value ctor, as both
-    JSON arrays and JSON binary arrays are backed with some form of a
-    `std::vector`. Because JSON binary arrays are a non-standard extension it
-    was decided that it would be best to prevent automatic initialization of a
-    binary array type, for backwards compatibility and so it does not happen on
-    accident.
-
-    @param[in] init container containing bytes to use as binary type
-
-    @return JSON binary array value
-
-    @complexity Linear in the size of @a init.
-
-    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
-    changes to any JSON value.
-
-    @since version 3.8.0
-    */
     JSON_HEDLEY_WARN_UNUSED_RESULT
     static basic_json binary(const typename binary_t::container_type& init)
     {
@@ -20823,23 +20726,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of the JSON value with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other JSON value to exchange the contents with
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
-
-    @since version 1.0.0
-    */
     void swap(reference other) noexcept (
         std::is_nothrow_move_constructible<value_t>::value&&
         std::is_nothrow_move_assignable<value_t>::value&&
@@ -20855,24 +20743,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         assert_invariant();
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of the JSON value from @a left with those of @a right. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated. implemented as a friend function callable via ADL.
-
-    @param[in,out] left JSON value to exchange the contents with
-    @param[in,out] right JSON value to exchange the contents with
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how JSON values can be swapped with
-    `swap()`.,swap__reference}
-
-    @since version 1.0.0
-    */
     friend void swap(reference left, reference right) noexcept (
         std::is_nothrow_move_constructible<value_t>::value&&
         std::is_nothrow_move_assignable<value_t>::value&&
@@ -20883,26 +20755,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         left.swap(right);
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON array with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other array to exchange the contents with
-
-    @throw type_error.310 when JSON value is not an array; example: `"cannot
-    use swap() with string"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how arrays can be swapped with
-    `swap()`.,swap__array_t}
-
-    @since version 1.0.0
-    */
     void swap(array_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for arrays
@@ -20916,26 +20770,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON object with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other object to exchange the contents with
-
-    @throw type_error.310 when JSON value is not an object; example:
-    `"cannot use swap() with string"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how objects can be swapped with
-    `swap()`.,swap__object_t}
-
-    @since version 1.0.0
-    */
     void swap(object_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for objects
@@ -20949,26 +20785,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other string to exchange the contents with
-
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__string_t}
-
-    @since version 1.0.0
-    */
     void swap(string_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for strings
@@ -20982,26 +20800,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /*!
+    /// @brief exchanges the values
-    @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
-
-    Exchanges the contents of a JSON string with those of @a other. Does not
-    invoke any move, copy, or swap operations on individual elements. All
-    iterators and references remain valid. The past-the-end iterator is
-    invalidated.
-
-    @param[in,out] other binary to exchange the contents with
-
-    @throw type_error.310 when JSON value is not a string; example: `"cannot
-    use swap() with boolean"`
-
-    @complexity Constant.
-
-    @liveexample{The example below shows how strings can be swapped with
-    `swap()`.,swap__binary_t}
-
-    @since version 3.8.0
-    */
     void swap(binary_t& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for strings
@@ -21015,7 +20815,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
         }
     }
 
-    /// @copydoc swap(binary_t&)
+    /// @brief exchanges the values
+    /// @sa https://json.nlohmann.me/api/basic_json/swap/
     void swap(typename binary_t::container_type& other) // NOLINT(bugprone-exception-escape)
     {
         // swap only works for strings