📝 added documentation

doc/examples/json_pointer__operator_add.cpp

@@ -0,0 +1,23 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON pointer
+    json::json_pointer ptr("/foo");
+    std::cout << ptr << '\n';
+
+    // apppend a JSON Pointer
+    ptr /= json::json_pointer("/bar/baz");
+    std::cout << ptr << '\n';
+
+    // append a string
+    ptr /= "fob";
+    std::cout << ptr << '\n';
+
+    // append an array index
+    ptr /= 42;
+    std::cout << ptr << std::endl;
+}

doc/examples/json_pointer__operator_add.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/9GFummh9iBAkOFiL"><b>online</b></a>

doc/examples/json_pointer__operator_add.output

@@ -0,0 +1,4 @@
+"/foo"
+"/foo/bar/baz"
+"/foo/bar/baz/fob"
+"/foo/bar/baz/fob/42"

doc/examples/json_pointer__operator_add_binary.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON pointer
+    json::json_pointer ptr("/foo");
+
+    // apppend a JSON Pointer
+    std::cout << ptr / json::json_pointer("/bar/baz") << '\n';
+
+    // append a string
+    std::cout << ptr / "fob" << '\n';
+
+    // append an array index
+    std::cout << ptr / 42 << std::endl;
+}

doc/examples/json_pointer__operator_add_binary.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/mxBfUH9gOY9AiOOk"><b>online</b></a>

doc/examples/json_pointer__operator_add_binary.output

@@ -0,0 +1,3 @@
+"/foo/bar/baz"
+"/foo/fob"
+"/foo/42"

include/nlohmann/detail/json_pointer.hpp

@@ -56,8 +56,7 @@ class json_pointer
 
     @return a string representation of the JSON pointer
 
-    @liveexample{The example shows the result of `to_string`.,
+    @liveexample{The example shows the result of `to_string`.,json_pointer__to_string}
-    json_pointer__to_string}
 
     @since version 2.0.0
     */
@@ -79,6 +78,19 @@ class json_pointer
 
     /*!
     @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 @ref operator/=(std::string) to append a reference token
+    @sa @ref operator/=(std::size_t) to append an array index
+    @sa @ref operator/(const json_pointer&, const json_pointer&) for a binary operator
+
+    @since version 3.6.0
     */
     json_pointer& operator/=(const json_pointer& ptr)
     {
@@ -88,14 +100,44 @@ class json_pointer
         return *this;
     }
 
-    /// @copydoc push_back(std::string&&)
+    /*!
+    @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 @ref operator/=(const json_pointer&) to append a JSON pointer
+    @sa @ref operator/=(std::size_t) to append an array index
+    @sa @ref operator/(const json_pointer&, std::size_t) for a binary operator
+
+    @since version 3.6.0
+    */
     json_pointer& operator/=(std::string token)
     {
         push_back(std::move(token));
         return *this;
     }
 
