From af94e712c771cabe446b1f3512dc901d40b97e4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9o=20DELRIEU?= Date: Sun, 15 Jan 2017 22:08:49 +0100 Subject: [PATCH] add basic doxygen documentations --- doc/Doxyfile | 2 +- src/json.hpp | 101 ++++++++++++++++++++++++++++++---------------- src/json.hpp.re2c | 101 ++++++++++++++++++++++++++++++---------------- 3 files changed, 135 insertions(+), 69 deletions(-) diff --git a/doc/Doxyfile b/doc/Doxyfile index 5064a0a0..4d511af3 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -109,7 +109,7 @@ RECURSIVE = NO EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = nlohmann::anonymous_namespace +EXCLUDE_SYMBOLS = nlohmann::detail EXAMPLE_PATH = examples EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO diff --git a/src/json.hpp b/src/json.hpp index 9d4a548a..838d2d07 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -116,20 +116,20 @@ namespace nlohmann @brief the JSON type enumeration This enumeration collects the different JSON types. It is internally used -to distinguish the stored values, and the functions @ref is_null(), @ref -is_object(), @ref is_array(), @ref is_string(), @ref is_boolean(), @ref -is_number() (with @ref is_number_integer(), @ref is_number_unsigned(), and -@ref is_number_float()), @ref is_discarded(), @ref is_primitive(), and -@ref is_structured() rely on it. +to distinguish the stored values, and the functions @ref basic_json::is_null(), @ref +basic_json::is_object(), @ref basic_json::is_array(), @ref basic_json::is_string(), @ref basic_json::is_boolean(), @ref +basic_json::is_number() (with @ref basic_json::is_number_integer(), @ref basic_json::is_number_unsigned(), and +@ref basic_json::is_number_float()), @ref basic_json::is_discarded(), @ref basic_json::is_primitive(), and +@ref basic_json::is_structured() rely on it. @note There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library distinguishes -these three types for numbers: @ref number_unsigned_t is used for unsigned -integers, @ref number_integer_t is used for signed integers, and @ref -number_float_t is used for floating-point numbers or to approximate +these three types for numbers: @ref basic_json::number_unsigned_t is used for unsigned +integers, @ref basic_json::number_integer_t is used for signed integers, and @ref +basic_json::number_float_t is used for floating-point numbers or to approximate integers which do not fit in the limits of their respective type. -@sa @ref basic_json(const value_t value_type) -- create a JSON value with +@sa @ref basic_json::basic_json(const value_t value_type) -- create a JSON value with the default value for a given type @since version 1.0.0 @@ -1800,18 +1800,6 @@ class basic_json @liveexample{The following code shows the constructor for different @ref value_t values,basic_json__value_t} - @sa @ref basic_json(std::nullptr_t) -- create a `null` value - @sa @ref basic_json(boolean_t value) -- create a boolean value - @sa @ref basic_json(const string_t&) -- create a string value - @sa @ref basic_json(const object_t&) -- create a object value - @sa @ref basic_json(const array_t&) -- create a array value - @sa @ref basic_json(const number_float_t) -- create a number - (floating-point) value - @sa @ref basic_json(const number_integer_t) -- create a number (integer) - value - @sa @ref basic_json(const number_unsigned_t) -- create a number (unsigned) - value - @since version 1.0.0 */ basic_json(const value_t value_type) @@ -1844,9 +1832,21 @@ class basic_json assert_invariant(); } - // constructor chosen when: - // - JSONSerializer::to_json exists for type T - // - T is not a istream, nor convertible to basic_json (float, vectors, etc) + /*! + @brief forwards the parameter to json_serializer::to_json method (U = uncvref_t) + + this constructor is chosen if: + - T is not derived from std::istream + - T is not @ref basic_json (to avoid hijacking copy/move constructors) + - T is not a @ref basic_json nested type (@ref json_pointer, @ref iterator, etc ...) + - @ref json_serializer has a to_json(basic_json_t&, T&&) method + + @param[in] val the value to be forwarded + + @throw what json_serializer::to_json throws + + @since version 2.1.0 + */ template , enable_if_t::value and not std::is_same::value and @@ -3003,7 +3003,19 @@ class basic_json } public: - // if T is basic_json, simply returns *this + /*! + @brief get special-case overload + + This overloads avoids a lot of template boilerplate, it can be seen as the identity method + + @tparam T type; T == @ref basic_json + + @return a copy of *this + + @complexity Constant. + + @since version 2.1.0 + */ template ::value, int> = 0> basic_json get() const @@ -3011,12 +3023,21 @@ class basic_json return *this; } - // This overload is chosen when: - // - T is not basic_json_t - // - JSONSerializer::from_json(basic_json const&, T&) exists - // - and JSONSerializer::from_json(basic_json const&) does not exist - // - // the latter is preferred if both are present (since it does not require a default construction of T) + /*! + @brief get overload for CopyConstructible and DefaultConstructible types + construct a default U value, and call @ref json_serializer from_json method with it + + This overloads is chosen if: + - U is not @ref basic_json + - @ref json_serializer has a from_json method of the form: void from_json(const @ref basic_json&, U&) + - @ref json_serializer does not have a from_json method of the form: U from_json(const @ref basic_json&); + + @return a value of type U + + @throw what json_serializer from_json method throws + + @since version 2.1.0 + */ template < typename T, typename U = uncvref_t, @@ -3042,9 +3063,21 @@ class basic_json return ret; } - // This overload is chosen when: - // - T is not basic_json_t - // - and JSONSerializer::from_json(basic_json const&) does not exist + /*! + @brief get overload for types than cannot be default constructed or copy constructed + + If @ref json_serializer has both overloads of from_json, this one is chosen + + This overloads is chosen if: + - U is not @ref basic_json + - @ref json_serializer has a from_json method of the form: U from_json(const @ref basic_json&); + + @return a value of type U + + @throw what json_serializer from_json method throws + + @since version 2.1.0 + */ template < typename T, enable_if_t>::value and diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 4b28a032..a3539180 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -116,20 +116,20 @@ namespace nlohmann @brief the JSON type enumeration This enumeration collects the different JSON types. It is internally used -to distinguish the stored values, and the functions @ref is_null(), @ref -is_object(), @ref is_array(), @ref is_string(), @ref is_boolean(), @ref -is_number() (with @ref is_number_integer(), @ref is_number_unsigned(), and -@ref is_number_float()), @ref is_discarded(), @ref is_primitive(), and -@ref is_structured() rely on it. +to distinguish the stored values, and the functions @ref basic_json::is_null(), @ref +basic_json::is_object(), @ref basic_json::is_array(), @ref basic_json::is_string(), @ref basic_json::is_boolean(), @ref +basic_json::is_number() (with @ref basic_json::is_number_integer(), @ref basic_json::is_number_unsigned(), and +@ref basic_json::is_number_float()), @ref basic_json::is_discarded(), @ref basic_json::is_primitive(), and +@ref basic_json::is_structured() rely on it. @note There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library distinguishes -these three types for numbers: @ref number_unsigned_t is used for unsigned -integers, @ref number_integer_t is used for signed integers, and @ref -number_float_t is used for floating-point numbers or to approximate +these three types for numbers: @ref basic_json::number_unsigned_t is used for unsigned +integers, @ref basic_json::number_integer_t is used for signed integers, and @ref +basic_json::number_float_t is used for floating-point numbers or to approximate integers which do not fit in the limits of their respective type. -@sa @ref basic_json(const value_t value_type) -- create a JSON value with +@sa @ref basic_json::basic_json(const value_t value_type) -- create a JSON value with the default value for a given type @since version 1.0.0 @@ -1800,18 +1800,6 @@ class basic_json @liveexample{The following code shows the constructor for different @ref value_t values,basic_json__value_t} - @sa @ref basic_json(std::nullptr_t) -- create a `null` value - @sa @ref basic_json(boolean_t value) -- create a boolean value - @sa @ref basic_json(const string_t&) -- create a string value - @sa @ref basic_json(const object_t&) -- create a object value - @sa @ref basic_json(const array_t&) -- create a array value - @sa @ref basic_json(const number_float_t) -- create a number - (floating-point) value - @sa @ref basic_json(const number_integer_t) -- create a number (integer) - value - @sa @ref basic_json(const number_unsigned_t) -- create a number (unsigned) - value - @since version 1.0.0 */ basic_json(const value_t value_type) @@ -1844,9 +1832,21 @@ class basic_json assert_invariant(); } - // constructor chosen when: - // - JSONSerializer::to_json exists for type T - // - T is not a istream, nor convertible to basic_json (float, vectors, etc) + /*! + @brief forwards the parameter to json_serializer::to_json method (U = uncvref_t) + + this constructor is chosen if: + - T is not derived from std::istream + - T is not @ref basic_json (to avoid hijacking copy/move constructors) + - T is not a @ref basic_json nested type (@ref json_pointer, @ref iterator, etc ...) + - @ref json_serializer has a to_json(basic_json_t&, T&&) method + + @param[in] val the value to be forwarded + + @throw what json_serializer::to_json throws + + @since version 2.1.0 + */ template , enable_if_t::value and not std::is_same::value and @@ -3003,7 +3003,19 @@ class basic_json } public: - // if T is basic_json, simply returns *this + /*! + @brief get special-case overload + + This overloads avoids a lot of template boilerplate, it can be seen as the identity method + + @tparam T type; T == @ref basic_json + + @return a copy of *this + + @complexity Constant. + + @since version 2.1.0 + */ template ::value, int> = 0> basic_json get() const @@ -3011,12 +3023,21 @@ class basic_json return *this; } - // This overload is chosen when: - // - T is not basic_json_t - // - JSONSerializer::from_json(basic_json const&, T&) exists - // - and JSONSerializer::from_json(basic_json const&) does not exist - // - // the latter is preferred if both are present (since it does not require a default construction of T) + /*! + @brief get overload for CopyConstructible and DefaultConstructible types + construct a default U value, and call @ref json_serializer from_json method with it + + This overloads is chosen if: + - U is not @ref basic_json + - @ref json_serializer has a from_json method of the form: void from_json(const @ref basic_json&, U&) + - @ref json_serializer does not have a from_json method of the form: U from_json(const @ref basic_json&); + + @return a value of type U + + @throw what json_serializer from_json method throws + + @since version 2.1.0 + */ template < typename T, typename U = uncvref_t, @@ -3042,9 +3063,21 @@ class basic_json return ret; } - // This overload is chosen when: - // - T is not basic_json_t - // - and JSONSerializer::from_json(basic_json const&) does not exist + /*! + @brief get overload for types than cannot be default constructed or copy constructed + + If @ref json_serializer has both overloads of from_json, this one is chosen + + This overloads is chosen if: + - U is not @ref basic_json + - @ref json_serializer has a from_json method of the form: U from_json(const @ref basic_json&); + + @return a value of type U + + @throw what json_serializer from_json method throws + + @since version 2.1.0 + */ template < typename T, enable_if_t>::value and