more documentation

.gitignore

@@ -4,3 +4,4 @@ json_benchmarks
 working
 
 html
+me.nlohmann.json.docset

Doxyfile

@@ -145,7 +145,7 @@ HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =
 HTML_FOOTER            =
 HTML_STYLESHEET        =
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = docs/mylayout.css
 HTML_EXTRA_FILES       =
 HTML_COLORSTYLE_HUE    = 220
 HTML_COLORSTYLE_SAT    = 100

Makefile

@@ -15,19 +15,28 @@ clean:
 json_unit: test/unit.cpp src/json.hpp test/catch.hpp
 	$(CXX) -std=c++11 $(CXXFLAGS) $(FLAGS) $(CPPFLAGS) -I src -I test $< $(LDFLAGS) -o $@
 
+# execute the unit tests and check documentation
 check: json_unit
 	./json_unit "*"
 	make check -C docs/examples
 
-docset:
+doxygen: update_docs src/json.hpp
+	doxygen
+	gsed -i 's@&lt; ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType &gt;@@g' html/*.html
+	gsed -i 's@&lt;&#160;ObjectType,&#160;ArrayType,&#160;StringType,&#160;BooleanType,&#160;NumberIntegerType,&#160;NumberFloatType,&#160;AllocatorType&#160;&gt;@@g' html/*.html
+
+docset: update_docs src/json.hpp
 	cp Doxyfile Doxyfile_docset
 	gsed -i 's/DISABLE_INDEX          = NO/DISABLE_INDEX          = YES/' Doxyfile_docset
 	gsed -i 's/SEARCHENGINE           = YES/SEARCHENGINE           = NO/' Doxyfile_docset
 	gsed -i 's/GENERATE_TREEVIEW      = YES/GENERATE_TREEVIEW      = NO/' Doxyfile_docset
 	gsed -i 's/SEPARATE_MEMBER_PAGES  = NO/SEPARATE_MEMBER_PAGES  = YES/' Doxyfile_docset
 	gsed -i 's/BINARY_TOC             = YES/BINARY_TOC             = NO/' Doxyfile_docset
+	gsed -i 's@HTML_EXTRA_STYLESHEET  = docs/mylayout.css@HTML_EXTRA_STYLESHEET  = docs/mylayout_docset.css@' Doxyfile_docset
 	rm -fr html *.docset
 	doxygen Doxyfile_docset
+	gsed -i 's@&lt; ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberFloatType, AllocatorType &gt;@@g' html/*.html
+	gsed -i 's@&lt;&#160;ObjectType,&#160;ArrayType,&#160;StringType,&#160;BooleanType,&#160;NumberIntegerType,&#160;NumberFloatType,&#160;AllocatorType&#160;&gt;@@g' html/*.html
 	make -C html
 	mv html/*.docset .
 	gsed -i 's@<string>doxygen</string>@<string>json</string>@' me.nlohmann.json.docset/Contents/Info.plist

docs/doxyindex.cpp

@@ -1,21 +1,9 @@
 /*!
 @mainpage
 
+See @ref nlohmann::basic_json
+
 @copyright Niels Lohmann\n
 @include "../../LICENSE.MIT"
 */
 
-/*!
-@defgroup container Container
-
-@brief methods and types to satisfy the Container requirements
-
-A Container is an object used to store other objects and taking care of the
-management of the memory used by the objects it contains.
-
-@see http://en.cppreference.com/w/cpp/concept/Container
-*/
-
-/*!
-@defgroup reversiblecontainer Reversible Container
-*/

docs/examples/array.cpp

@@ -0,0 +1,18 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON arrays
+    json j_no_init_list = json::array();
+    json j_empty_init_list = json::array({});
+    json j_nonempty_init_list = json::array({1, 2, 3, 4});
+    json j_list_of_pairs = json::array({ {"one", 1}, {"two", 2} });
+
+    // serialize the JSON arrays
+    std::cout << j_no_init_list << '\n';
+    std::cout << j_empty_init_list << '\n';
+    std::cout << j_nonempty_init_list << '\n';
+    std::cout << j_list_of_pairs << '\n';
+}

docs/examples/array.output

@@ -0,0 +1,4 @@
+[]
+[]
+[1,2,3,4]
+[["one",1],["two",2]]

docs/examples/basic_json__list_init_t.cpp

