more documentation

doc/examples/count.cpp

@@ -0,0 +1,18 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create a JSON object
+    json j_object = {{"one", 1}, {"two", 2}};
+
+    // call find
+    auto count_two = j_object.count("two");
+    auto count_three = j_object.count("three");
+
+    // print values
+    std::cout << std::boolalpha;
+    std::cout << "number of elements with key \"two\": " << count_two << '\n';
+    std::cout << "number of elements with key \"three\": " << count_three << '\n';
+}

doc/examples/count.output

@@ -0,0 +1,2 @@
+number of elements with key "two": 1
+number of elements with key "three": 0

doc/examples/find__key_type.cpp

@@ -0,0 +1,19 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create a JSON object
+    json j_object = {{"one", 1}, {"two", 2}};
+
+    // call find
+    auto it_two = j_object.find("two");
+    auto it_three = j_object.find("three");
+
+    // print values
+    std::cout << std::boolalpha;
+    std::cout << "\"two\" was found: " << (it_two != j_object.end()) << '\n';
+    std::cout << "value at key \"two\": " << *it_two << '\n';
+    std::cout << "\"three\" was found: " << (it_three != j_object.end()) << '\n';
+}

doc/examples/find__key_type.output

@@ -0,0 +1,3 @@
+"two" was found: true
+value at key "two": 2
+"three" was found: false

src/json.hpp

@@ -2701,7 +2701,21 @@ class basic_json
         m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
     }
 
-    /// find an element in an object
+    /*!
+    @brief find an element in a JSON object
+
+    Finds an element in a JSON object with key equivalent to @a key. If the
+    element is not found or the JSON value is not an object, end() is returned.
+
+    @param[in] key key value of the element to search for
+
+    @return Iterator to an element with key equivalent to @a key. If no such
+    element is found, past-the-end (see end()) iterator is returned.
+
+    @complexity Logarithmic in the size of the JSON object.
+
+    @liveexample{The example shows how find is used.,find__key_type}
+    */
     iterator find(typename object_t::key_type key)
     {
         auto result = end();
@@ -2714,7 +2728,10 @@ class basic_json
         return result;
     }
 
-    /// find an element in an object
+    /*!
+    @brief find an element in a JSON object
+    @copydoc find(typename object_t::key_type)
+    */
     const_iterator find(typename object_t::key_type key) const
     {
         auto result = cend();
@@ -2727,7 +2744,22 @@ class basic_json
         return result;
     }
 
-    /// returns the number of occurrences of a key in an object
+    /*!
+    @brief returns the number of occurrences of a key in a JSON object
+
+    Returns the number of elements with key @a key. If ObjectType is the
+    default `std::map` type, the return value will always be `0` (@a key was
+    not found) or `1` (@a key was found).
+
+    @param[in] key key value of the element to count
+
+    @return Number of elements with key @a key. If the JSON value is not an
+    object, the return value will be `0`.
+
+    @complexity Logarithmic in the size of the JSON object.
+
+    @liveexample{The example shows how count is used.,count}
+    */
     size_type count(typename object_t::key_type key) const
     {
         // return 0 for all nonobject types

src/json.hpp.re2c

@@ -2701,7 +2701,21 @@ class basic_json
         m_value.array->erase(m_value.array->begin() + static_cast<difference_type>(idx));
     }
 
-    /// find an element in an object
+    /*!
+    @brief find an element in a JSON object
+
+    Finds an element in a JSON object with key equivalent to @a key. If the
+    element is not found or the JSON value is not an object, end() is returned.
+
+    @param[in] key key value of the element to search for
+
+    @return Iterator to an element with key equivalent to @a key. If no such
+    element is found, past-the-end (see end()) iterator is returned.
+
+    @complexity Logarithmic in the size of the JSON object.
+
+    @liveexample{The example shows how find is used.,find__key_type}
+    */
     iterator find(typename object_t::key_type key)
     {
         auto result = end();
@@ -2714,7 +2728,10 @@ class basic_json
         return result;
     }
 
-    /// find an element in an object
+    /*!
+    @brief find an element in a JSON object
+    @copydoc find(typename object_t::key_type)
+    */
     const_iterator find(typename object_t::key_type key) const
     {
         auto result = cend();
@@ -2727,7 +2744,22 @@ class basic_json
         return result;
     }
 
-    /// returns the number of occurrences of a key in an object
+    /*!
+    @brief returns the number of occurrences of a key in a JSON object
+
+    Returns the number of elements with key @a key. If ObjectType is the
+    default `std::map` type, the return value will always be `0` (@a key was
+    not found) or `1` (@a key was found).
+
+    @param[in] key key value of the element to count
+
+    @return Number of elements with key @a key. If the JSON value is not an
+    object, the return value will be `0`.
+
+    @complexity Logarithmic in the size of the JSON object.
+
+    @liveexample{The example shows how count is used.,count}
+    */
     size_type count(typename object_t::key_type key) const
     {
         // return 0 for all nonobject types
@@ -5600,15 +5632,16 @@ class basic_json
     {
       public:
         /// constructor for strings
-        parser(const string_t& s, parser_callback_t cb = nullptr) : callback(cb), m_lexer(s)
+        parser(const string_t& s, parser_callback_t cb = nullptr)
+            : callback(cb), m_lexer(s)
         {
             // read first token
             get_token();
         }
 
         /// a parser reading from an input stream
-        parser(std::istream& _is, parser_callback_t cb = nullptr) : callback(cb),
-            m_lexer(&_is)
+        parser(std::istream& _is, parser_callback_t cb = nullptr)
+            : callback(cb), m_lexer(&_is)
         {
             // read first token
             get_token();
@@ -5875,7 +5908,7 @@ class basic_json
         }
 
       private:
-        /// levels of recursion
+        /// current level of recursion
         int depth = 0;
         /// callback function
         parser_callback_t callback;