diff --git a/include/nlohmann/detail/input/binary_reader.hpp b/include/nlohmann/detail/input/binary_reader.hpp index b9e6b304b..fb6243cc6 100644 --- a/include/nlohmann/detail/input/binary_reader.hpp +++ b/include/nlohmann/detail/input/binary_reader.hpp @@ -407,7 +407,7 @@ class binary_reader @brief Parses a C-style string from the BSON input. @param[in,out] result A reference to the string variable where the read string is to be stored. - @return `true` if the \x00-byte indicating the end of the string was + @return `true` if the \\x00-byte indicating the end of the string was encountered before the EOF; false` indicates an unexpected EOF. */ bool get_bson_cstr(string_t& result) @@ -437,7 +437,7 @@ class binary_reader @brief read a C-style string from contiguous input in one step @param[in,out] result the string to append to - @return whether the string was read; if the input has no \x00-byte, nothing + @return whether the string was read; if the input has no \\x00-byte, nothing is read, and @ref get_bson_cstr reports the end of the input */ bool get_bson_cstr_bulk(string_t& result, std::true_type /*bulk*/) diff --git a/include/nlohmann/detail/input/lexer.hpp b/include/nlohmann/detail/input/lexer.hpp index 00a964a17..1d4df1eb9 100644 --- a/include/nlohmann/detail/input/lexer.hpp +++ b/include/nlohmann/detail/input/lexer.hpp @@ -234,9 +234,9 @@ class lexer : public lexer_base ///////////////////// /*! - @brief get codepoint from 4 hex characters following `\u` + @brief get codepoint from 4 hex characters following `\\u` - For input "\u c1 c2 c3 c4" the codepoint is: + For input "\\u c1 c2 c3 c4" the codepoint is: (c1 * 0x1000) + (c2 * 0x0100) + (c3 * 0x0010) + c4 = (c1 << 12) + (c2 << 8) + (c3 << 4) + (c4 << 0) diff --git a/include/nlohmann/detail/iterators/iter_impl.hpp b/include/nlohmann/detail/iterators/iter_impl.hpp index 22f3ffc39..2115b6aeb 100644 --- a/include/nlohmann/detail/iterators/iter_impl.hpp +++ b/include/nlohmann/detail/iterators/iter_impl.hpp @@ -35,7 +35,7 @@ This class implements a both iterators (iterator and const_iterator) for the been set (e.g., by a constructor or a copy assignment). If the iterator is default-constructed, it is *uninitialized* and most methods are undefined. **The library uses assertions to detect calls on uninitialized iterators.** -@requirement REQ-JSON-01 The class satisfies the following concept requirements: +This class satisfies the following concept requirements (REQ-JSON-01): - [BidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator): The iterator that can be moved can be moved in both directions (i.e. diff --git a/include/nlohmann/detail/iterators/json_reverse_iterator.hpp b/include/nlohmann/detail/iterators/json_reverse_iterator.hpp index b452cfcce..d718901ae 100644 --- a/include/nlohmann/detail/iterators/json_reverse_iterator.hpp +++ b/include/nlohmann/detail/iterators/json_reverse_iterator.hpp @@ -29,7 +29,7 @@ namespace detail iterator (to create @ref reverse_iterator) and @ref const_iterator (to create @ref const_reverse_iterator). -@requirement REQ-JSON-02 The class satisfies the following concept requirements: +This class satisfies the following concept requirements (REQ-JSON-02): - [BidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator): The iterator that can be moved can be moved in both directions (i.e. diff --git a/include/nlohmann/detail/json_pointer.hpp b/include/nlohmann/detail/json_pointer.hpp index 6a3731d99..90f1d67dc 100644 --- a/include/nlohmann/detail/json_pointer.hpp +++ b/include/nlohmann/detail/json_pointer.hpp @@ -315,7 +315,7 @@ class json_pointer /*! @brief create and return a reference to the pointed to value - @complexity Linear in the number of reference tokens. + Complexity: Linear in the number of reference tokens. @throw parse_error.106 if an array index begins with '0' @throw parse_error.109 if array index is not a number @@ -402,7 +402,7 @@ class json_pointer @return reference to the JSON value pointed to by the JSON pointer - @complexity Linear in the length of the JSON pointer. + Complexity: Linear in the length of the JSON pointer. @throw parse_error.106 if an array index begins with '0' @throw parse_error.109 if an array index was not a number diff --git a/include/nlohmann/detail/macro_scope.hpp b/include/nlohmann/detail/macro_scope.hpp index 15c8864a4..4e1b79f65 100644 --- a/include/nlohmann/detail/macro_scope.hpp +++ b/include/nlohmann/detail/macro_scope.hpp @@ -195,13 +195,6 @@ #define JSON_NO_THREAD_LOCAL 1 #endif -// disable documentation warnings on clang -#if defined(__clang__) - #pragma clang diagnostic push - #pragma clang diagnostic ignored "-Wdocumentation" - #pragma clang diagnostic ignored "-Wdocumentation-unknown-command" -#endif - // allow disabling exceptions #if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION) #define JSON_THROW(exception) throw exception diff --git a/include/nlohmann/detail/macro_unscope.hpp b/include/nlohmann/detail/macro_unscope.hpp index a73951a22..134f3fa98 100644 --- a/include/nlohmann/detail/macro_unscope.hpp +++ b/include/nlohmann/detail/macro_unscope.hpp @@ -8,11 +8,6 @@ #pragma once -// restore clang diagnostic settings -#if defined(__clang__) - #pragma clang diagnostic pop -#endif - // clean up #undef JSON_ASSERT #undef JSON_INTERNAL_CATCH diff --git a/include/nlohmann/detail/output/serializer.hpp b/include/nlohmann/detail/output/serializer.hpp index f968b6001..41c52d3c7 100644 --- a/include/nlohmann/detail/output/serializer.hpp +++ b/include/nlohmann/detail/output/serializer.hpp @@ -67,7 +67,7 @@ class serializer @param[in] ichar indentation character to use @param[in] pretty_print_ whether the output shall be pretty-printed @param[in] ensure_ascii_ If @a ensure_ascii_ is true, all non-ASCII - characters in the output are escaped with `\uXXXX` sequences, and the + characters in the output are escaped with `\\uXXXX` sequences, and the result consists of ASCII characters only. @param[in] indent_step_ the indent level @param[in] error_handler_ how to react on decoding errors @@ -772,7 +772,7 @@ class serializer @param[in] s the string to escape - @complexity Linear in the length of string @a s. + Complexity: Linear in the length of string @a s. */ void dump_escaped(const string_t& s) { @@ -1290,7 +1290,7 @@ class serializer } /*! - * @brief write a lowercase "\uXXXX" escape sequence into @a string_buffer + * @brief write a lowercase "\\uXXXX" escape sequence into @a string_buffer * * Branch-free replacement for `snprintf(buf, 7, "\\u%04x", codeunit)` in the * string escaping hot path. It writes exactly six characters ('\\', 'u' and @@ -1650,7 +1650,7 @@ class serializer /// whether to pretty-print the output const bool pretty_print; - /// whether to escape non-ASCII characters with \uXXXX sequences + /// whether to escape non-ASCII characters with \\uXXXX sequences const bool ensure_ascii; /// the indent level diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 3cefc9543..698f66005 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -2339,12 +2339,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @throw what @ref json_serializer `from_json()` method throws - @liveexample{The example below shows several conversions from JSON values + The example below shows several conversions from JSON values to other types. There a few things to note: (1) Floating-point numbers can - be converted to integers\, (2) A JSON array can be converted to a standard - `std::vector`\, (3) A JSON object can be converted to C++ - associative containers such as `std::unordered_map`.,get__ValueType_const} + be converted to integers, (2) A JSON array can be converted to a standard + `std::vector`, (3) A JSON object can be converted to C++ + associative containers such as `std::unordered_map`. @since version 2.1.0 */ @@ -2411,7 +2411,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @return a copy of *this, converted into @a BasicJsonType - @complexity Depending on the implementation of the called `from_json()` + Complexity: Depending on the implementation of the called `from_json()` method. @since version 3.2.0 @@ -2435,7 +2435,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @return a copy of *this - @complexity Constant. + Complexity: Constant. @since version 2.1.0 */ @@ -2519,12 +2519,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @return pointer to the internally stored JSON value if the requested pointer type @a PointerType fits to the JSON value; `nullptr` otherwise - @complexity Constant. + Complexity: Constant. - @liveexample{The example below shows how pointers to internal values of a + The example below shows how pointers to internal values of a JSON value can be requested. Note that no type conversions are made and a `nullptr` is returned if the value and the requested pointer type does not - match.,get__PointerType} + match. @sa see @ref get_ptr() for explicit pointer-member access @@ -2618,14 +2618,14 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec to the JSON value type (e.g., the JSON value is of type boolean, but a string is requested); see example below - @complexity Linear in the size of the JSON value. + Complexity: Linear in the size of the JSON value. - @liveexample{The example below shows several conversions from JSON values + The example below shows several conversions from JSON values to other types. There a few things to note: (1) Floating-point numbers can - be converted to integers\, (2) A JSON array can be converted to a standard - `std::vector`\, (3) A JSON object can be converted to C++ - associative containers such as `std::unordered_map`.,operator__ValueType} + be converted to integers, (2) A JSON array can be converted to a standard + `std::vector`, (3) A JSON object can be converted to C++ + associative containers such as `std::unordered_map`. @since version 1.0.0 */ @@ -5007,6 +5007,19 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// @deprecated This function is deprecated since 3.8.0 and will be removed in /// version 4.0.0 of the library. Please use /// sax_parse(ptr, ptr + len) instead. + // + // Clang reports "declaration is marked with '@deprecated' command but does + // not have a deprecation attribute" for this overload even though + // JSON_HEDLEY_DEPRECATED_FOR below does expand to __attribute__((deprecated)); + // isolated reproductions of this exact declaration shape (doc comment, + // template<>, two stacked __attribute__ lines, an overload set of the same + // name) do not reproduce it, so this looks like a Clang comment/declaration + // association quirk specific to this overload within basic_json, not a + // genuine documentation bug. See #5725 item 2. +#if defined(__clang__) +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wdocumentation-deprecated-sync" +#endif template JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...)) JSON_HEDLEY_NON_NULL(2) @@ -5023,6 +5036,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec // NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg) : detail::binary_reader(std::move(ia), format).sax_parse(format, sax, strict); } +#if defined(__clang__) +#pragma clang diagnostic pop +#endif #ifndef JSON_NO_IO /// @brief deserialize from stream /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/ diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index c74ae6ac9..e39b7754b 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -2596,13 +2596,6 @@ JSON_HEDLEY_DIAGNOSTIC_POP #define JSON_NO_THREAD_LOCAL 1 #endif -// disable documentation warnings on clang -#if defined(__clang__) - #pragma clang diagnostic push - #pragma clang diagnostic ignored "-Wdocumentation" - #pragma clang diagnostic ignored "-Wdocumentation-unknown-command" -#endif - // allow disabling exceptions #if (defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)) && !defined(JSON_NOEXCEPTION) #define JSON_THROW(exception) throw exception @@ -9318,9 +9311,9 @@ class lexer : public lexer_base ///////////////////// /*! - @brief get codepoint from 4 hex characters following `\u` + @brief get codepoint from 4 hex characters following `\\u` - For input "\u c1 c2 c3 c4" the codepoint is: + For input "\\u c1 c2 c3 c4" the codepoint is: (c1 * 0x1000) + (c2 * 0x0100) + (c3 * 0x0010) + c4 = (c1 << 12) + (c2 << 8) + (c3 << 4) + (c4 << 0) @@ -13166,7 +13159,7 @@ class binary_reader @brief Parses a C-style string from the BSON input. @param[in,out] result A reference to the string variable where the read string is to be stored. - @return `true` if the \x00-byte indicating the end of the string was + @return `true` if the \\x00-byte indicating the end of the string was encountered before the EOF; false` indicates an unexpected EOF. */ bool get_bson_cstr(string_t& result) @@ -13196,7 +13189,7 @@ class binary_reader @brief read a C-style string from contiguous input in one step @param[in,out] result the string to append to - @return whether the string was read; if the input has no \x00-byte, nothing + @return whether the string was read; if the input has no \\x00-byte, nothing is read, and @ref get_bson_cstr reports the end of the input */ bool get_bson_cstr_bulk(string_t& result, std::true_type /*bulk*/) @@ -17906,7 +17899,7 @@ This class implements a both iterators (iterator and const_iterator) for the been set (e.g., by a constructor or a copy assignment). If the iterator is default-constructed, it is *uninitialized* and most methods are undefined. **The library uses assertions to detect calls on uninitialized iterators.** -@requirement REQ-JSON-01 The class satisfies the following concept requirements: +This class satisfies the following concept requirements (REQ-JSON-01): - [BidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator): The iterator that can be moved can be moved in both directions (i.e. @@ -18670,7 +18663,7 @@ namespace detail iterator (to create @ref reverse_iterator) and @ref const_iterator (to create @ref const_reverse_iterator). -@requirement REQ-JSON-02 The class satisfies the following concept requirements: +This class satisfies the following concept requirements (REQ-JSON-02): - [BidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator): The iterator that can be moved can be moved in both directions (i.e. @@ -19149,7 +19142,7 @@ class json_pointer /*! @brief create and return a reference to the pointed to value - @complexity Linear in the number of reference tokens. + Complexity: Linear in the number of reference tokens. @throw parse_error.106 if an array index begins with '0' @throw parse_error.109 if array index is not a number @@ -19236,7 +19229,7 @@ class json_pointer @return reference to the JSON value pointed to by the JSON pointer - @complexity Linear in the length of the JSON pointer. + Complexity: Linear in the length of the JSON pointer. @throw parse_error.106 if an array index begins with '0' @throw parse_error.109 if an array index was not a number @@ -24218,7 +24211,7 @@ class serializer @param[in] ichar indentation character to use @param[in] pretty_print_ whether the output shall be pretty-printed @param[in] ensure_ascii_ If @a ensure_ascii_ is true, all non-ASCII - characters in the output are escaped with `\uXXXX` sequences, and the + characters in the output are escaped with `\\uXXXX` sequences, and the result consists of ASCII characters only. @param[in] indent_step_ the indent level @param[in] error_handler_ how to react on decoding errors @@ -24923,7 +24916,7 @@ class serializer @param[in] s the string to escape - @complexity Linear in the length of string @a s. + Complexity: Linear in the length of string @a s. */ void dump_escaped(const string_t& s) { @@ -25441,7 +25434,7 @@ class serializer } /*! - * @brief write a lowercase "\uXXXX" escape sequence into @a string_buffer + * @brief write a lowercase "\\uXXXX" escape sequence into @a string_buffer * * Branch-free replacement for `snprintf(buf, 7, "\\u%04x", codeunit)` in the * string escaping hot path. It writes exactly six characters ('\\', 'u' and @@ -25801,7 +25794,7 @@ class serializer /// whether to pretty-print the output const bool pretty_print; - /// whether to escape non-ASCII characters with \uXXXX sequences + /// whether to escape non-ASCII characters with \\uXXXX sequences const bool ensure_ascii; /// the indent level @@ -28500,12 +28493,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @throw what @ref json_serializer `from_json()` method throws - @liveexample{The example below shows several conversions from JSON values + The example below shows several conversions from JSON values to other types. There a few things to note: (1) Floating-point numbers can - be converted to integers\, (2) A JSON array can be converted to a standard - `std::vector`\, (3) A JSON object can be converted to C++ - associative containers such as `std::unordered_map`.,get__ValueType_const} + be converted to integers, (2) A JSON array can be converted to a standard + `std::vector`, (3) A JSON object can be converted to C++ + associative containers such as `std::unordered_map`. @since version 2.1.0 */ @@ -28572,7 +28565,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @return a copy of *this, converted into @a BasicJsonType - @complexity Depending on the implementation of the called `from_json()` + Complexity: Depending on the implementation of the called `from_json()` method. @since version 3.2.0 @@ -28596,7 +28589,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @return a copy of *this - @complexity Constant. + Complexity: Constant. @since version 2.1.0 */ @@ -28680,12 +28673,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @return pointer to the internally stored JSON value if the requested pointer type @a PointerType fits to the JSON value; `nullptr` otherwise - @complexity Constant. + Complexity: Constant. - @liveexample{The example below shows how pointers to internal values of a + The example below shows how pointers to internal values of a JSON value can be requested. Note that no type conversions are made and a `nullptr` is returned if the value and the requested pointer type does not - match.,get__PointerType} + match. @sa see @ref get_ptr() for explicit pointer-member access @@ -28779,14 +28772,14 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec to the JSON value type (e.g., the JSON value is of type boolean, but a string is requested); see example below - @complexity Linear in the size of the JSON value. + Complexity: Linear in the size of the JSON value. - @liveexample{The example below shows several conversions from JSON values + The example below shows several conversions from JSON values to other types. There a few things to note: (1) Floating-point numbers can - be converted to integers\, (2) A JSON array can be converted to a standard - `std::vector`\, (3) A JSON object can be converted to C++ - associative containers such as `std::unordered_map`.,operator__ValueType} + be converted to integers, (2) A JSON array can be converted to a standard + `std::vector`, (3) A JSON object can be converted to C++ + associative containers such as `std::unordered_map`. @since version 1.0.0 */ @@ -31168,6 +31161,19 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// @deprecated This function is deprecated since 3.8.0 and will be removed in /// version 4.0.0 of the library. Please use /// sax_parse(ptr, ptr + len) instead. + // + // Clang reports "declaration is marked with '@deprecated' command but does + // not have a deprecation attribute" for this overload even though + // JSON_HEDLEY_DEPRECATED_FOR below does expand to __attribute__((deprecated)); + // isolated reproductions of this exact declaration shape (doc comment, + // template<>, two stacked __attribute__ lines, an overload set of the same + // name) do not reproduce it, so this looks like a Clang comment/declaration + // association quirk specific to this overload within basic_json, not a + // genuine documentation bug. See #5725 item 2. +#if defined(__clang__) +#pragma clang diagnostic push +#pragma clang diagnostic ignored "-Wdocumentation-deprecated-sync" +#endif template JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...)) JSON_HEDLEY_NON_NULL(2) @@ -31184,6 +31190,9 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec // NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg) : detail::binary_reader(std::move(ia), format).sax_parse(format, sax, strict); } +#if defined(__clang__) +#pragma clang diagnostic pop +#endif #ifndef JSON_NO_IO /// @brief deserialize from stream /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/ @@ -32779,11 +32788,6 @@ struct formatter // NOLINT(cert-dcl58-c -// restore clang diagnostic settings -#if defined(__clang__) - #pragma clang diagnostic pop -#endif - // clean up #undef JSON_ASSERT #undef JSON_INTERNAL_CATCH