@@ -0,0 +1,20 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json j_empty_init_list = json({});
+    json j_object = { {"one", 1}, {"two", 2} };
+    json j_array = {1, 2, 3, 4};
+    json j_nested_object = { {"one", {1}}, {"two", {1, 2}} };
+    json j_nested_array = { {{1}, "one"}, {{1, 2}, "two"} };
+
+    // serialize the JSON value
+    std::cout << j_empty_init_list << '\n';
+    std::cout << j_object << '\n';
+    std::cout << j_array << '\n';
+    std::cout << j_nested_object << '\n';
+    std::cout << j_nested_array << '\n';
+}

docs/examples/basic_json__list_init_t.output

@@ -0,0 +1,5 @@
+{}
+{"one":1,"two":2}
+[1,2,3,4]
+{"one":[1],"two":[1,2]}
+[[[1],"one"],[[1,2],"two"]]

docs/examples/basic_json__size_type_basic_json.cpp

@@ -0,0 +1,17 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create an array by creating copies of a JSON value
+    json value = "Hello";
+    json array_0 = json(0, value);
+    json array_1 = json(1, value);
+    json array_5 = json(5, value);
+
+    // serialize the JSON arrays
+    std::cout << array_0 << '\n';
+    std::cout << array_1 << '\n';
+    std::cout << array_5 << '\n';
+}

docs/examples/basic_json__size_type_basic_json.output

@@ -0,0 +1,3 @@
+[]
+["Hello"]
+["Hello","Hello","Hello","Hello","Hello"]

docs/examples/clear.cpp

@@ -0,0 +1,33 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json j_null;
+    json j_boolean = true;
+    json j_number_integer = 17;
+    json j_number_float = 23.42;
+    json j_object = {{"one", 1}, {"two", 2}};
+    json j_array = {1, 2, 4, 8, 16};
+    json j_string = "Hello, world";
+
+    // call clear()
+    j_null.clear();
+    j_boolean.clear();
+    j_number_integer.clear();
+    j_number_float.clear();
+    j_object.clear();
+    j_array.clear();
+    j_string.clear();
+
+    // serialize the cleared values()
+    std::cout << j_null << '\n';
+    std::cout << j_boolean << '\n';
+    std::cout << j_number_integer << '\n';
+    std::cout << j_number_float << '\n';
+    std::cout << j_object << '\n';
+    std::cout << j_array << '\n';
+    std::cout << j_string << '\n';
+}

docs/examples/clear.output

@@ -0,0 +1,7 @@
+null
+false
+0
+0
+{}
+[]
+""

docs/examples/max_size.cpp

@@ -0,0 +1,24 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON values
+    json j_null;
+    json j_boolean = true;
+    json j_number_integer = 17;
+    json j_number_float = 23.42;
+    json j_object = {{"one", 1}, {"two", 2}};
+    json j_array = {1, 2, 4, 8, 16};
+    json j_string = "Hello, world";
+
+    // call max_size()
+    std::cout << j_null.max_size() << '\n';
+    std::cout << j_boolean.max_size() << '\n';
+    std::cout << j_number_integer.max_size() << '\n';
+    std::cout << j_number_float.max_size() << '\n';
+    std::cout << j_object.max_size() << '\n';
+    std::cout << j_array.max_size() << '\n';
+    std::cout << j_string.max_size() << '\n';
+}

docs/examples/max_size.output

@@ -0,0 +1,7 @@
+0
+1
+1
+1
+256204778801521550
+1152921504606846975
+1

docs/examples/object.cpp

@@ -0,0 +1,17 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON arrays
+    json j_no_init_list = json::object();
+    json j_empty_init_list = json::object({});
+    json j_list_of_pairs = json::object({ {"one", 1}, {"two", 2} });
+    //json j_invalid_list = json::object({ "one", 1 }); // would throw
+
+    // serialize the JSON arrays
+    std::cout << j_no_init_list << '\n';
+    std::cout << j_empty_init_list << '\n';
+    std::cout << j_list_of_pairs << '\n';
+}

docs/examples/object.output

@@ -0,0 +1,3 @@
+{}
+{}
+{"one":1,"two":2}

docs/mylayout.css

@@ -0,0 +1,7 @@
+.memtemplate {
+    display: none;
+}
+
+.memTemplParams {
+    display: none;
+}

docs/mylayout_docset.css

