more documentation

Makefile

@@ -50,6 +50,7 @@ update_doxygen_online:
 	rm -fr html
 	mv /tmp/github-html html
 	-cd html ; git rm $(shell git ls-files --deleted)
+	git add html
 	git commit -m "Doxygen update"
 	git checkout master
 

docs/examples/basic_json__copyassignment.cpp

+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json a = 23;
+    json b = 42;
+
+    // copy-assign a to b
+    b = a;
+
+    // serialize the JSON arrays
+    std::cout << a << '\n';
+    std::cout << b << '\n';
+}

docs/examples/basic_json__copyassignment.output

+23
+23

docs/examples/basic_json__moveconstructor.cpp

+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create a JSON value
+    json a = 23;
+
+    // move contents of a to b
+    json b(std::move(a));
+
+    // serialize the JSON arrays
+    std::cout << a << '\n';
+    std::cout << b << '\n';
+}

docs/examples/basic_json__moveconstructor.output

+null
+23

docs/examples/dump.cpp

+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json j_object = {{"one", 1}, {"two", 2}};
+    json j_array = {1, 2, 4, 8, 16};
+
+    // call dump()
+    std::cout << j_object.dump() << "\n\n";
+    std::cout << j_object.dump(-1) << "\n\n";
+    std::cout << j_object.dump(0) << "\n\n";
+    std::cout << j_object.dump(4) << "\n\n";
+    std::cout << j_array.dump() << "\n\n";
+    std::cout << j_array.dump(-1) << "\n\n";
+    std::cout << j_array.dump(0) << "\n\n";
+    std::cout << j_array.dump(4) << "\n\n";
+}

docs/examples/dump.output

+{"one":1,"two":2}
+
+{"one":1,"two":2}
+
+{
+"one": 1,
+"two": 2
+}
+
+{
+    "one": 1,
+    "two": 2
+}
+
+[1,2,4,8,16]
+
+[1,2,4,8,16]
+
+[
+1,
+2,
+4,
+8,
+16
+]
+
+[
+    1,
+    2,
+    4,
+    8,
+    16
+]
+

src/json.hpp

@@ -85,16 +85,16 @@ struct has_mapped_type
                            (@c std::allocator by default)
 
 @requirement This class satisfies the Container requirements (see http://en.cppreference.com/w/cpp/concept/Container):
-- @ref basic_json()
-- @ref basic_json(const basic_json&)
-- @ref reference& operator=(basic_json)
-- @ref ~basic_json()
-- @ref iterator begin(), @ref const_iterator begin(), @ref const_iterator cbegin()
-- @ref iterator end(), @ref const_iterator end(), @ref const_iterator cend()
-- @ref bool operator==(const_reference, const_reference), @ref bool operator!=(const_reference, const_reference)
-- @ref void swap(reference other)
-- @ref size_type size(), @ref size_type max_size()
-- @ref bool empty()
+- basic_json()
+- basic_json(const basic_json&)
+- reference& operator=(basic_json)
+- ~basic_json()
+- iterator begin(), const_iterator begin(), const_iterator cbegin()
+- iterator end(), const_iterator end(), const_iterator cend()
+- bool operator==(const_reference, const_reference), bool operator!=(const_reference, const_reference)
+- void swap(reference other)
+- size_type size(), size_type max_size()
+- bool empty()
 
 @note ObjectType trick from http://stackoverflow.com/a/9860911
 
@@ -686,7 +686,8 @@ class basic_json
     3. In all other cases, the initializer list could not be interpreted as
     JSON object type, so interpreting it as JSON array type is safe.
 
-    With the rules described above, the following JSON values cannot be expressed by an initializer list:
+    With the rules described above, the following JSON values cannot be
+    expressed by an initializer list:
 
     - the empty array (`[]`): use @ref array(list_init_t) with an empty
       initializer list in this case
@@ -1037,7 +1038,22 @@ class basic_json
         }
     }
 
-    /// move constructor
+    /*!
+    @brief move constructor
+
+    Move constructor. Constructs a JSON value with the contents of the given
+    value @a other using move semantics. It "steals" the resources from @a
+    other and leaves it as JSON null value.
+
+    @param other  value to move to this object
+
+    @post @a other is a JSON null value
+
+    @complexity Constant.
+
+    @liveexample{The code below shows the move constructor explicitly called
+    via std::move.,basic_json__moveconstructor}
+    */
     basic_json(basic_json&& other) noexcept
         : m_type(std::move(other.m_type)),
           m_value(std::move(other.m_value))
