🔥 consolidate documentation

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

@@ -88,7 +88,7 @@ The class satisfies the following concept requirements:
 
 - [**adl_serializer**](../adl_serializer) - the default serializer
 - [**value_t**](value_t.md) - the JSON type enumeration
-- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
+- [**json_pointer**](../json_pointer/index.md) - JSON Pointer implementation
 - [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
 - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
 - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags

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

@@ -5,7 +5,7 @@ json_pointer operator "" _json_pointer(const char* s, std::size_t n);
 ```
 
 This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer`
-to a string literal and returns a [`json_pointer`](../json_pointer.md) object if no parse error occurred.
+to a string literal and returns a [`json_pointer`](../json_pointer/index.md) object if no parse error occurred.
 
 ## Parameters
 
@@ -17,11 +17,11 @@ to a string literal and returns a [`json_pointer`](../json_pointer.md) object if
 
 ## Return value
 
-[`json_pointer`](../json_pointer.md) value parsed from `s`
+[`json_pointer`](../json_pointer/index.md) value parsed from `s`
 
 ## Exceptions
 
-The function can throw anything that [`json_pointer::json_pointer`](../json_pointer.md) would throw.
+The function can throw anything that [`json_pointer::json_pointer`](../json_pointer/index.md) would throw.
 
 ## Complexity
 

doc/mkdocs/docs/api/json_pointer.md

@@ -1,28 +0,0 @@
-# json_pointer
-
-```cpp
-template<typename BasicJsonType>
-class json_pointer;
-```
-
-## Template parameters
-
-`BasicJsonType`
-:   a specialization of [`basic_json`](basic_json/index.md)
-
-## Member functions
-
-- (constructor)
-- **to_string** - return a string representation of the JSON pointer
-- **operator std::string**- return a string representation of the JSON pointer
-- **operator/=** - append to the end of the JSON pointer
-- **operator/** - create JSON Pointer by appending
-- **parent_pointer** - returns the parent of this JSON pointer
-- **pop_back** - remove last reference token
-- **back** - return last reference token
-- **push_back** - append an unescaped token at the end of the pointer
-- **empty** - return whether pointer points to the root document
-
-## Version history
-
-Added in version 2.0.0.

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

@@ -0,0 +1,39 @@
+# json_pointer::back
+
+```cpp
+const std::string& back() const;
+```
+
+Return last reference token.
+
+## Return value
+
+Last reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `back`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__back.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

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

@@ -0,0 +1,39 @@
+# json_pointer::empty
+
+```cpp
+bool empty() const noexcept;
+```
+
+Return whether pointer points to the root document.
+
+## Return value
+
+`#!cpp true` iff the JSON pointer points to the root document.
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the result of `empty` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__empty.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__empty.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

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

@@ -0,0 +1,34 @@
+# json_pointer
+
+```cpp
+template<typename BasicJsonType>
+class json_pointer;
+```
+
+JSON Pointer defines a string syntax for identifying a specific value within a JSON document.
+
+## Template parameters
+
+`BasicJsonType`
+:   a specialization of [`basic_json`](../basic_json/index.md)
+
+## Member functions
+
+- [(constructor)](json_pointer.md)
+- [**to_string**](to_string.md) - return a string representation of the JSON pointer
+- [**operator std::string**](operator_string.md) - return a string representation of the JSON pointer
+- [**operator/=**](operator_slasheq.md) - append to the end of the JSON pointer
+- [**operator/**](operator_slash.md) - create JSON Pointer by appending
+- [**parent_pointer**](parent_pointer.md) - returns the parent of this JSON pointer
+- [**pop_back**](pop_back.md) - remove last reference token
+- [**back**](back.md) - return last reference token
+- [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
+- [**empty**](empty.md) - return whether pointer points to the root document
+
+## See also
+
+[RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901)
+
+## Version history
+
+Added in version 2.0.0.

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

@@ -0,0 +1,40 @@
+# json_pointer::json_pointer
+
+```cpp
+explicit json_pointer(const std::string& s = "");
+```
+
+Create a JSON pointer according to the syntax described in
+[Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
+
+## Parameters
+
+`s` (in)
+:    string representing the JSON pointer; if omitted, the empty string is assumed which references the whole JSON value
+
+## Exceptions
+
+- Throws [parse_error.107](../../home/exceptions.md#jsonexceptionparse_error107) if the given JSON pointer `s` is 
+  nonempty and does not begin with a slash (`/`); see example below.
+- Throws [parse_error.108](../../home/exceptions.md#jsonexceptionparse_error108) if a tilde (`~`) in the given JSON
+  pointer `s` is not followed by `0` (representing `~`) or `1` (representing `/`); see example below.
+
+## Examples
+
+??? example
+
+    The example shows the construction several valid JSON pointers as well as the exceptional behavior.
+     
+    ```cpp
+    --8<-- "examples/json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer.output"
+    ```
+
+## Version history
+
+Added in version 2.0.0.

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

@@ -0,0 +1,64 @@
+# json_pointer::operator/
+
+```cpp
+// (1)
+json_pointer operator/(const json_pointer& lhs, const json_pointer& rhs);
+
+// (2)
+json_pointer operator/(const json_pointer& lhs, std::string token);
+
+// (3)
+json_pointer operator/(const json_pointer& lhs, std::size_t array_idx);
+```
+
+1. create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+2. create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+3. create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+
+## Parameters
+
+`lhs` (in)
+:    JSON pointer
+
+`rhs` (in)
+:    JSON pointer to append
+
+`token` (in)
+:    reference token to append
+
+`array_idx` (in)
+:    array index to append
+
+## Return value
+
+1. a new JSON pointer with `rhs` appended to `lhs`
+2. a new JSON pointer with unescaped `token` appended to `lhs`
+3. a new JSON pointer with `array_idx` appended to `lhs`
+
+## Complexity
+
+1. Linear in the length of `lhs` and `rhs`.
+2. Linear in the length of `lhs`.
+3. Linear in the length of `lhs`.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `operator/`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__operator_add_binary.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__operator_add_binary.output"
+    ```
+
+## Version history
+
+1. Added in version 3.6.0.
+2. Added in version 3.6.0.
+3. Added in version 3.6.0.

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

@@ -0,0 +1,61 @@
+# json_pointer::operator/=
+
+```cpp
+// (1)
+json_pointer& operator/=(const json_pointer& ptr);
+
+// (2)
+json_pointer& operator/=(std::string token);
+
+// (3)
+json_pointer& operator/=(std::size_t array_idx)
+```
+
+1. append another JSON pointer at the end of this JSON pointer
+2. append an unescaped reference token at the end of this JSON pointer
+3. append an array index at the end of this JSON pointer
+
+## Parameters
+
+`ptr` (in)
+:    JSON pointer to append
+
+`token` (in)
+:    reference token to append
+
+`array_idx` (in)
+:    array index to append
+
+## Return value
+
+1. JSON pointer with `ptr` appended
+2. JSON pointer with `token` appended without escaping `token`
+3. JSON pointer with `array_idx` appended
+
+## Complexity
+
+1. Linear in the length of `ptr`.
+2. Amortized constant.
+3. Amortized constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `operator/=`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__operator_add.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__operator_add.output"
+    ```
+
+## Version history
+
+1. Added in version 3.6.0.
+2. Added in version 3.6.0.
+3. Added in version 3.6.0.

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

@@ -0,0 +1,24 @@
+# json_pointer::operator std::string
+
+```cpp
+operator std::string() const
+```
+
+Return a string representation of the JSON pointer.
+
+## Return value
+
+A string representation of the JSON pointer
+
+## Possible implementation
+
+```cpp
+operator std::string() const
+{
+    return to_string();
+}
+```
+
+## Version history
+
+Since version 2.0.0.

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

@@ -0,0 +1,35 @@
+# json_pointer::parent_pointer
+
+```cpp
+json_pointer parent_pointer() const;
+```
+
+Returns the parent of this JSON pointer.
+
+## Return value
+
+Parent of this JSON pointer; in case this JSON pointer is the root, the root itself is returned.
+
+## Complexity
+
+Linear in the length of the JSON pointer.
+
+## Examples
+
+??? example
+
+    The example shows the result of `parent_pointer` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__parent_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__parent_pointer.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

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

@@ -0,0 +1,35 @@
+# json_pointer::pop_back
+
+```cpp
+void pop_back();
+```
+
+Remove last reference token.
+
+## Exceptions
+
+Throws [out_of_range.405](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent.
+
+## Complexity
+
+Constant.
+
+## Examples
+
+??? example
+
+    The example shows the usage of `pop_back`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__pop_back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__pop_back.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

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

@@ -0,0 +1,38 @@
+# json_pointer::push_back
+
+```cpp
+void push_back(const std::string& token);
+
+void push_back(std::string&& token);
+```
+
+Append an unescaped token at the end of the reference pointer.
+
+## Parameters
+
+`token` (in)
+:   token to add
+
+## Complexity
+
+Amortized constant.
+
+## Examples
+
+??? example
+
+    The example shows the result of `push_back` for different JSON Pointers.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__push_back.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__push_back.output"
+    ```
+
+## Version history
+
+Added in version 3.6.0.

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

@@ -0,0 +1,39 @@
+# json_pointer::to_string
+
+```cpp
+std::string to_string() const;
+```
+
+Return a string representation of the JSON pointer.
+
+## Return value
+
+A string representation of the JSON pointer
+
+## Notes
+
+For each JSON pointer `ptr`, it holds:
+
+```cpp
+ptr == json_pointer(ptr.to_string());
+```
+
+## Examples
+
+??? example
+
+    The example shows the result of `to_string`.
+     
+    ```cpp
+    --8<-- "examples/json_pointer__to_string.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/json_pointer__to_string.output"
+    ```
+
+## Version history
+
+Since version 2.0.0.

doc/mkdocs/mkdocs.yml

@@ -194,7 +194,18 @@ nav:
         - 'from_json': api/adl_serializer/from_json.md
         - 'to_json': api/adl_serializer/to_json.md
       - api/json.md
-      - api/json_pointer.md
+      - json_pointer:
+        - 'Overview': api/json_pointer/index.md
+        - '(Constructor)': api/json_pointer/json_pointer.md
+        - 'back': api/json_pointer/back.md
+        - 'empty': api/json_pointer/empty.md
+        - 'operator std::string': api/json_pointer/operator_string.md
+        - 'operator/': api/json_pointer/operator_slash.md
+        - 'operator/=': api/json_pointer/operator_slasheq.md
+        - 'parent_pointer': api/json_pointer/parent_pointer.md
+        - 'pop_back': api/json_pointer/pop_back.md
+        - 'push_back': api/json_pointer/push_back.md
+        - 'to_string': api/json_pointer/to_string.md
       - json_sax:
         - 'Overview': api/json_sax/index.md
         - 'binary': api/json_sax/binary.md

doc/mkdocs/scripts/check_strcuture.py

@@ -41,6 +41,10 @@ def check_structure():
             for lineno, line in enumerate(file_content.readlines()):
                 line = line.strip()
 
+                # lines longer than 160 characters are bad (unless they are tables)
+                if len(line) > 160 and '|' not in line:
+                    print(f'{file}:{lineno+1}: Error: line is too long ({len(line)} vs. 160 chars)!')
+
                 # check if headers are correct
                 if line.startswith('## '):
                     header = line.strip('## ')

include/nlohmann/detail/json_pointer.hpp

@@ -15,6 +15,9 @@
 
 namespace nlohmann
 {
+
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
+/// @sa http://127.0.0.1:8000/api/json_pointer/
 template<typename BasicJsonType>
 class json_pointer
 {
@@ -23,45 +26,14 @@ class json_pointer
     friend class basic_json;
 
   public:
-    /*!
-    @brief create JSON pointer
-
-    Create a JSON pointer according to the syntax described in
-    [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
-
-    @param[in] s  string representing the JSON pointer; if omitted, the empty
-                  string is assumed which references the whole JSON value
-
-    @throw parse_error.107 if the given JSON pointer @a s is nonempty and does
-                           not begin with a slash (`/`); see example below
-
-    @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s is
-    not followed by `0` (representing `~`) or `1` (representing `/`); see
-    example below
-
-    @liveexample{The example shows the construction several valid JSON pointers
-    as well as the exceptional behavior.,json_pointer}
-
-    @since version 2.0.0
-    */
+    /// @brief create JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/json_pointer/
     explicit json_pointer(const std::string& s = "")
         : reference_tokens(split(s))
     {}
 
-    /*!
-    @brief return a string representation of the JSON pointer
-
-    @invariant For each JSON pointer `ptr`, it holds:
-    @code {.cpp}
-    ptr == json_pointer(ptr.to_string());
-    @endcode
-
-    @return a string representation of the JSON pointer
-
-    @liveexample{The example shows the result of `to_string`.,json_pointer__to_string}
-
-    @since version 2.0.0
-    */
+    /// @brief return a string representation of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/to_string/
     std::string to_string() const
     {
         return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
@@ -72,28 +44,15 @@ class json_pointer
         });
     }
 