@@ -0,0 +1,15 @@
+.memtemplate {
+    display: none;
+}
+
+.memTemplParams {
+    display: none;
+}
+
+.navtab {
+    display: none;
+}
+
+#top, .footer {
+    display: none;
+}

src/json.hpp

@@ -368,12 +368,12 @@ class basic_json
 
     Value type  | initial value
     ----------- | -------------
-    null        | @c null
-    boolean     | @c false
-    string      | @c ""
-    number      | @c 0
-    object      | @c {}
-    array       | @c []
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
     @param value  the type of the value to create
 
@@ -643,7 +643,72 @@ class basic_json
         : basic_json(number_float_t(value))
     {}
 
-    /// create a container (array or object) from an initializer list
+    /*!
+    @brief create a container (array or object) from an initializer list
+
+    Creates a JSON value of type array or object from the passed initializer
+    list @a init. In case @a type_deduction is `true` (default), the type of
+    the JSON value to be created is deducted from the initializer list @a init
+    according to the following rules:
+
+    1. If the list is empty, an empty JSON object value `{}` is created.
+    2. If the list consists of pairs whose first element is a string, a JSON
+    object value is created where the first elements of the pairs are treated
+    as keys and the second elements are as values.
+    3. In all other cases, an array is created.
+
+    The rules aim to create the best fit between a C++ initializer list and
+    JSON values. The ratioinale is as follows:
+
+    1. The empty initializer list is written as `{}` which is exactly an empty
+    JSON object.
+    2. C++ has now way of describing mapped types other than to list a list of
+    pairs. As JSON requires that keys must be of type string, rule 2 is the
+    weakest constraint one can pose on initializer lists to interpret them as
+    an object.
+    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:
+
+    - the empty array (`[]`): use @ref array(list_init_t) with an empty
+      initializer list in this case
+    - arrays whose elements satisfy rule 2: use @ref array(list_init_t) with
+      the same initializer list in this case
+
+    @note When used without parentheses around an empty initializer list, @ref
+    basic_json() is called instead of this function, yielding the JSON null
+    value.
+
+    @param init  initializer list with JSON values
+
+    @param type_deduction  internal parameter; when set to `true`, the type of
+    the JSON value is deducted from the initializer list @a init; when set to
+    `false`, the type provided via @a manual_type is forced. This mode is used
+    by the functions @ref array(list_init_t) and @ref object(list_init_t).
+
+    @param manual_type  internal parameter; when @a type_deduction is set to
+    `false`, the created JSON value will use the provided type (only @ref
+    value_t::array and @ref value_t::object are valid); when @a type_deduction
+    is set to `true`, this parameter has no effect
+
+    @return a JSON value created from the initializer list @a init; the type is
+    either an array or an object
+
+    @throw std::domain_error if @a type_deduction is `false`, @a manual_type is
+    `value_t::object`, but @a init contains an element which is not a pair
+    whose first element is a string
+
+    @complexity Linear in the size of the initializer list @a init.
+
+    @liveexample{The example below shows how JSON values are created from
+    initializer lists,basic_json__list_init_t}
+
+    @sa @ref basic_json array(list_init_t) - create a JSON array value from
+    an initializer list
+    @sa @ref basic_json object(list_init_t) - create a JSON object value from
+    an initializer list
+    */
     basic_json(list_init_t init, bool type_deduction = true,
                value_t manual_type = value_t::array)
     {
@@ -701,25 +766,101 @@ class basic_json
         }
     }
 
-    /// explicitly create an array from an initializer list
+    /*!
+    @brief explicitly create an array from an initializer list
+
+    Creates a JSON array value from a given initializer list. That is, given a
+    list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
+    initializer list is empty, the empty array `[]` is created.
+
+    @note This function is only needed to express two edge cases that cannot be
+    realized with the initializer list constructor (@ref
+    basic_json(list_init_t, bool, value_t)). These cases are:
+    1. creating an array whose elements are all pairs whose first element is a
+    string - in this case, the initializer list constructor would create an
+    object, taking the first elements as keys
+    2. creating an empty array - passing the empty initializer list to the
+    initializer list constructor yields an empty object
+
+    @param init  initializer list with JSON values to create an array from
+    (optional)
+
+    @return JSON array value
+
+    @complexity Linear in the size of @a init.
+
+    @liveexample{The following code shows an example for the @ref array
+    function.,array}
+
+    @sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
+    an initializer list
+    @sa @ref basic_json object(list_init_t) - create a JSON object value from
+    an initializer list
+    */
     static basic_json array(list_init_t init = list_init_t())
     {
         return basic_json(init, false, value_t::array);
     }
 