@@ -1050,14 +1066,22 @@ class basic_json
     /*!
     @brief copy assignment
 
-    The copy assignment operator is expressed in terms of the copy constructor,
-    destructor, and the swap() member function.
+    Copy assignment operator. Copies a JSON value via the "copy and swap"
+    strategy: It is expressed in terms of the copy constructor, destructor, and
+    the swap() member function.
+
+    @param other  value to copy from
 
     @complexity Linear.
 
     @requirement This function satisfies the Container requirements:
     - The complexity is linear.
 
+    @liveexample{The code below shows and example for the copy assignment. It
+    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    copy of `a` (which is the null value after the swap) is
+    destroyed.,basic_json__copyassignment}
+
     @ingroup container
     */
     reference& operator=(basic_json other) noexcept (
@@ -1076,7 +1100,7 @@ class basic_json
     /*!
     @brief destructor
 
-    Destroys the JSON value and frees all memory.
+    Destroys the JSON value and frees all allocated memory.
 
     @complexity Linear.
 
@@ -1137,7 +1161,7 @@ class basic_json
     /*!
     @brief serialization
 
-    Serialization function for JSON objects. The function tries to mimick
+    Serialization function for JSON values. The function tries to mimick
     Python's @p json.dumps() function, and currently supports its @p indent
     parameter.
 
@@ -1146,6 +1170,13 @@ class basic_json
     will only insert newlines. -1 (the default) selects the most compact
     representation
 
+    @return string containing the serialization of the JSON value
+
+    @complexity Linear.
+
+    @liveexample{The following example shows the effect of different @a indent
+    parameters to the result of the serializaion.,dump}
+
     @see https://docs.python.org/2/library/json.html#json.dump
     */
     string_t dump(const int indent = -1) const noexcept

src/json.hpp.re2c

@@ -85,16 +85,16 @@ struct has_mapped_type
                            (@c std::allocator by default)
 
 @requirement This class satisfies the Container requirements (see http://en.cppreference.com/w/cpp/concept/Container):
-- @ref basic_json()
-- @ref basic_json(const basic_json&)
-- @ref reference& operator=(basic_json)
-- @ref ~basic_json()
-- @ref iterator begin(), @ref const_iterator begin(), @ref const_iterator cbegin()
-- @ref iterator end(), @ref const_iterator end(), @ref const_iterator cend()
-- @ref bool operator==(const_reference, const_reference), @ref bool operator!=(const_reference, const_reference)
-- @ref void swap(reference other)
-- @ref size_type size(), @ref size_type max_size()
-- @ref bool empty()
+- basic_json()
+- basic_json(const basic_json&)
+- reference& operator=(basic_json)
+- ~basic_json()
+- iterator begin(), const_iterator begin(), const_iterator cbegin()
+- iterator end(), const_iterator end(), const_iterator cend()
+- bool operator==(const_reference, const_reference), bool operator!=(const_reference, const_reference)
+- void swap(reference other)
+- size_type size(), size_type max_size()
+- bool empty()
 
 @note ObjectType trick from http://stackoverflow.com/a/9860911
 
@@ -686,7 +686,8 @@ class basic_json
     3. In all other cases, the initializer list could not be interpreted as
     JSON object type, so interpreting it as JSON array type is safe.
 
-    With the rules described above, the following JSON values cannot be expressed by an initializer list:
+    With the rules described above, the following JSON values cannot be
+    expressed by an initializer list:
 
     - the empty array (`[]`): use @ref array(list_init_t) with an empty
       initializer list in this case
@@ -1037,7 +1038,22 @@ class basic_json
         }
     }
 
-    /// move constructor
+    /*!
+    @brief move constructor
+
+    Move constructor. Constructs a JSON value with the contents of the given
+    value @a other using move semantics. It "steals" the resources from @a
+    other and leaves it as JSON null value.
+
+    @param other  value to move to this object
+
+    @post @a other is a JSON null value
+
+    @complexity Constant.
+
+    @liveexample{The code below shows the move constructor explicitly called
+    via std::move.,basic_json__moveconstructor}
+    */
     basic_json(basic_json&& other) noexcept
         : m_type(std::move(other.m_type)),
           m_value(std::move(other.m_value))
@@ -1050,14 +1066,22 @@ class basic_json
     /*!
     @brief copy assignment
 
-    The copy assignment operator is expressed in terms of the copy constructor,
-    destructor, and the swap() member function.
+    Copy assignment operator. Copies a JSON value via the "copy and swap"
+    strategy: It is expressed in terms of the copy constructor, destructor, and
+    the swap() member function.
+
+    @param other  value to copy from
 
     @complexity Linear.
 
     @requirement This function satisfies the Container requirements:
     - The complexity is linear.
 
+    @liveexample{The code below shows and example for the copy assignment. It
+    creates a copy of value `a` which is then swapped with `b`. Finally\, the
+    copy of `a` (which is the null value after the swap) is
+    destroyed.,basic_json__copyassignment}
+
     @ingroup container
     */
     reference& operator=(basic_json other) noexcept (
@@ -1076,7 +1100,7 @@ class basic_json
     /*!
     @brief destructor
 
-    Destroys the JSON value and frees all memory.
+    Destroys the JSON value and frees all allocated memory.
 
     @complexity Linear.
 
@@ -1137,7 +1161,7 @@ class basic_json
     /*!
     @brief serialization
 
-    Serialization function for JSON objects. The function tries to mimick
+    Serialization function for JSON values. The function tries to mimick
     Python's @p json.dumps() function, and currently supports its @p indent
     parameter.
 
@@ -1146,6 +1170,13 @@ class basic_json
     will only insert newlines. -1 (the default) selects the most compact
     representation
 
+    @return string containing the serialization of the JSON value
+
+    @complexity Linear.
+
+    @liveexample{The following example shows the effect of different @a indent
+    parameters to the result of the serializaion.,dump}
+
     @see https://docs.python.org/2/library/json.html#json.dump
     */
     string_t dump(const int indent = -1) const noexcept