improved documentation

doc/css/mylayout.css

@@ -12,3 +12,7 @@ pre.fragment {
     white-space: -o-pre-wrap;    /* Opera 7 */
     word-wrap: break-word;       /* Internet Explorer 5.5+ */
 }
+
+td.paramname {
+    vertical-align: top;
+}

doc/index.md

@@ -3,7 +3,54 @@
 These pages contain the API documentation of JSON for Modern C++, a C++11 header-only JSON class.
 
 - @link nlohmann::basic_json `basic_json` class @endlink
-- [Function index](functions_func.html)
+- [Functions](functions_func.html)
+  - object inspection
+    - @link nlohmann::basic_json::dump dump @endlink -- value serialization
+    - @link nlohmann::basic_json::type type @endlink -- type of the value
+    - @link nlohmann::basic_json::is_primitive is_primitive @endlink,
+      @link nlohmann::basic_json::is_structured is_structured @endlink,
+      @link nlohmann::basic_json::is_null is_null @endlink,
+      @link nlohmann::basic_json::is_boolean is_boolean @endlink,
+      @link nlohmann::basic_json::is_number is_number @endlink,
+      @link nlohmann::basic_json::is_number_integer is_number_integer @endlink,
+      @link nlohmann::basic_json::is_number_unsigned is_number_unsigned @endlink,
+      @link nlohmann::basic_json::is_number_float is_number_float @endlink,
+      @link nlohmann::basic_json::is_object is_object @endlink,
+      @link nlohmann::basic_json::is_array is_array @endlink,
+      @link nlohmann::basic_json::is_string is_string @endlink,
+      @link nlohmann::basic_json::is_discarded is_discarded @endlink -- check for value type
+    - @link nlohmann::basic_json::operator value_t() const operator value_t @endlink -- type of the value (implicit conversion)
+  - value access
+    - @link nlohmann::basic_json::get get @endlink -- get a value
+    - @link nlohmann::basic_json::get_ptr get_ptr @endlink -- get a value pointer
+    - @link nlohmann::basic_json::get_ref get_ref @endlink -- get a value reference
+    - @link nlohmann::basic_json::operator ValueType() const operator ValueType @endlink -- get a value (implicit conversion)
+  - element access
+    - @link nlohmann::basic_json::at(size_type) at @endlink -- access array element with bounds checking
+    - @link nlohmann::basic_json::at(const typename object_t::key_type & 	key) at @endlink -- access object element with bounds checking
+    - @link nlohmann::basic_json::operator[](size_type) operator[] @endlink -- access array element
+    - @link nlohmann::basic_json::operator[](const typename object_t::key_type & 	key) operator[] @endlink -- access object element
+    - @link nlohmann::basic_json::value value @endlink -- access object element with default value
+    - @link nlohmann::basic_json::front front @endlink -- access the first element
+    - @link nlohmann::basic_json::back back @endlink -- access the last element 
+  - iterators
+    - begin, cbegin
+    - end, cend
+    - rbegin, crbegin
+    - rend, crend
+  - capacity
+    - @link nlohmann::basic_json::empty empty @endlink -- checks whether the container is empty
+    - @link nlohmann::basic_json::size size @endlink -- returns the number of elements
+    - @link nlohmann::basic_json::max_size max_size @endlink -- returns the maximum possible number of elements
+  - modifiers
+    - @link nlohmann::basic_json::clear clear @endlink -- clears the contents
+    - @link nlohmann::basic_json::push_back(const nlohmann::basic_json &) push_back @endlink -- add an object to an array
+    - @link nlohmann::basic_json::operator+=(const nlohmann::basic_json &) operator+= @endlink -- add an object to an array
+    - @link nlohmann::basic_json::insert insert @endlink -- inserts elements
+    - @link nlohmann::basic_json::swap swap @endlink -- exchanges the values
+  - lexicographical comparison operators
+  - serialization
+  - deserialization
 - Types
   - @link nlohmann::basic_json::array_t arrays @endlink
   - @link nlohmann::basic_json::object_t objects @endlink

src/json.hpp

@@ -1019,11 +1019,14 @@ class basic_json
     @brief create an object (implicit)
 
     Create an object JSON value with a given content. This constructor allows
-    any type that can be used to construct values of type @ref object_t.
+    any type @a CompatibleObjectType that can be used to construct values of
-    Examples include the types `std::map` and `std::unordered_map`.
+    type @ref object_t.
 