-    /// explicitly create an object from an initializer list
+    /*!
+    @brief explicitly create an object from an initializer list
+
+    Creates a JSON object value from a given initializer list. The initializer
+    lists elements must be pairs, and their first elments must be strings. If
+    the initializer list is empty, the empty object `{}` is created.
+
+    @note This function is only added for symmetry reasons. In contrast to the
+    related function @ref basic_json array(list_init_t), there are no cases
+    which can only be expressed by this function. That is, any initializer list
+    @a init can also be passed to the initializer list constructor @ref
+    basic_json(list_init_t, bool, value_t).
+
+    @param init  initializer list to create an object from (optional)
+
+    @return JSON object value
+
+    @throw std::domain_error if @a init is not a pair whose first elements are
+    strings; thrown by @ref basic_json(list_init_t, bool, value_t)
+
+    @complexity Linear in the size of @a init.
+
+    @liveexample{The following code shows an example for the @ref object
+    function.,object}
+
+    @sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
+    an initializer list
+    @sa @ref basic_json array(list_init_t) - create a JSON array value from an
+    initializer list
+    */
     static basic_json object(list_init_t init = list_init_t())
     {
         return basic_json(init, false, value_t::object);
     }
 
-    /// construct an array with count copies of given value
-    basic_json(size_type count, const basic_json& other)
+    /*!
+    @brief construct an array with count copies of given value
+
+    Constructs a JSON array value by creating @a count copies of a passed
+    value. In case @a count is `0`, an empty array is created. As postcondition,
+    `std::distance(begin(),end()) == count` holds.
+
+    @param count  the number of JSON copies of @a value to create
+    @param value  the JSON value to copy
+
+    @return A JSON array value with @a count copies of @a value.
+
+    @complexity Linear in @a count.
+
+    @liveexample{The following code shows examples for the @ref
+    basic_json(size_type\, const basic_json&)
+    constructor.,basic_json__size_type_basic_json}
+    */
+    basic_json(size_type count, const basic_json& value)
         : m_type(value_t::array)
     {
         AllocatorType<array_t> alloc;
         m_value.array = alloc.allocate(1);
-        alloc.construct(m_value.array, count, other);
+        alloc.construct(m_value.array, count, value);
     }
 
     /// construct a JSON container given an iterator range
@@ -2163,6 +2304,34 @@ class basic_json
 
     /*!
     @brief returns the maximum possible number of elements
+
+    Returns the maximum number of elements a JSON value is able to hold due to
+    system or library implementation limitations, i.e. `std::distance(begin(),
+    end())` for the JSON value.
+
+    @return The return value depends on the different value types and is
+            defined as follows:
+            Value type  | return value
+            ----------- | -------------
+            null        | @c 0
+            boolean     | @c 1
+            string      | @c 1
+            number      | @c 1
+            object      | result of function object_t::max_size()
+            array       | result of function array_t::max_size()
+
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
+                Container concept; that is, their max_size() functions have
+                constant complexity.
+
+    @requirement This function satisfies the Container requirements:
+    - The complexity is constant.
+    - Has the semantics of returning `b.size()` where `b` is the largest
+      possible JSON value.
+
+    @liveexample{The following code calls @ref max_size on the different value
+    types. Note the output is implementation specific.,max_size}
+
     @ingroup container
     */
     size_type max_size() const noexcept
@@ -2202,7 +2371,29 @@ class basic_json
     /// @name modifiers
     /// @{
 
