From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id EE4B33858006; Mon, 18 Mar 2024 14:08:24 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org EE4B33858006 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1710770904; bh=8WDB7uPTW7mCDgd5EHo+bOcPXwT6ySk4+mxC18hAREo=; h=From:To:Subject:Date:From; b=LYI4g1YenlDJHOOtN7qQLK1Cea/z/CAsLQBxQyJlwkfWwBD5pWvVum+tI6L2Adb5j TQceaEN1Sjk40Cle54wqYCrRp2HxJGjo7A+Zfsh1C6vAaw4rKYDmRcHigDOvWrytro Cys5PLMppjZ5qS43+Jyq5M7bGX/CWhEjxmCyHd2w= MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r12-10278] libstdc++: Add @headerfile and @since to doxygen comments [PR40380] X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/releases/gcc-12 X-Git-Oldrev: 5558c3f14517d7471b0e3e2a0169a49f23a8b98a X-Git-Newrev: afefe951acd8bae13be0e1b700262316254ce935 Message-Id: <20240318140824.EE4B33858006@sourceware.org> Date: Mon, 18 Mar 2024 14:08:24 +0000 (GMT) List-Id: https://gcc.gnu.org/g:afefe951acd8bae13be0e1b700262316254ce935 commit r12-10278-gafefe951acd8bae13be0e1b700262316254ce935 Author: Jonathan Wakely Date: Wed Apr 26 22:48:35 2023 +0100 libstdc++: Add @headerfile and @since to doxygen comments [PR40380] libstdc++-v3/ChangeLog: PR libstdc++/40380 * include/bits/basic_string.h: Improve doxygen comments. * include/bits/cow_string.h: Likewise. * include/bits/forward_list.h: Likewise. * include/bits/fs_dir.h: Likewise. * include/bits/fs_path.h: Likewise. * include/bits/quoted_string.h: Likewise. * include/bits/stl_bvector.h: Likewise. * include/bits/stl_map.h: Likewise. * include/bits/stl_multimap.h: Likewise. * include/bits/stl_multiset.h: Likewise. * include/bits/stl_set.h: Likewise. * include/bits/stl_vector.h: Likewise. * include/bits/unordered_map.h: Likewise. * include/bits/unordered_set.h: Likewise. * include/std/filesystem: Likewise. * include/std/iomanip: Likewise. (cherry picked from commit 865869dc6943eb5dee855bc1ea88b09b7dabc641) Diff: --- libstdc++-v3/include/bits/basic_string.h | 2 ++ libstdc++-v3/include/bits/cow_string.h | 2 ++ libstdc++-v3/include/bits/forward_list.h | 2 ++ libstdc++-v3/include/bits/fs_dir.h | 35 +++++++++++++++++++++++++++++-- libstdc++-v3/include/bits/fs_path.h | 18 +++++++++++++++- libstdc++-v3/include/bits/quoted_string.h | 12 +++++++---- libstdc++-v3/include/bits/stl_bvector.h | 2 ++ libstdc++-v3/include/bits/stl_map.h | 2 ++ libstdc++-v3/include/bits/stl_multimap.h | 2 ++ libstdc++-v3/include/bits/stl_multiset.h | 3 ++- libstdc++-v3/include/bits/stl_set.h | 2 ++ libstdc++-v3/include/bits/stl_vector.h | 2 ++ libstdc++-v3/include/bits/unordered_map.h | 4 ++++ libstdc++-v3/include/bits/unordered_set.h | 4 ++++ libstdc++-v3/include/std/filesystem | 2 ++ libstdc++-v3/include/std/iomanip | 1 + 16 files changed, 87 insertions(+), 8 deletions(-) diff --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h index 3f38f20dd18..e02b1b97c5c 100644 --- a/libstdc++-v3/include/bits/basic_string.h +++ b/libstdc++-v3/include/bits/basic_string.h @@ -69,6 +69,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 * * @ingroup strings * @ingroup sequences + * @headerfile string + * @since C++98 * * @tparam _CharT Type of character * @tparam _Traits Traits for character type, defaults to diff --git a/libstdc++-v3/include/bits/cow_string.h b/libstdc++-v3/include/bits/cow_string.h index 87720690cd3..6dd23883429 100644 --- a/libstdc++-v3/include/bits/cow_string.h +++ b/libstdc++-v3/include/bits/cow_string.h @@ -54,6 +54,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * * @ingroup strings * @ingroup sequences + * @headerfile string + * @since C++98 * * @tparam _CharT Type of character * @tparam _Traits Traits for character type, defaults to diff --git a/libstdc++-v3/include/bits/forward_list.h b/libstdc++-v3/include/bits/forward_list.h index bbb1740296b..69725a255e8 100644 --- a/libstdc++-v3/include/bits/forward_list.h +++ b/libstdc++-v3/include/bits/forward_list.h @@ -406,6 +406,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * and fixed time insertion/deletion at any point in the sequence. * * @ingroup sequences + * @headerfile forward_list + * @since C++11 * * @tparam _Tp Type of element. * @tparam _Alloc Allocator type, defaults to allocator<_Tp>. diff --git a/libstdc++-v3/include/bits/fs_dir.h b/libstdc++-v3/include/bits/fs_dir.h index 84e8e8984e8..968a5cf52a0 100644 --- a/libstdc++-v3/include/bits/fs_dir.h +++ b/libstdc++-v3/include/bits/fs_dir.h @@ -52,6 +52,10 @@ namespace filesystem */ /// Information about a file's type and permissions. + /** + * @headerfile filesystem + * @since C++17 + */ class file_status { public: @@ -94,6 +98,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 class recursive_directory_iterator; /// The value type used by directory iterators + /** + * @headerfile filesystem + * @since C++17 + */ class directory_entry { public: @@ -354,7 +362,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 file_type _M_type = file_type::none; }; + /// @cond undocumented + /// Proxy returned by post-increment on directory iterators. + /** + * @headerfile filesystem + * @since C++17 + */ struct __directory_iterator_proxy { const directory_entry& operator*() const& noexcept { return _M_entry; } @@ -370,8 +384,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 directory_entry _M_entry; }; + /// @endcond /// Iterator type for traversing the entries in a single directory. + /** + * @headerfile filesystem + * @since C++17 + */ class directory_iterator { public: @@ -451,7 +470,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 std::__shared_ptr<_Dir> _M_dir; }; - /// @relates std::filesystem::directory_iterator @{ + /** @relates std::filesystem::directory_iterator + * @headerfile filesystem + * @since C++17 + * @{ + */ /** @brief Enable range-based `for` using directory_iterator. * @@ -468,6 +491,10 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 /// @} /// Iterator type for recursively traversing a directory hierarchy. + /** + * @headerfile filesystem + * @since C++17 + */ class recursive_directory_iterator { public: @@ -566,7 +593,11 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 filesystem::remove_all(const path&); }; - /// @relates std::filesystem::recursive_directory_iterator @{ + /** @relates std::filesystem::directory_iterator + * @headerfile filesystem + * @since C++17 + * @{ + */ /** @brief Enable range-based `for` using recursive_directory_iterator. * diff --git a/libstdc++-v3/include/bits/fs_path.h b/libstdc++-v3/include/bits/fs_path.h index 60bfd99995f..e42c040a0b8 100644 --- a/libstdc++-v3/include/bits/fs_path.h +++ b/libstdc++-v3/include/bits/fs_path.h @@ -285,7 +285,11 @@ namespace __detail /// @{ /// A filesystem path - /// @ingroup filesystem + /** + * @ingroup filesystem + * @headerfile filesystem + * @since C++17 + */ class path { public: @@ -743,6 +747,10 @@ namespace __detail /// @} /// Exception type thrown by the Filesystem library + /** + * @headerfile filesystem + * @since C++17 + */ class filesystem_error : public std::system_error { public: @@ -805,6 +813,8 @@ namespace __detail /** Create a path from a UTF-8-encoded sequence of char * * @relates std::filesystem::path + * @headerfile filesystem + * @since C++17 */ template, @@ -828,6 +838,8 @@ namespace __detail /** Create a path from a UTF-8-encoded sequence of char * * @relates std::filesystem::path + * @headerfile filesystem + * @since C++17 */ template, @@ -928,6 +940,10 @@ namespace __detail /// @endcond /// An iterator for the components of a path + /** + * @headerfile filesystem + * @since C++17 + */ class path::iterator { public: diff --git a/libstdc++-v3/include/bits/quoted_string.h b/libstdc++-v3/include/bits/quoted_string.h index fdaaac88c7c..dbb1a9fd083 100644 --- a/libstdc++-v3/include/bits/quoted_string.h +++ b/libstdc++-v3/include/bits/quoted_string.h @@ -85,14 +85,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Inserter for quoted strings. * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 2344 quoted()'s interaction with padding is unclear + * @headerfile iomanip */ template std::basic_ostream<_CharT, _Traits>& operator<<(std::basic_ostream<_CharT, _Traits>& __os, const _Quoted_string& __str) { + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 2344 quoted()'s interaction with padding is unclear std::basic_ostringstream<_CharT, _Traits> __ostr; __ostr << __str._M_delim; for (const _CharT* __c = __str._M_string; *__c; ++__c) @@ -109,14 +110,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Inserter for quoted strings. * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 2344 quoted()'s interaction with padding is unclear + * @headerfile iomanip */ template std::basic_ostream<_CharT, _Traits>& operator<<(std::basic_ostream<_CharT, _Traits>& __os, const _Quoted_string<_String, _CharT>& __str) { + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 2344 quoted()'s interaction with padding is unclear std::basic_ostringstream<_CharT, _Traits> __ostr; __ostr << __str._M_delim; for (auto __c : __str._M_string) @@ -133,6 +135,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** * @brief Extractor for delimited strings. * The left and right delimiters can be different. + * + * @headerfile iomanip */ template std::basic_istream<_CharT, _Traits>& diff --git a/libstdc++-v3/include/bits/stl_bvector.h b/libstdc++-v3/include/bits/stl_bvector.h index d256af40f40..f90d3c47f3d 100644 --- a/libstdc++-v3/include/bits/stl_bvector.h +++ b/libstdc++-v3/include/bits/stl_bvector.h @@ -672,6 +672,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * access to individual elements in any order. * * @ingroup sequences + * @headerfile vector + * @since C++98 * * @tparam _Alloc Allocator type. * diff --git a/libstdc++-v3/include/bits/stl_map.h b/libstdc++-v3/include/bits/stl_map.h index 9c2b0745673..b1ed460af1c 100644 --- a/libstdc++-v3/include/bits/stl_map.h +++ b/libstdc++-v3/include/bits/stl_map.h @@ -76,6 +76,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * retrieved based on a key, in logarithmic time. * * @ingroup associative_containers + * @headerfile map + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. diff --git a/libstdc++-v3/include/bits/stl_multimap.h b/libstdc++-v3/include/bits/stl_multimap.h index f6b08bca3f3..586ec8ba06c 100644 --- a/libstdc++-v3/include/bits/stl_multimap.h +++ b/libstdc++-v3/include/bits/stl_multimap.h @@ -74,6 +74,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * retrieved based on a key, in logarithmic time. * * @ingroup associative_containers + * @headerfile map + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. diff --git a/libstdc++-v3/include/bits/stl_multiset.h b/libstdc++-v3/include/bits/stl_multiset.h index 1fbccd70c3d..023773722a2 100644 --- a/libstdc++-v3/include/bits/stl_multiset.h +++ b/libstdc++-v3/include/bits/stl_multiset.h @@ -74,7 +74,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * in logarithmic time. * * @ingroup associative_containers - * + * @headerfile set + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Compare Comparison function object type, defaults to less<_Key>. diff --git a/libstdc++-v3/include/bits/stl_set.h b/libstdc++-v3/include/bits/stl_set.h index b6c9746f481..ba301bb31ae 100644 --- a/libstdc++-v3/include/bits/stl_set.h +++ b/libstdc++-v3/include/bits/stl_set.h @@ -74,6 +74,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * retrieved in logarithmic time. * * @ingroup associative_containers + * @headerfile set + * @since C++98 * * @tparam _Key Type of key objects. * @tparam _Compare Comparison function object type, defaults to less<_Key>. diff --git a/libstdc++-v3/include/bits/stl_vector.h b/libstdc++-v3/include/bits/stl_vector.h index b4ff3989a5d..977474acd7f 100644 --- a/libstdc++-v3/include/bits/stl_vector.h +++ b/libstdc++-v3/include/bits/stl_vector.h @@ -403,6 +403,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * individual elements in any order. * * @ingroup sequences + * @headerfile vector + * @since C++98 * * @tparam _Tp Type of element. * @tparam _Alloc Allocator type, defaults to allocator<_Tp>. diff --git a/libstdc++-v3/include/bits/unordered_map.h b/libstdc++-v3/include/bits/unordered_map.h index d5edfde8caf..90cfa874756 100644 --- a/libstdc++-v3/include/bits/unordered_map.h +++ b/libstdc++-v3/include/bits/unordered_map.h @@ -78,6 +78,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * with the keys. * * @ingroup unordered_associative_containers + * @headerfile unordered_map + * @since C++11 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. @@ -1221,6 +1223,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * values of another type with the keys. * * @ingroup unordered_associative_containers + * @headerfile unordered_map + * @since C++11 * * @tparam _Key Type of key objects. * @tparam _Tp Type of mapped objects. diff --git a/libstdc++-v3/include/bits/unordered_set.h b/libstdc++-v3/include/bits/unordered_set.h index d2fa2c51171..157c11e6087 100644 --- a/libstdc++-v3/include/bits/unordered_set.h +++ b/libstdc++-v3/include/bits/unordered_set.h @@ -75,6 +75,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * the elements themselves. * * @ingroup unordered_associative_containers + * @headerfile unordered_set + * @since C++11 * * @tparam _Value Type of key objects. * @tparam _Hash Hashing function object type, defaults to hash<_Value>. @@ -943,6 +945,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER * elements' keys are the elements themselves. * * @ingroup unordered_associative_containers + * @headerfile unordered_set + * @since C++11 * * @tparam _Value Type of key objects. * @tparam _Hash Hashing function object type, defaults to hash<_Value>. diff --git a/libstdc++-v3/include/std/filesystem b/libstdc++-v3/include/std/filesystem index dd112a254ad..1e0313597c0 100644 --- a/libstdc++-v3/include/std/filesystem +++ b/libstdc++-v3/include/std/filesystem @@ -39,6 +39,8 @@ * * Utilities for performing operations on file systems and their components, * such as paths, regular files, and directories. + * + * @since C++17 */ #include diff --git a/libstdc++-v3/include/std/iomanip b/libstdc++-v3/include/std/iomanip index 53716813993..5aba3d418b6 100644 --- a/libstdc++-v3/include/std/iomanip +++ b/libstdc++-v3/include/std/iomanip @@ -455,6 +455,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @param __string String to quote. * @param __delim Character to quote string with. * @param __escape Escape character to escape itself or quote character. + * @since C++14 */ template inline auto