From 50912bf83fcaa9215c887f8df5077e2bd20cc4b9 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 30 Sep 2026 17:59:38 +0200 Subject: [PATCH] Fix stale doxygen comments hidden by the -Wdocumentation pragma macro_scope.hpp ignores -Wdocumentation and -Wdocumentation-unknown-command for the whole library, which also hides genuine documentation mistakes: - detail::unescape() documented "@return unescaped string" but returns void and unescapes its argument in place; reworded to "@param[in,out] s string to unescape in place" and dropped the bogus @return. - basic_json::get()'s copy-conversion overload wrote "converted to @tparam ValueType" inside @return, which Doxygen and Clang parse as a second, malformed @tparam; changed to "@a ValueType", matching the two other get() overloads a few lines above that already use it. This narrows the gap the -Wdocumentation pragma needs to cover; fully replacing the Doxygen-only commands it also hides (item 2c) is left for after #5267. Signed-off-by: Niels Lohmann #5725 item 2 --- include/nlohmann/detail/string_escape.hpp | 3 +-- include/nlohmann/json.hpp | 2 +- single_include/nlohmann/json.hpp | 5 ++--- 3 files changed, 4 insertions(+), 6 deletions(-) diff --git a/include/nlohmann/detail/string_escape.hpp b/include/nlohmann/detail/string_escape.hpp index 0d24a56bc..a6489e054 100644 --- a/include/nlohmann/detail/string_escape.hpp +++ b/include/nlohmann/detail/string_escape.hpp @@ -62,8 +62,7 @@ inline StringType escape(const StringType& s) /*! * @brief string unescaping as described in RFC 6901 (Sect. 4) - * @param[in] s string to unescape - * @return unescaped string + * @param[in,out] s string to unescape in place * * Note the order of escaping "~1" to "/" and "~0" to "~" is important. * diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 0bf165748..390d9db77 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -2481,7 +2481,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @tparam ValueTypeCV the provided value type @tparam ValueType the returned value type - @return copy of the JSON value, converted to @tparam ValueType if necessary + @return copy of the JSON value, converted to @a ValueType if necessary @throw what @ref json_serializer `from_json()` method throws if conversion is required diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index a7b129cce..129e7d70f 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -3552,8 +3552,7 @@ inline StringType escape(const StringType& s) /*! * @brief string unescaping as described in RFC 6901 (Sect. 4) - * @param[in] s string to unescape - * @return unescaped string + * @param[in,out] s string to unescape in place * * Note the order of escaping "~1" to "/" and "~0" to "~" is important. * @@ -28567,7 +28566,7 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec @tparam ValueTypeCV the provided value type @tparam ValueType the returned value type - @return copy of the JSON value, converted to @tparam ValueType if necessary + @return copy of the JSON value, converted to @a ValueType if necessary @throw what @ref json_serializer `from_json()` method throws if conversion is required