-    /// clears the contents
+    /*!
+    @brief clears the contents
+
+    Clears the content of a JSON value and resets it to the default value as
+    if @ref basic_json(value_t) would have been called:
+
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
+
+    @note Floating-point numbers are set to `0.0` which will be serialized to
+    `0`. The vale type remains @ref number_float_t.
+
+    @complexity Linear in the size of the JSON value.
+
+    @liveexample{The example below shows the effect of @ref clear to different
+    JSON value types.,clear}
+    */
     void clear() noexcept
     {
         switch (m_type)

src/json.hpp.re2c

@@ -368,12 +368,12 @@ class basic_json
 
     Value type  | initial value
     ----------- | -------------
-    null        | @c null
-    boolean     | @c false
-    string      | @c ""
-    number      | @c 0
-    object      | @c {}
-    array       | @c []
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
 
     @param value  the type of the value to create
 
@@ -643,7 +643,72 @@ class basic_json
         : basic_json(number_float_t(value))
     {}
 
-    /// create a container (array or object) from an initializer list
+    /*!
+    @brief create a container (array or object) from an initializer list
+
+    Creates a JSON value of type array or object from the passed initializer
+    list @a init. In case @a type_deduction is `true` (default), the type of
+    the JSON value to be created is deducted from the initializer list @a init
+    according to the following rules:
+
+    1. If the list is empty, an empty JSON object value `{}` is created.
+    2. If the list consists of pairs whose first element is a string, a JSON
+    object value is created where the first elements of the pairs are treated
+    as keys and the second elements are as values.
+    3. In all other cases, an array is created.
+
+    The rules aim to create the best fit between a C++ initializer list and
+    JSON values. The ratioinale is as follows:
+
+    1. The empty initializer list is written as `{}` which is exactly an empty
+    JSON object.
+    2. C++ has now way of describing mapped types other than to list a list of
+    pairs. As JSON requires that keys must be of type string, rule 2 is the
+    weakest constraint one can pose on initializer lists to interpret them as
+    an object.
+    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:
+
+    - the empty array (`[]`): use @ref array(list_init_t) with an empty
+      initializer list in this case
+    - arrays whose elements satisfy rule 2: use @ref array(list_init_t) with
+      the same initializer list in this case
+
+    @note When used without parentheses around an empty initializer list, @ref
+    basic_json() is called instead of this function, yielding the JSON null
+    value.
+
+    @param init  initializer list with JSON values
+
+    @param type_deduction  internal parameter; when set to `true`, the type of
+    the JSON value is deducted from the initializer list @a init; when set to
+    `false`, the type provided via @a manual_type is forced. This mode is used
+    by the functions @ref array(list_init_t) and @ref object(list_init_t).
+
+    @param manual_type  internal parameter; when @a type_deduction is set to
+    `false`, the created JSON value will use the provided type (only @ref
+    value_t::array and @ref value_t::object are valid); when @a type_deduction
+    is set to `true`, this parameter has no effect
+
+    @return a JSON value created from the initializer list @a init; the type is
+    either an array or an object
+
+    @throw std::domain_error if @a type_deduction is `false`, @a manual_type is
+    `value_t::object`, but @a init contains an element which is not a pair
+    whose first element is a string
+
+    @complexity Linear in the size of the initializer list @a init.
+
+    @liveexample{The example below shows how JSON values are created from
+    initializer lists,basic_json__list_init_t}
+
+    @sa @ref basic_json array(list_init_t) - create a JSON array value from
+    an initializer list
+    @sa @ref basic_json object(list_init_t) - create a JSON object value from
+    an initializer list
+    */
     basic_json(list_init_t init, bool type_deduction = true,
                value_t manual_type = value_t::array)
     {
@@ -701,25 +766,101 @@ class basic_json
         }
     }
 
-    /// explicitly create an array from an initializer list
+    /*!
+    @brief explicitly create an array from an initializer list
+
+    Creates a JSON array value from a given initializer list. That is, given a
+    list of values `a, b, c`, creates the JSON value `[a, b, c]`. If the
+    initializer list is empty, the empty array `[]` is created.
+
+    @note This function is only needed to express two edge cases that cannot be
+    realized with the initializer list constructor (@ref
+    basic_json(list_init_t, bool, value_t)). These cases are:
+    1. creating an array whose elements are all pairs whose first element is a
+    string - in this case, the initializer list constructor would create an
+    object, taking the first elements as keys
+    2. creating an empty array - passing the empty initializer list to the
+    initializer list constructor yields an empty object
+
+    @param init  initializer list with JSON values to create an array from
+    (optional)
+
+    @return JSON array value
+
+    @complexity Linear in the size of @a init.
+
+    @liveexample{The following code shows an example for the @ref array
+    function.,array}
+
+    @sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
+    an initializer list
+    @sa @ref basic_json object(list_init_t) - create a JSON object value from
+    an initializer list
+    */
     static basic_json array(list_init_t init = list_init_t())
     {
         return basic_json(init, false, value_t::array);
     }
 