-    @tparam CompatibleObjectType an object type whose `key_type` and
+    @tparam CompatibleObjectType An object type whose `key_type` and
-    `value_type` is compatible to @ref object_t
+    `value_type` is compatible to @ref object_t. Examples include `std::map`,
+    `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with
+    a `key_type` of `std::string`, and a `value_type` from which a @ref
+    basic_json value can be constructed.
 
     @param[in] val  a value for the object
 
@@ -1078,11 +1081,14 @@ class basic_json
     @brief create an array (implicit)
 
     Create an array JSON value with a given content. This constructor allows
-    any type that can be used to construct values of type @ref array_t.
+    any type @a CompatibleArrayType that can be used to construct values of
-    Examples include the types `std::vector`, `std::list`, and `std::set`.
+    type @ref array_t.
 
-    @tparam CompatibleArrayType an object type whose `value_type` is compatible
+    @tparam CompatibleArrayType An object type whose `value_type` is compatible
-    to @ref array_t
+    to @ref array_t. Examples include `std::vector`, `std::deque`, `std::list`,
+    `std::forward_list`, `std::array`, `std::set`, `std::unordered_set`,
+    `std::multiset`, and `unordered_multiset` with a `value_type` from which a
+    @ref basic_json value can be constructed.
 
     @param[in] val  a value for the array
 
@@ -1172,7 +1178,7 @@ class basic_json
     @param[in] val  a value for the string
 
     @tparam CompatibleStringType an string type which is compatible to @ref
-    string_t
+    string_t, for instance `std::string`.
 
     @complexity Linear in the size of the passed @a val.
 
@@ -1218,15 +1224,13 @@ class basic_json
 
     Create an integer number JSON value with a given content.
 
-    @tparam T  helper type to compare number_integer_t and int (not visible in)
+    @tparam T A helper type to remove this function via SFINAE in case @ref
-    the interface.
+    number_integer_t is the same as `int`. In this case, this constructor would
+    have the same signature as @ref basic_json(const int value). Note the
+    helper type @a T is not visible in this constructor's interface.
 
     @param[in] val  an integer to create a JSON number from
 
-    @note This constructor would have the same signature as @ref
-    basic_json(const int value), so we need to switch this one off in case
-    number_integer_t is the same as int. This is done via the helper type @a T.
-
     @complexity Constant.
 
     @liveexample{The example below shows the construction of an integer
@@ -1282,12 +1286,12 @@ class basic_json
     @brief create an integer number (implicit)
 
     Create an integer number JSON value with a given content. This constructor
-    allows any type that can be used to construct values of type @ref
+    allows any type @a CompatibleNumberIntegerType that can be used to
-    number_integer_t. Examples may include the types `int`, `int32_t`, or
+    construct values of type @ref number_integer_t.
-    `short`.
 
-    @tparam CompatibleNumberIntegerType an integer type which is compatible to
+    @tparam CompatibleNumberIntegerType An integer type which is compatible to
-    @ref number_integer_t.
+    @ref number_integer_t. Examples include the types `int`, `int32_t`, `long`,
+    and `short`.
 
     @param[in] val  an integer to create a JSON number from
 
@@ -1346,12 +1350,12 @@ class basic_json
     @brief create an unsigned number (implicit)
 
     Create an unsigned number JSON value with a given content. This constructor
-    allows any type that can be used to construct values of type @ref
+    allows any type @a CompatibleNumberUnsignedType that can be used to
-    number_unsigned_t. Examples may include the types `unsigned int`,
+    construct values of type @ref number_unsigned_t.
-    `uint32_t`, or `unsigned short`.
 
-    @tparam CompatibleNumberUnsignedType an integer type which is compatible to
+    @tparam CompatibleNumberUnsignedType An integer type which is compatible to
-    @ref number_unsigned_t.
+    @ref number_unsigned_t. Examples may include the types `unsigned int`,
+    `uint32_t`, or `unsigned short`.
 
     @param[in] val  an unsigned integer to create a JSON number from
 
@@ -1413,11 +1417,11 @@ class basic_json
     @brief create an floating-point number (implicit)
 
     Create an floating-point number JSON value with a given content. This
-    constructor allows any type that can be used to construct values of type
+    constructor allows any type @a CompatibleNumberFloatType that can be used
-    @ref number_float_t. Examples may include the types `float`.
+    to construct values of type @ref number_float_t.
 
-    @tparam CompatibleNumberFloatType a floating-point type which is compatible
+    @tparam CompatibleNumberFloatType A floating-point type which is compatible
-    to @ref number_float_t.
+    to @ref number_float_t. Examples may include the types `float` or `double`.
 
     @param[in] val  a floating-point to create a JSON number from
 
@@ -1826,7 +1830,7 @@ class basic_json
 
     @since version 2.0.0
     */
-    basic_json(std::istream& i, parser_callback_t cb = nullptr)
+    explicit basic_json(std::istream& i, parser_callback_t cb = nullptr)
     {
         *this = parser(i, cb).parse();
     }

src/json.hpp.re2c

@@ -143,6 +143,9 @@ default)
  - [ReversibleContainer](http://en.cppreference.com/w/cpp/concept/ReversibleContainer);
    JSON values can be used like STL containers and provide reverse iterator
    access.
+- Container Elements
+ - [Eraseable](http://en.cppreference.com/w/cpp/concept/Erasable):
+   JSON values can be destroyed by a given allocator.
 
 @internal
 @note ObjectType trick from http://stackoverflow.com/a/9860911
@@ -1019,11 +1022,14 @@ class basic_json
     @brief create an object (implicit)
 
     Create an object JSON value with a given content. This constructor allows
-    any type that can be used to construct values of type @ref object_t.
+    any type @a CompatibleObjectType that can be used to construct values of
-    Examples include the types `std::map` and `std::unordered_map`.
+    type @ref object_t.
 
-    @tparam CompatibleObjectType an object type whose `key_type` and
+    @tparam CompatibleObjectType An object type whose `key_type` and
-    `value_type` is compatible to @ref object_t
+    `value_type` is compatible to @ref object_t. Examples include `std::map`,
+    `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with
+    a `key_type` of `std::string`, and a `value_type` from which a @ref
+    basic_json value can be constructed.
 
     @param[in] val  a value for the object
 