-    /// @copydoc operator/=(std::string)
+    /*!
+    @brief append an array index at the end of this JSON pointer
+
+    @param[in] array_index  array index ot append
+    @return JSON pointer with @a array_index appended
+
+    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
+
+    @complexity Amortized constant.
+
+    @sa @ref operator/=(const json_pointer&) to append a JSON pointer
+    @sa @ref operator/=(std::string) to append a reference token
+    @sa @ref operator/(const json_pointer&, std::string) for a binary operator
+
+    @since version 3.6.0
+    */
     json_pointer& operator/=(std::size_t array_index)
     {
         return *this /= std::to_string(array_index);
@@ -103,15 +145,39 @@ class json_pointer
 
     /*!
     @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 @ref operator/=(const json_pointer&) to append a JSON pointer
+
+    @since version 3.6.0
     */
-    friend json_pointer operator/(const json_pointer& left_ptr,
+    friend json_pointer operator/(const json_pointer& lhs,
-                                  const json_pointer& right_ptr)
+                                  const json_pointer& rhs)
     {
-        return json_pointer(left_ptr) /= right_ptr;
+        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 @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)
     {
@@ -120,10 +186,22 @@ class json_pointer
 
     /*!
     @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_index  array index
+    @return a new JSON pointer with @a array_index 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 @ref operator/=(std::size_t) to append an array index
+
+    @since version 3.6.0
     */
-    friend json_pointer operator/(const json_pointer& lhs, std::size_t array_index)
+    friend json_pointer operator/(const json_pointer& ptr, std::size_t array_index)
     {
-        return json_pointer(lhs) /= array_index;
+        return json_pointer(ptr) /= array_index;
     }
 
     /*!
@@ -790,12 +868,34 @@ class json_pointer
         return result;
     }
 
+    /*!
+    @brief compares two JSON pointers for equality
+
+    @param[in] lhs  JSON pointer to compare
+    @param[in] rhs  JSON pointer to compare
+    @return whether @a lhs is equal to @a rhs
+
+    @complexity Linear in the length of the JSON pointer
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+    */
     friend bool operator==(json_pointer const& lhs,
                            json_pointer const& rhs) noexcept
     {
         return lhs.reference_tokens == rhs.reference_tokens;
     }
 
+    /*!
+    @brief compares two JSON pointers for inequality
+
+    @param[in] lhs  JSON pointer to compare
+    @param[in] rhs  JSON pointer to compare
+    @return whether @a lhs is not equal @a rhs
+
+    @complexity Linear in the length of the JSON pointer
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+    */
     friend bool operator!=(json_pointer const& lhs,
                            json_pointer const& rhs) noexcept
     {

single_include/nlohmann/json.hpp

@@ -8466,8 +8466,7 @@ class json_pointer
 
     @return a string representation of the JSON pointer
 
-    @liveexample{The example shows the result of `to_string`.,
+    @liveexample{The example shows the result of `to_string`.,json_pointer__to_string}
-    json_pointer__to_string}
 
     @since version 2.0.0
     */
@@ -8489,6 +8488,19 @@ class json_pointer
 
     /*!
     @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 @ref operator/=(std::string) to append a reference token
+    @sa @ref operator/=(std::size_t) to append an array index
+    @sa @ref operator/(const json_pointer&, const json_pointer&) for a binary operator
+
+    @since version 3.6.0
     */
     json_pointer& operator/=(const json_pointer& ptr)
     {
@@ -8498,14 +8510,44 @@ class json_pointer
         return *this;
     }
 
-    /// @copydoc push_back(std::string&&)
+    /*!
+    @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 @ref operator/=(const json_pointer&) to append a JSON pointer
+    @sa @ref operator/=(std::size_t) to append an array index
+    @sa @ref operator/(const json_pointer&, std::size_t) for a binary operator
+
+    @since version 3.6.0
+    */
     json_pointer& operator/=(std::string token)
     {
         push_back(std::move(token));
         return *this;
     }
 
-    /// @copydoc operator/=(std::string)
+    /*!
+    @brief append an array index at the end of this JSON pointer
+
+    @param[in] array_index  array index ot append
+    @return JSON pointer with @a array_index appended
+
+    @liveexample{The example shows the usage of `operator/=`.,json_pointer__operator_add}
+
+    @complexity Amortized constant.
+
+    @sa @ref operator/=(const json_pointer&) to append a JSON pointer
+    @sa @ref operator/=(std::string) to append a reference token
+    @sa @ref operator/(const json_pointer&, std::string) for a binary operator
+
+    @since version 3.6.0
+    */
     json_pointer& operator/=(std::size_t array_index)
     {
         return *this /= std::to_string(array_index);
@@ -8513,15 +8555,39 @@ class json_pointer
 
     /*!
     @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 @ref operator/=(const json_pointer&) to append a JSON pointer
+
+    @since version 3.6.0
     */
-    friend json_pointer operator/(const json_pointer& left_ptr,
+    friend json_pointer operator/(const json_pointer& lhs,
-                                  const json_pointer& right_ptr)
+                                  const json_pointer& rhs)
     {
-        return json_pointer(left_ptr) /= right_ptr;
+        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 @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)
     {
@@ -8530,10 +8596,22 @@ class json_pointer
 
     /*!
     @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_index  array index
+    @return a new JSON pointer with @a array_index 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 @ref operator/=(std::size_t) to append an array index
+
+    @since version 3.6.0
     */
-    friend json_pointer operator/(const json_pointer& lhs, std::size_t array_index)
+    friend json_pointer operator/(const json_pointer& ptr, std::size_t array_index)
     {
-        return json_pointer(lhs) /= array_index;
+        return json_pointer(ptr) /= array_index;
     }
 
     /*!
@@ -9200,12 +9278,34 @@ class json_pointer
         return result;
     }
 
+    /*!
+    @brief compares two JSON pointers for equality
+
+    @param[in] lhs  JSON pointer to compare
+    @param[in] rhs  JSON pointer to compare
+    @return whether @a lhs is equal to @a rhs
+
+    @complexity Linear in the length of the JSON pointer
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+    */
     friend bool operator==(json_pointer const& lhs,
                            json_pointer const& rhs) noexcept
     {
         return lhs.reference_tokens == rhs.reference_tokens;
     }
 
+    /*!
+    @brief compares two JSON pointers for inequality
+
+    @param[in] lhs  JSON pointer to compare
+    @param[in] rhs  JSON pointer to compare
+    @return whether @a lhs is not equal @a rhs
+
+    @complexity Linear in the length of the JSON pointer
+
+    @exceptionsafety No-throw guarantee: this function never throws exceptions.
+    */
     friend bool operator!=(json_pointer const& lhs,
                            json_pointer const& rhs) noexcept
     {