-    /// @copydoc to_string()
+    /// @brief return a string representation of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_string/
     operator std::string() const
     {
         return to_string();
     }
 
-    /*!
-    @brief append another JSON pointer at the end of this JSON pointer
-
-    @param[in] ptr  JSON pointer to append
-    @return JSON pointer with @a ptr appended
-
-    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
-    @complexity Linear in the length of @a ptr.
-
-    @sa see @ref operator/=(std::string) to append a reference token
-    @sa see @ref operator/=(std::size_t) to append an array index
-    @sa see @ref operator/(const json_pointer&, const json_pointer&) for a binary operator
-
-    @since version 3.6.0
-    */
+    /// @brief append another JSON pointer at the end of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/
     json_pointer& operator/=(const json_pointer& ptr)
     {
         reference_tokens.insert(reference_tokens.end(),
@@ -102,123 +61,45 @@ class json_pointer
         return *this;
     }
 
-    /*!
-    @brief append an unescaped reference token at the end of this JSON pointer
-
-    @param[in] token  reference token to append
-    @return JSON pointer with @a token appended without escaping @a token
-
-    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
-    @complexity Amortized constant.
-
-    @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-    @sa see @ref operator/=(std::size_t) to append an array index
-    @sa see @ref operator/(const json_pointer&, std::size_t) for a binary operator
-
-    @since version 3.6.0
-    */
+    /// @brief append an unescaped reference token at the end of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/
     json_pointer& operator/=(std::string token)
     {
         push_back(std::move(token));
         return *this;
     }
 
-    /*!
-    @brief append an array index at the end of this JSON pointer
-
-    @param[in] array_idx  array index to append
-    @return JSON pointer with @a array_idx appended
-
-    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
-    @complexity Amortized constant.
-
-    @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-    @sa see @ref operator/=(std::string) to append a reference token
-    @sa see @ref operator/(const json_pointer&, std::string) for a binary operator
-
-    @since version 3.6.0
-    */
+    /// @brief append an array index at the end of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/
     json_pointer& operator/=(std::size_t array_idx)
     {
         return *this /= std::to_string(array_idx);
     }
 
-    /*!
-    @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
-
-    @param[in] lhs  JSON pointer
-    @param[in] rhs  JSON pointer
-    @return a new JSON pointer with @a rhs appended to @a lhs
-
-    @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
-    @complexity Linear in the length of @a lhs and @a rhs.
-
-    @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-
-    @since version 3.6.0
-    */
+    /// @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/
     friend json_pointer operator/(const json_pointer& lhs,
                                   const json_pointer& rhs)
     {
         return json_pointer(lhs) /= rhs;
     }
 
-    /*!
-    @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
-
-    @param[in] ptr  JSON pointer
-    @param[in] token  reference token
-    @return a new JSON pointer with unescaped @a token appended to @a ptr
-
-    @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
-    @complexity Linear in the length of @a ptr.
-
-    @sa see @ref operator/=(std::string) to append a reference token
-
-    @since version 3.6.0
-    */
-    friend json_pointer operator/(const json_pointer& ptr, std::string token) // NOLINT(performance-unnecessary-value-param)
+    /// @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/
+    friend json_pointer operator/(const json_pointer& lhs, std::string token) // NOLINT(performance-unnecessary-value-param)
     {
-        return json_pointer(ptr) /= std::move(token);
+        return json_pointer(lhs) /= std::move(token);
     }
 
-    /*!
-    @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
-
-    @param[in] ptr  JSON pointer
-    @param[in] array_idx  array index
-    @return a new JSON pointer with @a array_idx appended to @a ptr
-
-    @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
-    @complexity Linear in the length of @a ptr.
-
-    @sa see @ref operator/=(std::size_t) to append an array index
-
-    @since version 3.6.0
-    */
-    friend json_pointer operator/(const json_pointer& ptr, std::size_t array_idx)
+    /// @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/
+    friend json_pointer operator/(const json_pointer& lhs, std::size_t array_idx)
     {
-        return json_pointer(ptr) /= array_idx;
+        return json_pointer(lhs) /= array_idx;
     }
 
-    /*!
-    @brief returns the parent of this JSON pointer
-
-    @return parent of this JSON pointer; in case this JSON pointer is the root,
-            the root itself is returned
-
-    @complexity Linear in the length of the JSON pointer.
-
-    @liveexample{The example shows the result of `parent_pointer` for different
-    JSON Pointers.,json_pointer__parent_pointer}
-
-    @since version 3.6.0
-    */
+    /// @brief returns the parent of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/parent_pointer/
     json_pointer parent_pointer() const
     {
         if (empty())
@@ -231,19 +112,8 @@ class json_pointer
         return res;
     }
 
-    /*!
-    @brief remove last reference token
-
-    @pre not `empty()`
-
-    @liveexample{The example shows the usage of `pop_back`.,json_pointer__pop_back}
-
-    @complexity Constant.
-
-    @throw out_of_range.405 if JSON pointer has no parent
-
-    @since version 3.6.0
-    */
+    /// @brief remove last reference token
+    /// @sa http://127.0.0.1:8000/api/json_pointer/pop_back/
     void pop_back()
     {
         if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -254,20 +124,8 @@ class json_pointer
         reference_tokens.pop_back();
     }
 
-    /*!
-    @brief return last reference token
-
-    @pre not `empty()`
-    @return last reference token
-
-    @liveexample{The example shows the usage of `back`.,json_pointer__back}
-
-    @complexity Constant.
-
-    @throw out_of_range.405 if JSON pointer has no parent
-
-    @since version 3.6.0
-    */
+    /// @brief return last reference token
+    /// @sa http://127.0.0.1:8000/api/json_pointer/back/
     const std::string& back() const
     {
         if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -278,43 +136,22 @@ class json_pointer
         return reference_tokens.back();
     }
 
-    /*!
-    @brief append an unescaped token at the end of the reference pointer
-
-    @param[in] token  token to add
-
-    @complexity Amortized constant.
-
-    @liveexample{The example shows the result of `push_back` for different
-    JSON Pointers.,json_pointer__push_back}
-
-    @since version 3.6.0
-    */
+    /// @brief append an unescaped token at the end of the reference pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/
     void push_back(const std::string& token)
     {
         reference_tokens.push_back(token);
     }
 
-    /// @copydoc push_back(const std::string&)
+    /// @brief append an unescaped token at the end of the reference pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/
     void push_back(std::string&& token)
     {
         reference_tokens.push_back(std::move(token));
     }
 
-    /*!
-    @brief return whether pointer points to the root document
-
-    @return true iff the JSON pointer points to the root document
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
-    @liveexample{The example shows the result of `empty` for different JSON
-    Pointers.,json_pointer__empty}
-
-    @since version 3.6.0
-    */
+    /// @brief return whether pointer points to the root document
+    /// @sa http://127.0.0.1:8000/api/json_pointer/empty/
     bool empty() const noexcept
     {
         return reference_tokens.empty();

single_include/nlohmann/json.hpp

@@ -12369,6 +12369,9 @@ class json_reverse_iterator : public std::reverse_iterator<Base>
 
 namespace nlohmann
 {
+
+/// @brief JSON Pointer defines a string syntax for identifying a specific value within a JSON document
+/// @sa http://127.0.0.1:8000/api/json_pointer/
 template<typename BasicJsonType>
 class json_pointer
 {
@@ -12377,45 +12380,14 @@ class json_pointer
     friend class basic_json;
 
   public:
-    /*!
-    @brief create JSON pointer
-
-    Create a JSON pointer according to the syntax described in
-    [Section 3 of RFC6901](https://tools.ietf.org/html/rfc6901#section-3).
-
-    @param[in] s  string representing the JSON pointer; if omitted, the empty
-                  string is assumed which references the whole JSON value
-
-    @throw parse_error.107 if the given JSON pointer @a s is nonempty and does
-                           not begin with a slash (`/`); see example below
-
-    @throw parse_error.108 if a tilde (`~`) in the given JSON pointer @a s is
-    not followed by `0` (representing `~`) or `1` (representing `/`); see
-    example below
-
-    @liveexample{The example shows the construction several valid JSON pointers
-    as well as the exceptional behavior.,json_pointer}
-
-    @since version 2.0.0
-    */
+    /// @brief create JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/json_pointer/
     explicit json_pointer(const std::string& s = "")
         : reference_tokens(split(s))
     {}
 
-    /*!
-    @brief return a string representation of the JSON pointer
-
-    @invariant For each JSON pointer `ptr`, it holds:
-    @code {.cpp}
-    ptr == json_pointer(ptr.to_string());
-    @endcode
-
-    @return a string representation of the JSON pointer
-
-    @liveexample{The example shows the result of `to_string`.,json_pointer__to_string}
-
-    @since version 2.0.0
-    */
+    /// @brief return a string representation of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/to_string/
     std::string to_string() const
     {
         return std::accumulate(reference_tokens.begin(), reference_tokens.end(),
@@ -12426,28 +12398,15 @@ class json_pointer
         });
     }
 
-    /// @copydoc to_string()
+    /// @brief return a string representation of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_string/
     operator std::string() const
     {
         return to_string();
     }
 
-    /*!
-    @brief append another JSON pointer at the end of this JSON pointer
-
-    @param[in] ptr  JSON pointer to append
-    @return JSON pointer with @a ptr appended
-
-    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
-    @complexity Linear in the length of @a ptr.
-
-    @sa see @ref operator/=(std::string) to append a reference token
-    @sa see @ref operator/=(std::size_t) to append an array index
-    @sa see @ref operator/(const json_pointer&, const json_pointer&) for a binary operator
-
-    @since version 3.6.0
-    */
+    /// @brief append another JSON pointer at the end of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/
     json_pointer& operator/=(const json_pointer& ptr)
     {
         reference_tokens.insert(reference_tokens.end(),
@@ -12456,123 +12415,45 @@ class json_pointer
         return *this;
     }
 
-    /*!
-    @brief append an unescaped reference token at the end of this JSON pointer
-
-    @param[in] token  reference token to append
-    @return JSON pointer with @a token appended without escaping @a token
-
-    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
-    @complexity Amortized constant.
-
-    @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-    @sa see @ref operator/=(std::size_t) to append an array index
-    @sa see @ref operator/(const json_pointer&, std::size_t) for a binary operator
-
-    @since version 3.6.0
-    */
+    /// @brief append an unescaped reference token at the end of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/
     json_pointer& operator/=(std::string token)
     {
         push_back(std::move(token));
         return *this;
     }
 
-    /*!
-    @brief append an array index at the end of this JSON pointer
-
-    @param[in] array_idx  array index to append
-    @return JSON pointer with @a array_idx appended
-
-    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
-
-    @complexity Amortized constant.
-
-    @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-    @sa see @ref operator/=(std::string) to append a reference token
-    @sa see @ref operator/(const json_pointer&, std::string) for a binary operator
-
-    @since version 3.6.0
-    */
+    /// @brief append an array index at the end of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slasheq/
     json_pointer& operator/=(std::size_t array_idx)
     {
         return *this /= std::to_string(array_idx);
     }
 
-    /*!
-    @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
-
-    @param[in] lhs  JSON pointer
-    @param[in] rhs  JSON pointer
-    @return a new JSON pointer with @a rhs appended to @a lhs
-
-    @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
-    @complexity Linear in the length of @a lhs and @a rhs.
-
-    @sa see @ref operator/=(const json_pointer&) to append a JSON pointer
-
-    @since version 3.6.0
-    */
+    /// @brief create a new JSON pointer by appending the right JSON pointer at the end of the left JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/
     friend json_pointer operator/(const json_pointer& lhs,
                                   const json_pointer& rhs)
     {
         return json_pointer(lhs) /= rhs;
     }
 
-    /*!
-    @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
-
-    @param[in] ptr  JSON pointer
-    @param[in] token  reference token
-    @return a new JSON pointer with unescaped @a token appended to @a ptr
-
-    @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
-    @complexity Linear in the length of @a ptr.
-
-    @sa see @ref operator/=(std::string) to append a reference token
-
-    @since version 3.6.0
-    */
-    friend json_pointer operator/(const json_pointer& ptr, std::string token) // NOLINT(performance-unnecessary-value-param)
+    /// @brief create a new JSON pointer by appending the unescaped token at the end of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/
+    friend json_pointer operator/(const json_pointer& lhs, std::string token) // NOLINT(performance-unnecessary-value-param)
     {
-        return json_pointer(ptr) /= std::move(token);
+        return json_pointer(lhs) /= std::move(token);
     }
 
-    /*!
-    @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
-
-    @param[in] ptr  JSON pointer
-    @param[in] array_idx  array index
-    @return a new JSON pointer with @a array_idx appended to @a ptr
-
-    @liveexample{The example shows the usage of `operator/`.,json_pointer__operator_add_binary}
-
-    @complexity Linear in the length of @a ptr.
-
-    @sa see @ref operator/=(std::size_t) to append an array index
-
-    @since version 3.6.0
-    */
-    friend json_pointer operator/(const json_pointer& ptr, std::size_t array_idx)
+    /// @brief create a new JSON pointer by appending the array-index-token at the end of the JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/operator_slash/
+    friend json_pointer operator/(const json_pointer& lhs, std::size_t array_idx)
     {
-        return json_pointer(ptr) /= array_idx;
+        return json_pointer(lhs) /= array_idx;
     }
 
-    /*!
-    @brief returns the parent of this JSON pointer
-
-    @return parent of this JSON pointer; in case this JSON pointer is the root,
-            the root itself is returned
-
-    @complexity Linear in the length of the JSON pointer.
-
-    @liveexample{The example shows the result of `parent_pointer` for different
-    JSON Pointers.,json_pointer__parent_pointer}
-
-    @since version 3.6.0
-    */
+    /// @brief returns the parent of this JSON pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/parent_pointer/
     json_pointer parent_pointer() const
     {
         if (empty())
@@ -12585,19 +12466,8 @@ class json_pointer
         return res;
     }
 
-    /*!
-    @brief remove last reference token
-
-    @pre not `empty()`
-
-    @liveexample{The example shows the usage of `pop_back`.,json_pointer__pop_back}
-
-    @complexity Constant.
-
-    @throw out_of_range.405 if JSON pointer has no parent
-
-    @since version 3.6.0
-    */
+    /// @brief remove last reference token
+    /// @sa http://127.0.0.1:8000/api/json_pointer/pop_back/
     void pop_back()
     {
         if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -12608,20 +12478,8 @@ class json_pointer
         reference_tokens.pop_back();
     }
 
-    /*!
-    @brief return last reference token
-
-    @pre not `empty()`
-    @return last reference token
-
-    @liveexample{The example shows the usage of `back`.,json_pointer__back}
-
-    @complexity Constant.
-
-    @throw out_of_range.405 if JSON pointer has no parent
-
-    @since version 3.6.0
-    */
+    /// @brief return last reference token
+    /// @sa http://127.0.0.1:8000/api/json_pointer/back/
     const std::string& back() const
     {
         if (JSON_HEDLEY_UNLIKELY(empty()))
@@ -12632,43 +12490,22 @@ class json_pointer
         return reference_tokens.back();
     }
 
-    /*!
-    @brief append an unescaped token at the end of the reference pointer
-
-    @param[in] token  token to add
-
-    @complexity Amortized constant.
-
-    @liveexample{The example shows the result of `push_back` for different
-    JSON Pointers.,json_pointer__push_back}
-
-    @since version 3.6.0
-    */
+    /// @brief append an unescaped token at the end of the reference pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/
     void push_back(const std::string& token)
     {
         reference_tokens.push_back(token);
     }
 
-    /// @copydoc push_back(const std::string&)
+    /// @brief append an unescaped token at the end of the reference pointer
+    /// @sa http://127.0.0.1:8000/api/json_pointer/push_back/
     void push_back(std::string&& token)
     {
         reference_tokens.push_back(std::move(token));
     }
 
-    /*!
-    @brief return whether pointer points to the root document
-
-    @return true iff the JSON pointer points to the root document
-
-    @complexity Constant.
-
-    @exceptionsafety No-throw guarantee: this function never throws exceptions.
-
-    @liveexample{The example shows the result of `empty` for different JSON
-    Pointers.,json_pointer__empty}
-
-    @since version 3.6.0
-    */
+    /// @brief return whether pointer points to the root document
+    /// @sa http://127.0.0.1:8000/api/json_pointer/empty/
     bool empty() const noexcept
     {
         return reference_tokens.empty();