🔥 consolidate documentation

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

@@ -8,9 +8,10 @@ This type is a type designed to carry binary data that appears in various serial
 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for
 compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
 
-Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint8_t`, which
+Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint64_t`, which
 is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is
-incompatible with each other, and it is up to the user to translate between them).
+incompatible with each other, and it is up to the user to translate between them). The subtype is added to `BinaryType`
+via the helper type [byte_container_with_subtype](../byte_container_with_subtype.md).
 
 [CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
 > Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
@@ -62,6 +63,10 @@ type `#!cpp binary_t*` must be dereferenced.
     - If a subtype is given, it is used and added as unsigned 8-bit integer.
     - If no subtype is given, the generic binary subtype 0x00 is used.
 
+## See also
+
+- [byte_container_with_subtype](../byte_container_with_subtype.md)
+
 ## Version history
 
 - Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0.

doc/mkdocs/docs/api/byte_container_with_subtype.md

@@ -0,0 +1,36 @@
+# byte_container_with_subtype
+
+```cpp
+template<typename BinaryType>
+class byte_container_with_subtype : public BinaryType
+```
+
+This type extends the template parameter `BinaryType` provided to [`basic_json`](basic_json/index.md) with a subtype
+used by BSON and MessagePack. This type exists so that the user does not have to specify a type themselves with a
+specific naming scheme in  order to override the binary type.
+
+## Template parameters
+
+`BinaryType`
+:   container to store bytes (`#!cpp std::vector<std::uint8_t>` by default)
+
+## Member types
+
+- **container_type** - the type of the underlying container (`BinaryType`)
+- **subtype_type** - the type of the subtype (`#!cpp std::uint64_t`)
+
+## Member functions
+
+- (constructor)
+- (destructor)
+- **operator==** - comparison: equal
+- **operator!=** - comparison: not equal
+- **set_subtype** - sets the binary subtype
+- **subtype** - return the binary subtype
+- **has_subtype** - return whether the value has a subtype
+- **clear_subtype** - clears the binary subtype
+
+## Version history
+
+- Added in version 3.8.0.
+- Changed type of subtypes to `#!cpp std::uint64_t` in 3.10.0.

doc/mkdocs/docs/api/ordered_map.md

@@ -5,3 +5,45 @@ template<class Key, class T, class IgnoredLess = std::less<Key>,
          class Allocator = std::allocator<std::pair<const Key, T>>>
 struct ordered_map : std::vector<std::pair<const Key, T>, Allocator>;
 ```
+
+A minimal map-like container that preserves insertion order for use within `nlohmann::basic_json<ordered_map>`.
+
+## Template parameters
+
+`Key`
+:   key type
+
+`T`
+:   mapped type
+
+`IgnoredLess`
+:   comparison function (ignored and only added to ensure compatibility with `std::map`)
+
+`Allocator`
+:   allocator type
+
+## Member types
+
+- **key_type** - key type (`Key`)
+- **mapped_type** - mapped type (`T`)
+- **Container** - base container type (`#!cpp std::vector<std::pair<const Key, T>, Allocator>`)
+- **iterator**
+- **const_iterator**
+- **size_type**
+- **value_type**
+
+## Member functions
+
+- (constructor)
+- (destructor)
+- **emplace**
+- **operator\[\]**
+- **at**
+- **erase**
+- **count**
+- **find**
+- **insert**
+
+## Version history
+
+- Added in version 3.9.0 to implement [`nlohmann::ordered_json`](ordered_json.md).

doc/mkdocs/mkdocs.yml

@@ -181,6 +181,7 @@ nav:
         - api/basic_json/update.md
         - api/basic_json/value.md
         - api/basic_json/value_t.md
+      - api/byte_container_with_subtype.md
       - adl_serializer:
         - api/adl_serializer/index.md
         - api/adl_serializer/from_json.md

include/nlohmann/adl_serializer.hpp

@@ -14,17 +14,8 @@ namespace nlohmann
 template<typename ValueType, typename>
 struct adl_serializer
 {
-    /*!
-    @brief convert a JSON value to any value type
-
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
-
-    @note This function is chosen for default-constructible value types.
-
-    @param[in] j        JSON value to read from
-    @param[in,out] val  value to write to
-    */
+    /// @brief convert a JSON value to any value type
+    /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
     template<typename BasicJsonType, typename TargetType = ValueType>
     static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
         noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
@@ -33,18 +24,8 @@ struct adl_serializer
         ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
     }
 
-    /*!
-    @brief convert a JSON value to any value type
-
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
-
-    @note This function is chosen for value types which are not default-constructible.
-
-    @param[in] j  JSON value to read from
-
-    @return copy of the JSON value, converted to @a ValueType
-    */
+    /// @brief convert a JSON value to any value type
+    /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
     template<typename BasicJsonType, typename TargetType = ValueType>
     static auto from_json(BasicJsonType && j) noexcept(
     noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))
@@ -53,15 +34,8 @@ struct adl_serializer
         return ::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {});
     }
 
-    /*!
-    @brief convert any value type to a JSON value
-
-    This function is usually called by the constructors of the @ref basic_json
-    class.
-
-    @param[in,out] j  JSON value to write to
-    @param[in] val    value to read from
-    */
+    /// @brief convert any value type to a JSON value
+    /// @sa https://json.nlohmann.me/api/adl_serializer/to_json/
     template<typename BasicJsonType, typename TargetType = ValueType>
     static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
         noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))

single_include/nlohmann/json.hpp

@@ -5041,17 +5041,8 @@ namespace nlohmann
 template<typename ValueType, typename>
 struct adl_serializer
 {
-    /*!
-    @brief convert a JSON value to any value type
-
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
-
-    @note This function is chosen for default-constructible value types.
-
-    @param[in] j        JSON value to read from
-    @param[in,out] val  value to write to
-    */
+    /// @brief convert a JSON value to any value type
+    /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
     template<typename BasicJsonType, typename TargetType = ValueType>
     static auto from_json(BasicJsonType && j, TargetType& val) noexcept(
         noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), val)))
@@ -5060,18 +5051,8 @@ struct adl_serializer
         ::nlohmann::from_json(std::forward<BasicJsonType>(j), val);
     }
 
-    /*!
-    @brief convert a JSON value to any value type
-
-    This function is usually called by the `get()` function of the
-    @ref basic_json class (either explicit or via conversion operators).
-
-    @note This function is chosen for value types which are not default-constructible.
-
-    @param[in] j  JSON value to read from
-
-    @return copy of the JSON value, converted to @a ValueType
-    */
+    /// @brief convert a JSON value to any value type
+    /// @sa https://json.nlohmann.me/api/adl_serializer/from_json/
     template<typename BasicJsonType, typename TargetType = ValueType>
     static auto from_json(BasicJsonType && j) noexcept(
     noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {})))
@@ -5080,15 +5061,8 @@ struct adl_serializer
         return ::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {});
     }
 
-    /*!
-    @brief convert any value type to a JSON value
-
-    This function is usually called by the constructors of the @ref basic_json
-    class.
-
-    @param[in,out] j  JSON value to write to
-    @param[in] val    value to read from
-    */
+    /// @brief convert any value type to a JSON value
+    /// @sa https://json.nlohmann.me/api/adl_serializer/to_json/
     template<typename BasicJsonType, typename TargetType = ValueType>
     static auto to_json(BasicJsonType& j, TargetType && val) noexcept(
         noexcept(::nlohmann::to_json(j, std::forward<TargetType>(val))))