From 8c6a71e47c11d22503a87ef1f118668b043df9de Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 2 May 2019 16:46:50 +0100 Subject: [PATCH] Miscellaneous API doc improvements * include/bits/basic_string.h: Fix iterator/index confusion in Doxygen comments. * include/bits/range_access.h: Fix Doxygen warnings. * include/bits/refwrap.h: Do not document implementation details. (ref, cref): Group docs with reference_wrapper. * include/std/fstream: Fix Doxygen markup. * libsupc++/initializer_list (begin, end): Group docs with initializer_list. From-SVN: r270814 --- libstdc++-v3/ChangeLog | 9 +++++++ libstdc++-v3/include/bits/basic_string.h | 33 ++++++++++++------------ libstdc++-v3/include/bits/range_access.h | 6 ++--- libstdc++-v3/include/bits/refwrap.h | 9 +++++-- libstdc++-v3/include/std/fstream | 6 ++--- libstdc++-v3/libsupc++/initializer_list | 2 ++ 6 files changed, 39 insertions(+), 26 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index e56c4f011a3..32d1be1616f 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,14 @@ 2019-05-02 Jonathan Wakely + * include/bits/basic_string.h: Fix iterator/index confusion in + Doxygen comments. + * include/bits/range_access.h: Fix Doxygen warnings. + * include/bits/refwrap.h: Do not document implementation details. + (ref, cref): Group docs with reference_wrapper. + * include/std/fstream: Fix Doxygen markup. + * libsupc++/initializer_list (begin, end): Group docs with + initializer_list. + * doc/doxygen/user.cfg.in: Set MARKDOWN_SUPPORT=YES. * include/bits/unique_lock.h: Fix/improve doxygen markup. diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h index 40ef8758a51..4a6332a8968 100644 --- a/libstdc++-v3/include/bits/basic_string.h +++ b/libstdc++-v3/include/bits/basic_string.h @@ -1625,7 +1625,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Insert value of a string. - * @param __pos1 Iterator referencing location in string to insert at. + * @param __pos1 Position in string to insert at. * @param __str The string to insert. * @return Reference to this string. * @throw std::length_error If new length exceeds @c max_size(). @@ -1642,8 +1642,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Insert a substring. - * @param __pos1 Iterator referencing location in string to insert at. - * @param __str The string to insert. + * @param __pos1 Position in string to insert at. + * @param __str The string to insert. * @param __pos2 Start of characters in str to insert. * @param __n Number of characters to insert. * @return Reference to this string. @@ -1667,7 +1667,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Insert a C substring. - * @param __pos Iterator referencing location in string to insert at. + * @param __pos Position in string to insert at. * @param __s The C string to insert. * @param __n The number of characters to insert. * @return Reference to this string. @@ -1687,7 +1687,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Insert a C string. - * @param __pos Iterator referencing location in string to insert at. + * @param __pos Position in string to insert at. * @param __s The C string to insert. * @return Reference to this string. * @throw std::length_error If new length exceeds @c max_size(). @@ -1754,7 +1754,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 #if __cplusplus >= 201703L /** * @brief Insert a string_view. - * @param __pos Iterator referencing position in string to insert at. + * @param __pos Position in string to insert at. * @param __svt The object convertible to string_view to insert. * @return Reference to this string. */ @@ -1768,10 +1768,9 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /** * @brief Insert a string_view. - * @param __pos Iterator referencing position in string to insert at. - * @param __svt The object convertible to string_view to insert from. - * @param __pos Iterator referencing position in string_view to insert - * from. + * @param __pos1 Position in string to insert at. + * @param __svt The object convertible to string_view to insert from. + * @param __pos2 Start of characters in str to insert. * @param __n The number of characters to insert. * @return Reference to this string. */ @@ -4519,7 +4518,7 @@ _GLIBCXX_END_NAMESPACE_CXX11 /** * @brief Insert value of a string. - * @param __pos1 Iterator referencing location in string to insert at. + * @param __pos1 Position in string to insert at. * @param __str The string to insert. * @return Reference to this string. * @throw std::length_error If new length exceeds @c max_size(). @@ -4535,7 +4534,7 @@ _GLIBCXX_END_NAMESPACE_CXX11 /** * @brief Insert a substring. - * @param __pos1 Iterator referencing location in string to insert at. + * @param __pos1 Position in string to insert at. * @param __str The string to insert. * @param __pos2 Start of characters in str to insert. * @param __n Number of characters to insert. @@ -4560,7 +4559,7 @@ _GLIBCXX_END_NAMESPACE_CXX11 /** * @brief Insert a C substring. - * @param __pos Iterator referencing location in string to insert at. + * @param __pos Position in string to insert at. * @param __s The C string to insert. * @param __n The number of characters to insert. * @return Reference to this string. @@ -4579,7 +4578,7 @@ _GLIBCXX_END_NAMESPACE_CXX11 /** * @brief Insert a C string. - * @param __pos Iterator referencing location in string to insert at. + * @param __pos Position in string to insert at. * @param __s The C string to insert. * @return Reference to this string. * @throw std::length_error If new length exceeds @c max_size(). @@ -4646,7 +4645,7 @@ _GLIBCXX_END_NAMESPACE_CXX11 #if __cplusplus >= 201703L /** * @brief Insert a string_view. - * @param __pos Iterator referencing position in string to insert at. + * @param __pos Position in string to insert at. * @param __svt The object convertible to string_view to insert. * @return Reference to this string. */ @@ -4660,9 +4659,9 @@ _GLIBCXX_END_NAMESPACE_CXX11 /** * @brief Insert a string_view. - * @param __pos Iterator referencing position in string to insert at. + * @param __pos Position in string to insert at. * @param __svt The object convertible to string_view to insert from. - * @param __pos Iterator referencing position in string_view to insert + * @param __pos Position in string_view to insert * from. * @param __n The number of characters to insert. * @return Reference to this string. diff --git a/libstdc++-v3/include/bits/range_access.h b/libstdc++-v3/include/bits/range_access.h index dfdcd8e7207..d1e74711433 100644 --- a/libstdc++-v3/include/bits/range_access.h +++ b/libstdc++-v3/include/bits/range_access.h @@ -245,11 +245,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Return the size of an array. - * @param __array Array. */ template constexpr size_t - size(const _Tp (&/*__array*/)[_Nm]) noexcept + size(const _Tp (&)[_Nm]) noexcept { return _Nm; } /** @@ -264,11 +263,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Return whether an array is empty (always false). - * @param __array Container. */ template [[nodiscard]] constexpr bool - empty(const _Tp (&/*__array*/)[_Nm]) noexcept + empty(const _Tp (&)[_Nm]) noexcept { return false; } /** diff --git a/libstdc++-v3/include/bits/refwrap.h b/libstdc++-v3/include/bits/refwrap.h index 6b4335a22ac..e810988cd4f 100644 --- a/libstdc++-v3/include/bits/refwrap.h +++ b/libstdc++-v3/include/bits/refwrap.h @@ -44,6 +44,8 @@ namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION + /// @cond undocumented + /** * Derives from @c unary_function or @c binary_function, or perhaps * nothing, depending on the number of arguments provided. The @@ -282,10 +284,11 @@ _GLIBCXX_MEM_FN_TRAITS(&& noexcept, false_type, true_type) }; #endif // ! C++20 + /// @endcond + /** * @brief Primary class template for reference_wrapper. * @ingroup functors - * @{ */ template class reference_wrapper @@ -345,6 +348,8 @@ _GLIBCXX_MEM_FN_TRAITS(&& noexcept, false_type, true_type) reference_wrapper(_Tp&) -> reference_wrapper<_Tp>; #endif + /// @relates reference_wrapper @{ + /// Denotes a reference should be taken to a variable. template inline reference_wrapper<_Tp> @@ -375,7 +380,7 @@ _GLIBCXX_MEM_FN_TRAITS(&& noexcept, false_type, true_type) cref(reference_wrapper<_Tp> __t) noexcept { return { __t.get() }; } - // @} group functors + // @} _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/std/fstream b/libstdc++-v3/include/std/fstream index 419cb92c96c..5ccaf3e4ec5 100644 --- a/libstdc++-v3/include/std/fstream +++ b/libstdc++-v3/include/std/fstream @@ -569,7 +569,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus >= 201703L /** - * @param Create an input file stream. + * @brief Create an input file stream. * @param __s filesystem::path specifying the filename. * @param __mode Open file in specified mode (see std::ios_base). * @@ -832,7 +832,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus >= 201703L /** - * @param Create an output file stream. + * @brief Create an output file stream. * @param __s filesystem::path specifying the filename. * @param __mode Open file in specified mode (see std::ios_base). * @@ -1090,7 +1090,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus >= 201703L /** - * @param Create an input/output file stream. + * @brief Create an input/output file stream. * @param __s filesystem::path specifying the filename. * @param __mode Open file in specified mode (see std::ios_base). */ diff --git a/libstdc++-v3/libsupc++/initializer_list b/libstdc++-v3/libsupc++/initializer_list index 8086bd30a2d..ab8ace943cd 100644 --- a/libstdc++-v3/libsupc++/initializer_list +++ b/libstdc++-v3/libsupc++/initializer_list @@ -83,6 +83,7 @@ namespace std * @brief Return an iterator pointing to the first element of * the initializer_list. * @param __ils Initializer list. + * @relates initializer_list */ template constexpr const _Tp* @@ -93,6 +94,7 @@ namespace std * @brief Return an iterator pointing to one past the last element * of the initializer_list. * @param __ils Initializer list. + * @relates initializer_list */ template constexpr const _Tp*