-    /// explicitly create an object from an initializer list
+    /*!
+    @brief explicitly create an object from an initializer list
+
+    Creates a JSON object value from a given initializer list. The initializer
+    lists elements must be pairs, and their first elments must be strings. If
+    the initializer list is empty, the empty object `{}` is created.
+
+    @note This function is only added for symmetry reasons. In contrast to the
+    related function @ref basic_json array(list_init_t), there are no cases
+    which can only be expressed by this function. That is, any initializer list
+    @a init can also be passed to the initializer list constructor @ref
+    basic_json(list_init_t, bool, value_t).
+
+    @param init  initializer list to create an object from (optional)
+
+    @return JSON object value
+
+    @throw std::domain_error if @a init is not a pair whose first elements are
+    strings; thrown by @ref basic_json(list_init_t, bool, value_t)
+
+    @complexity Linear in the size of @a init.
+
+    @liveexample{The following code shows an example for the @ref object
+    function.,object}
+
+    @sa @ref basic_json(list_init_t, bool, value_t) - create a JSON value from
+    an initializer list
+    @sa @ref basic_json array(list_init_t) - create a JSON array value from an
+    initializer list
+    */
     static basic_json object(list_init_t init = list_init_t())
     {
         return basic_json(init, false, value_t::object);
     }
 
-    /// construct an array with count copies of given value
-    basic_json(size_type count, const basic_json& other)
+    /*!
+    @brief construct an array with count copies of given value
+
+    Constructs a JSON array value by creating @a count copies of a passed
+    value. In case @a count is `0`, an empty array is created. As postcondition,
+    `std::distance(begin(),end()) == count` holds.
+
+    @param count  the number of JSON copies of @a value to create
+    @param value  the JSON value to copy
+
+    @return A JSON array value with @a count copies of @a value.
+
+    @complexity Linear in @a count.
+
+    @liveexample{The following code shows examples for the @ref
+    basic_json(size_type\, const basic_json&)
+    constructor.,basic_json__size_type_basic_json}
+    */
+    basic_json(size_type count, const basic_json& value)
         : m_type(value_t::array)
     {
         AllocatorType<array_t> alloc;
         m_value.array = alloc.allocate(1);
-        alloc.construct(m_value.array, count, other);
+        alloc.construct(m_value.array, count, value);
     }
 
     /// construct a JSON container given an iterator range
@@ -2163,6 +2304,34 @@ class basic_json
 
     /*!
     @brief returns the maximum possible number of elements
+
+    Returns the maximum number of elements a JSON value is able to hold due to
+    system or library implementation limitations, i.e. `std::distance(begin(),
+    end())` for the JSON value.
+
+    @return The return value depends on the different value types and is
+            defined as follows:
+            Value type  | return value
+            ----------- | -------------
+            null        | @c 0
+            boolean     | @c 1
+            string      | @c 1
+            number      | @c 1
+            object      | result of function object_t::max_size()
+            array       | result of function array_t::max_size()
+
+    @complexity Constant, as long as @ref array_t and @ref object_t satisfy the
+                Container concept; that is, their max_size() functions have
+                constant complexity.
+
+    @requirement This function satisfies the Container requirements:
+    - The complexity is constant.
+    - Has the semantics of returning `b.size()` where `b` is the largest
+      possible JSON value.
+
+    @liveexample{The following code calls @ref max_size on the different value
+    types. Note the output is implementation specific.,max_size}
+
     @ingroup container
     */
     size_type max_size() const noexcept
@@ -2202,7 +2371,29 @@ class basic_json
     /// @name modifiers
     /// @{
 
-    /// clears the contents
+    /*!
+    @brief clears the contents
+
+    Clears the content of a JSON value and resets it to the default value as
+    if @ref basic_json(value_t) would have been called:
+
+    Value type  | initial value
+    ----------- | -------------
+    null        | `null`
+    boolean     | `false`
+    string      | `""`
+    number      | `0`
+    object      | `{}`
+    array       | `[]`
+
+    @note Floating-point numbers are set to `0.0` which will be serialized to
+    `0`. The vale type remains @ref number_float_t.
+
+    @complexity Linear in the size of the JSON value.
+
+    @liveexample{The example below shows the effect of @ref clear to different
+    JSON value types.,clear}
+    */
     void clear() noexcept
     {
         switch (m_type)