🔥 consolidate documentation

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

@@ -11,7 +11,7 @@ compatibility with these binary types. As such, it is simply defined as an order
 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). The subtype is added to `BinaryType`
-via the helper type [byte_container_with_subtype](../byte_container_with_subtype.md).
+via the helper type [byte_container_with_subtype](../byte_container_with_subtype/index.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
@@ -65,7 +65,7 @@ type `#!cpp binary_t*` must be dereferenced.
 
 ## See also
 
-- [byte_container_with_subtype](../byte_container_with_subtype.md)
+- [byte_container_with_subtype](../byte_container_with_subtype/index.md)
 
 ## Version history
 

doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md

@@ -0,0 +1,27 @@
+# byte_container_with_subtype::byte_container_with_subtype
+
+```cpp
+// (1)
+byte_container_with_subtype();
+
+// (2)
+byte_container_with_subtype(const container_type& container);
+byte_container_with_subtype(container_type&& container);
+
+// (3)
+byte_container_with_subtype(const container_type& container, subtype_type subtype);
+byte_container_with_subtype(container_type&& container, subtype_type subtype);
+```
+
+1. Create empty binary container without subtype.
+2. Create binary container without subtype.
+3. Create binary container with subtype.
+
+## Parameters
+
+`container` (in)
+:   binary container
+
+`subtype` (in)
+:   subtype
+

doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md

@@ -0,0 +1,20 @@
+# byte_container_with_subtype::clear_subtype
+
+```cpp
+void clear_subtype() noexcept;
+```
+
+Clears the binary subtype and flags the value as not having a subtype, which has implications for serialization; for
+instance MessagePack will prefer the bin family over the ext family.
+
+## Complexity
+
+Constant.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Version history
+
+Since version 3.8.0.

doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md

@@ -0,0 +1,23 @@
+# byte_container_with_subtype::has_subtype
+
+```cpp
+constexpr bool has_subtype() const noexcept;
+```
+
+Returns whether the value has a subtype.
+
+## Return value
+
+whether the value has a subtype
+
+## Complexity
+
+Constant.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Version history
+
+Since version 3.8.0.

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

@@ -5,7 +5,7 @@ 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
+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.
 
@@ -21,14 +21,13 @@ specific naming scheme in  order to override the binary type.
 
 ## Member functions
 
-- (constructor)
+- [(constructor)](byte_container_with_subtype.md)
-- (destructor)
 - **operator==** - comparison: equal
 - **operator!=** - comparison: not equal
-- **set_subtype** - sets the binary subtype
+- [**set_subtype**](subtype.md) - sets the binary subtype
-- **subtype** - return the binary subtype
+- [**subtype**](subtype.md) - return the binary subtype
-- **has_subtype** - return whether the value has a subtype
+- [**has_subtype**](has_subtype.md) - return whether the value has a subtype
-- **clear_subtype** - clears the binary subtype
+- [**clear_subtype**](clear_subtype.md) - clears the binary subtype
 
 ## Version history
 

doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md

@@ -0,0 +1,25 @@
+# byte_container_with_subtype::set_subtype
+
+```cpp
+void set_subtype(subtype_type subtype) noexcept
+```
+
+Sets the binary subtype of the value, also flags a binary JSON value as having a subtype, which has implications for
+serialization.
+
+## Parameters
+
+`subtype` (in)
+:   subtype to set
+
+## Complexity
+
+Constant.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Version history
+
+Since version 3.8.0.

doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md

@@ -0,0 +1,25 @@
+# byte_container_with_subtype::subtype
+
+```cpp
+constexpr subtype_type subtype() const noexcept;
+```
+
+Returns the numerical subtype of the value if it has a subtype. If it does not have a subtype, this function will return
+`subtype_type(-1)` as a sentinel value.
+
+## Return value
+
+the numerical subtype of the binary value, or `subtype_type(-1)` if no subtype is set
+
+## Complexity
+
+Constant.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Version history
+
+- Added in version 3.8.0
+- Fixed return value to properly return `subtype_type(-1)` as documented in version 3.10.0.

doc/mkdocs/mkdocs.yml

@@ -145,8 +145,6 @@ nav:
         - api/basic_json/operator_value_t.md
         - api/basic_json/operator[].md
         - api/basic_json/operator=.md
-        - 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
@@ -182,7 +180,13 @@ nav:
         - api/basic_json/update.md
         - api/basic_json/value.md
         - api/basic_json/value_t.md
-      - api/byte_container_with_subtype.md
+      - byte_container_with_subtype:
+        - 'Overview': api/byte_container_with_subtype/index.md
+        - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
+        - 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md
+        - 'has_subtype': api/byte_container_with_subtype/has_subtype.md
+        - 'set_subtype': api/byte_container_with_subtype/set_subtype.md
+        - 'subtype': api/byte_container_with_subtype/subtype.md
       - adl_serializer:
         - api/adl_serializer/index.md
         - api/adl_serializer/from_json.md

include/nlohmann/byte_container_with_subtype.hpp

@@ -7,46 +7,38 @@
 namespace nlohmann
 {
 
-/*!
+/// @brief an internal type for a backed binary type
-@brief an internal type for a backed binary type
+/// @sa https://json.nlohmann.me/api/byte_container_with_subtype/
-
-This type extends the template parameter @a BinaryType provided to `basic_json`
-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.
-
-@tparam BinaryType container to store bytes (`std::vector<std::uint8_t>` by
-                   default)
-
-@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.10.0.
-*/
 template<typename BinaryType>
 class byte_container_with_subtype : public BinaryType
 {
   public:
-    /// the type of the underlying container
     using container_type = BinaryType;
-    /// the type of the subtype
     using subtype_type = std::uint64_t;
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype() noexcept(noexcept(container_type()))
         : container_type()
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(const container_type& b) noexcept(noexcept(container_type(b)))
         : container_type(b)
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(container_type&& b) noexcept(noexcept(container_type(std::move(b))))
         : container_type(std::move(b))
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(const container_type& b, subtype_type subtype_) noexcept(noexcept(container_type(b)))
         : container_type(b)
         , m_subtype(subtype_)
         , m_has_subtype(true)
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(container_type&& b, subtype_type subtype_) noexcept(noexcept(container_type(std::move(b))))
         : container_type(std::move(b))
         , m_subtype(subtype_)
@@ -64,97 +56,30 @@ class byte_container_with_subtype : public BinaryType
         return !(rhs == *this);
     }
 
-    /*!
+    /// @brief sets the binary subtype
-    @brief sets the binary subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/set_subtype/
-
-    Sets the binary subtype of the value, also flags a binary JSON value as
-    having a subtype, which has implications for serialization.
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref subtype() -- return the binary subtype
-    @sa see @ref clear_subtype() -- clears the binary subtype
-    @sa see @ref has_subtype() -- returns whether or not the binary value has a
-    subtype
-
-    @since version 3.8.0
-    */
     void set_subtype(subtype_type subtype_) noexcept
     {
         m_subtype = subtype_;
         m_has_subtype = true;
     }
 
-    /*!
+    /// @brief return the binary subtype
-    @brief return the binary subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype/
-
-    Returns the numerical subtype of the value if it has a subtype. If it does
-    not have a subtype, this function will return subtype_type(-1) as a sentinel
-    value.
-
-    @return the numerical subtype of the binary value
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref set_subtype() -- sets the binary subtype
-    @sa see @ref clear_subtype() -- clears the binary subtype
-    @sa see @ref has_subtype() -- returns whether or not the binary value has a
-    subtype
-
-    @since version 3.8.0; fixed return value to properly return
-           subtype_type(-1) as documented in version 3.10.0
-    */
     constexpr subtype_type subtype() const noexcept
     {
         return m_has_subtype ? m_subtype : subtype_type(-1);
     }
 
-    /*!
+    /// @brief return whether the value has a subtype
-    @brief return whether the value has a subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/has_subtype/
-
-    @return whether the value has a subtype
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref subtype() -- return the binary subtype
-    @sa see @ref set_subtype() -- sets the binary subtype
-    @sa see @ref clear_subtype() -- clears the binary subtype
-
-    @since version 3.8.0
-    */
     constexpr bool has_subtype() const noexcept
     {
         return m_has_subtype;
     }
 
-    /*!
+    /// @brief clears the binary subtype
-    @brief clears the binary subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/clear_subtype/
-
-    Clears the binary subtype and flags the value as not having a subtype, which
-    has implications for serialization; for instance MessagePack will prefer the
-    bin family over the ext family.
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref subtype() -- return the binary subtype
-    @sa see @ref set_subtype() -- sets the binary subtype
-    @sa see @ref has_subtype() -- returns whether or not the binary value has a
-    subtype
-
-    @since version 3.8.0
-    */
     void clear_subtype() noexcept
     {
         m_subtype = 0;

single_include/nlohmann/json.hpp

@@ -5083,46 +5083,38 @@ struct adl_serializer
 namespace nlohmann
 {
 
-/*!
+/// @brief an internal type for a backed binary type
-@brief an internal type for a backed binary type
+/// @sa https://json.nlohmann.me/api/byte_container_with_subtype/
-
-This type extends the template parameter @a BinaryType provided to `basic_json`
-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.
-
-@tparam BinaryType container to store bytes (`std::vector<std::uint8_t>` by
-                   default)
-
-@since version 3.8.0; changed type of subtypes to std::uint64_t in 3.10.0.
-*/
 template<typename BinaryType>
 class byte_container_with_subtype : public BinaryType
 {
   public:
-    /// the type of the underlying container
     using container_type = BinaryType;
-    /// the type of the subtype
     using subtype_type = std::uint64_t;
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype() noexcept(noexcept(container_type()))
         : container_type()
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(const container_type& b) noexcept(noexcept(container_type(b)))
         : container_type(b)
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(container_type&& b) noexcept(noexcept(container_type(std::move(b))))
         : container_type(std::move(b))
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(const container_type& b, subtype_type subtype_) noexcept(noexcept(container_type(b)))
         : container_type(b)
         , m_subtype(subtype_)
         , m_has_subtype(true)
     {}
 
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/byte_container_with_subtype/
     byte_container_with_subtype(container_type&& b, subtype_type subtype_) noexcept(noexcept(container_type(std::move(b))))
         : container_type(std::move(b))
         , m_subtype(subtype_)
@@ -5140,97 +5132,30 @@ class byte_container_with_subtype : public BinaryType
         return !(rhs == *this);
     }
 
-    /*!
+    /// @brief sets the binary subtype
-    @brief sets the binary subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/set_subtype/
-
-    Sets the binary subtype of the value, also flags a binary JSON value as
-    having a subtype, which has implications for serialization.
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref subtype() -- return the binary subtype
-    @sa see @ref clear_subtype() -- clears the binary subtype
-    @sa see @ref has_subtype() -- returns whether or not the binary value has a
-    subtype
-
-    @since version 3.8.0
-    */
     void set_subtype(subtype_type subtype_) noexcept
     {
         m_subtype = subtype_;
         m_has_subtype = true;
     }
 
-    /*!
+    /// @brief return the binary subtype
-    @brief return the binary subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/subtype/
-
-    Returns the numerical subtype of the value if it has a subtype. If it does
-    not have a subtype, this function will return subtype_type(-1) as a sentinel
-    value.
-
-    @return the numerical subtype of the binary value
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref set_subtype() -- sets the binary subtype
-    @sa see @ref clear_subtype() -- clears the binary subtype
-    @sa see @ref has_subtype() -- returns whether or not the binary value has a
-    subtype
-
-    @since version 3.8.0; fixed return value to properly return
-           subtype_type(-1) as documented in version 3.10.0
-    */
     constexpr subtype_type subtype() const noexcept
     {
         return m_has_subtype ? m_subtype : subtype_type(-1);
     }
 
-    /*!
+    /// @brief return whether the value has a subtype
-    @brief return whether the value has a subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/has_subtype/
-
-    @return whether the value has a subtype
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref subtype() -- return the binary subtype
-    @sa see @ref set_subtype() -- sets the binary subtype
-    @sa see @ref clear_subtype() -- clears the binary subtype
-
-    @since version 3.8.0
-    */
     constexpr bool has_subtype() const noexcept
     {
         return m_has_subtype;
     }
 
-    /*!
+    /// @brief clears the binary subtype
-    @brief clears the binary subtype
+    /// @sa https://json.nlohmann.me/api/byte_container_with_subtype/clear_subtype/
-
-    Clears the binary subtype and flags the value as not having a subtype, which
-    has implications for serialization; for instance MessagePack will prefer the
-    bin family over the ext family.
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this member function never throws
-    exceptions.
-
-    @sa see @ref subtype() -- return the binary subtype
-    @sa see @ref set_subtype() -- sets the binary subtype
-    @sa see @ref has_subtype() -- returns whether or not the binary value has a
-    subtype
-
-    @since version 3.8.0
-    */
     void clear_subtype() noexcept
     {
         m_subtype = 0;