🔥 consolidate documentation

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

@@ -18,11 +18,6 @@ template<
 class basic_json;
 ```
 
-## Specializations
-
-- [**json**](../json.md) - default specialization
-- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
-
 ## Template parameters
 
 | Template parameter   | Description | Derived type |
@@ -38,6 +33,11 @@ class basic_json;
 | `JSONSerializer`     | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
 | `BinaryType`         | type for binary arrays | [`binary_t`](binary_t.md) |
 
+## Specializations
+
+- [**json**](../json.md) - default specialization
+- [**ordered_json**](../ordered_json.md) - specialization that maintains the insertion order of object keys
+
 ## Iterator invalidation
 
 Todo

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

@@ -5,7 +5,9 @@ template<typename BasicJsonType>
 class json_pointer;
 ```
 
-JSON Pointer defines a string syntax for identifying a specific value within a JSON document.
+A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with
+functions [`at`](../basic_json/at.md) and [`operator[]`](../basic_json/operator%5B%5D.md). Furthermore, JSON pointers
+are the base for JSON patches.
 
 ## Template parameters
 
@@ -27,7 +29,7 @@ JSON Pointer defines a string syntax for identifying a specific value within a J
 
 ## See also
 
-[RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
+- [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
 
 ## Version history
 

doc/mkdocs/docs/features/json_pointer.md

@@ -13,3 +13,7 @@ json j_original = R"({
 j_original["/baz/1"_json_pointer];
 // "two"
 ```
+
+## See also
+
+- Class [`json_pointer`](../api/json_pointer/index.md)

doc/mkdocs/scripts/check_structure.py

@@ -5,8 +5,8 @@ import glob
 
 def check_structure():
     expected_headers = [
-        'Specializations',
         'Template parameters',
+        'Specializations',
         'Iterator invalidation',
         'Requirements',
         'Member types',

include/nlohmann/adl_serializer.hpp

@@ -11,6 +11,7 @@
 namespace nlohmann
 {
 
+/// @sa https://json.nlohmann.me/api/adl_serializer/
 template<typename ValueType, typename>
 struct adl_serializer
 {

include/nlohmann/json_fwd.hpp

@@ -24,6 +24,8 @@ for serialization.
 template<typename T = void, typename SFINAE = void>
 struct adl_serializer;
 
+/// a class to store JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/
 template<template<typename U, typename V, typename... Args> class ObjectType =
          std::map,
          template<typename U, typename... Args> class ArrayType = std::vector,
@@ -37,40 +39,24 @@ template<template<typename U, typename V, typename... Args> class ObjectType =
          class BinaryType = std::vector<std::uint8_t>>
 class basic_json;
 
-/*!
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
-@brief JSON Pointer
+/// @sa https://json.nlohmann.me/api/json_pointer/
-
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
-
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
-
-@since version 2.0.0
-*/
 template<typename BasicJsonType>
 class json_pointer;
 
 /*!
-@brief default JSON class
+@brief default specialization
-
+@sa https://json.nlohmann.me/api/json/
-This type is the default specialization of the @ref basic_json class which
-uses the standard template types.
-
-@since version 1.0.0
 */
 using json = basic_json<>;
 
+/// @brief a minimal map-like container that preserves insertion order
+/// @sa https://json.nlohmann.me/api/ordered_map/
 template<class Key, class T, class IgnoredLess, class Allocator>
 struct ordered_map;
 
-/*!
+/// @brief specialization that maintains the insertion order of object keys
-@brief ordered JSON class
+/// @sa https://json.nlohmann.me/api/ordered_json/
-
-This type preserves the insertion order of object keys.
-
-@since version 3.9.0
-*/
 using ordered_json = basic_json<nlohmann::ordered_map>;
 
 }  // namespace nlohmann

single_include/nlohmann/json.hpp

@@ -3241,6 +3241,8 @@ for serialization.
 template<typename T = void, typename SFINAE = void>
 struct adl_serializer;
 
+/// a class to store JSON values
+/// @sa https://json.nlohmann.me/api/basic_json/
 template<template<typename U, typename V, typename... Args> class ObjectType =
          std::map,
          template<typename U, typename... Args> class ArrayType = std::vector,
@@ -3254,40 +3256,24 @@ template<template<typename U, typename V, typename... Args> class ObjectType =
          class BinaryType = std::vector<std::uint8_t>>
 class basic_json;
 
-/*!
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
-@brief JSON Pointer
+/// @sa https://json.nlohmann.me/api/json_pointer/
-
-A JSON pointer defines a string syntax for identifying a specific value
-within a JSON document. It can be used with functions `at` and
-`operator[]`. Furthermore, JSON pointers are the base for JSON patches.
-
-@sa [RFC 6901](https://tools.ietf.org/html/rfc6901)
-
-@since version 2.0.0
-*/
 template<typename BasicJsonType>
 class json_pointer;
 
 /*!
-@brief default JSON class
+@brief default specialization
-
+@sa https://json.nlohmann.me/api/json/
-This type is the default specialization of the @ref basic_json class which
-uses the standard template types.
-
-@since version 1.0.0
 */
 using json = basic_json<>;
 
+/// @brief a minimal map-like container that preserves insertion order
+/// @sa https://json.nlohmann.me/api/ordered_map/
 template<class Key, class T, class IgnoredLess, class Allocator>
 struct ordered_map;
 
-/*!
+/// @brief specialization that maintains the insertion order of object keys
-@brief ordered JSON class
+/// @sa https://json.nlohmann.me/api/ordered_json/
-
-This type preserves the insertion order of object keys.
-
-@since version 3.9.0
-*/
 using ordered_json = basic_json<nlohmann::ordered_map>;
 
 }  // namespace nlohmann
@@ -4845,6 +4831,7 @@ constexpr const auto& to_json = detail::static_const<detail::to_json_fn>::value;
 namespace nlohmann
 {
 
+/// @sa https://json.nlohmann.me/api/adl_serializer/
 template<typename ValueType, typename>
 struct adl_serializer
 {