From ae5bd307a29435e8f3aedcf0a3f341908d075eaa Mon Sep 17 00:00:00 2001 From: Niels Date: Fri, 5 Feb 2016 22:30:25 +0100 Subject: [PATCH] improved documentation --- doc/css/mylayout.css | 4 +++ doc/index.md | 49 +++++++++++++++++++++++++++++++- src/json.hpp | 64 ++++++++++++++++++++++-------------------- src/json.hpp.re2c | 67 ++++++++++++++++++++++++-------------------- 4 files changed, 123 insertions(+), 61 deletions(-) diff --git a/doc/css/mylayout.css b/doc/css/mylayout.css index 1b55b49e..b4c849a3 100644 --- a/doc/css/mylayout.css +++ b/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; +} \ No newline at end of file diff --git a/doc/index.md b/doc/index.md index b1aaa40f..20c61a0c 100644 --- a/doc/index.md +++ b/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 diff --git a/src/json.hpp b/src/json.hpp index effdeb13..753d2ee0 100644 --- a/src/json.hpp +++ b/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. - Examples include the types `std::map` and `std::unordered_map`. + any type @a CompatibleObjectType that can be used to construct values of + type @ref object_t. - @tparam CompatibleObjectType an object type whose `key_type` and - `value_type` is compatible to @ref object_t + @tparam CompatibleObjectType An object type whose `key_type` and + `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. - Examples include the types `std::vector`, `std::list`, and `std::set`. + any type @a CompatibleArrayType that can be used to construct values of + type @ref array_t. - @tparam CompatibleArrayType an object type whose `value_type` is compatible - to @ref array_t + @tparam CompatibleArrayType An object type whose `value_type` is compatible + 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) - the interface. + @tparam T A helper type to remove this function via SFINAE in case @ref + 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 - number_integer_t. Examples may include the types `int`, `int32_t`, or - `short`. + allows any type @a CompatibleNumberIntegerType that can be used to + construct values of type @ref number_integer_t. - @tparam CompatibleNumberIntegerType an integer type which is compatible to - @ref number_integer_t. + @tparam CompatibleNumberIntegerType An integer type which is compatible to + @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 - number_unsigned_t. Examples may include the types `unsigned int`, - `uint32_t`, or `unsigned short`. + allows any type @a CompatibleNumberUnsignedType that can be used to + construct values of type @ref number_unsigned_t. - @tparam CompatibleNumberUnsignedType an integer type which is compatible to - @ref number_unsigned_t. + @tparam CompatibleNumberUnsignedType An integer type which is compatible to + @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 - @ref number_float_t. Examples may include the types `float`. + constructor allows any type @a CompatibleNumberFloatType that can be used + to construct values of type @ref number_float_t. - @tparam CompatibleNumberFloatType a floating-point type which is compatible - to @ref number_float_t. + @tparam CompatibleNumberFloatType A floating-point type which is compatible + 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(); } diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index e0636ab3..dadb94e7 100644 --- a/src/json.hpp.re2c +++ b/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. - Examples include the types `std::map` and `std::unordered_map`. + any type @a CompatibleObjectType that can be used to construct values of + type @ref object_t. - @tparam CompatibleObjectType an object type whose `key_type` and - `value_type` is compatible to @ref object_t + @tparam CompatibleObjectType An object type whose `key_type` and + `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. - Examples include the types `std::vector`, `std::list`, and `std::set`. + any type @a CompatibleArrayType that can be used to construct values of + type @ref array_t. - @tparam CompatibleArrayType an object type whose `value_type` is compatible - to @ref array_t + @tparam CompatibleArrayType An object type whose `value_type` is compatible + 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) - the interface. + @tparam T A helper type to remove this function via SFINAE in case @ref + 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 - number_integer_t. Examples may include the types `int`, `int32_t`, or - `short`. + allows any type @a CompatibleNumberIntegerType that can be used to + construct values of type @ref number_integer_t. - @tparam CompatibleNumberIntegerType an integer type which is compatible to - @ref number_integer_t. + @tparam CompatibleNumberIntegerType An integer type which is compatible to + @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 - number_unsigned_t. Examples may include the types `unsigned int`, - `uint32_t`, or `unsigned short`. + allows any type @a CompatibleNumberUnsignedType that can be used to + construct values of type @ref number_unsigned_t. - @tparam CompatibleNumberUnsignedType an integer type which is compatible to - @ref number_unsigned_t. + @tparam CompatibleNumberUnsignedType An integer type which is compatible to + @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 - @ref number_float_t. Examples may include the types `float`. + constructor allows any type @a CompatibleNumberFloatType that can be used + to construct values of type @ref number_float_t. - @tparam CompatibleNumberFloatType a floating-point type which is compatible - to @ref number_float_t. + @tparam CompatibleNumberFloatType A floating-point type which is compatible + 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(); }