@@ -1078,11 +1084,14 @@ class basic_json
     @brief create an array (implicit)
 
     Create an array JSON value with a given content. This constructor allows
-    any type that can be used to construct values of type @ref array_t.
+    any type @a CompatibleArrayType that can be used to construct values of
-    Examples include the types `std::vector`, `std::list`, and `std::set`.
+    type @ref array_t.
 
-    @tparam CompatibleArrayType an object type whose `value_type` is compatible
+    @tparam CompatibleArrayType An object type whose `value_type` is compatible
-    to @ref array_t
+    to @ref array_t. Examples include `std::vector`, `std::deque`, `std::list`,
+    `std::forward_list`, `std::array`, `std::set`, `std::unordered_set`,
+    `std::multiset`, and `unordered_multiset` with a `value_type` from which a
+    @ref basic_json value can be constructed.
 
     @param[in] val  a value for the array
 
@@ -1172,7 +1181,7 @@ class basic_json
     @param[in] val  a value for the string
 
     @tparam CompatibleStringType an string type which is compatible to @ref
-    string_t
+    string_t, for instance `std::string`.
 
     @complexity Linear in the size of the passed @a val.
 
@@ -1218,15 +1227,13 @@ class basic_json
 
     Create an integer number JSON value with a given content.
 
-    @tparam T  helper type to compare number_integer_t and int (not visible in)
+    @tparam T A helper type to remove this function via SFINAE in case @ref
-    the interface.
+    number_integer_t is the same as `int`. In this case, this constructor would
+    have the same signature as @ref basic_json(const int value). Note the
+    helper type @a T is not visible in this constructor's interface.
 
     @param[in] val  an integer to create a JSON number from
 
-    @note This constructor would have the same signature as @ref
-    basic_json(const int value), so we need to switch this one off in case
-    number_integer_t is the same as int. This is done via the helper type @a T.
-
     @complexity Constant.
 
     @liveexample{The example below shows the construction of an integer
@@ -1282,12 +1289,12 @@ class basic_json
     @brief create an integer number (implicit)
 
     Create an integer number JSON value with a given content. This constructor
-    allows any type that can be used to construct values of type @ref
+    allows any type @a CompatibleNumberIntegerType that can be used to
-    number_integer_t. Examples may include the types `int`, `int32_t`, or
+    construct values of type @ref number_integer_t.
-    `short`.
 
-    @tparam CompatibleNumberIntegerType an integer type which is compatible to
+    @tparam CompatibleNumberIntegerType An integer type which is compatible to
-    @ref number_integer_t.
+    @ref number_integer_t. Examples include the types `int`, `int32_t`, `long`,
+    and `short`.
 
     @param[in] val  an integer to create a JSON number from
 
@@ -1346,12 +1353,12 @@ class basic_json
     @brief create an unsigned number (implicit)
 
     Create an unsigned number JSON value with a given content. This constructor
-    allows any type that can be used to construct values of type @ref
+    allows any type @a CompatibleNumberUnsignedType that can be used to
-    number_unsigned_t. Examples may include the types `unsigned int`,
+    construct values of type @ref number_unsigned_t.
-    `uint32_t`, or `unsigned short`.
 
-    @tparam CompatibleNumberUnsignedType an integer type which is compatible to
+    @tparam CompatibleNumberUnsignedType An integer type which is compatible to
-    @ref number_unsigned_t.
+    @ref number_unsigned_t. Examples may include the types `unsigned int`,
+    `uint32_t`, or `unsigned short`.
 
     @param[in] val  an unsigned integer to create a JSON number from
 
@@ -1413,11 +1420,11 @@ class basic_json
     @brief create an floating-point number (implicit)
 
     Create an floating-point number JSON value with a given content. This
-    constructor allows any type that can be used to construct values of type
+    constructor allows any type @a CompatibleNumberFloatType that can be used
-    @ref number_float_t. Examples may include the types `float`.
+    to construct values of type @ref number_float_t.
 
-    @tparam CompatibleNumberFloatType a floating-point type which is compatible
+    @tparam CompatibleNumberFloatType A floating-point type which is compatible
-    to @ref number_float_t.
+    to @ref number_float_t. Examples may include the types `float` or `double`.
 
     @param[in] val  a floating-point to create a JSON number from
 
@@ -1826,7 +1833,7 @@ class basic_json
 
     @since version 2.0.0
     */
-    basic_json(std::istream& i, parser_callback_t cb = nullptr)
+    explicit basic_json(std::istream& i, parser_callback_t cb = nullptr)
     {
         *this = parser(i, cb).parse();
     }