From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 9BFA2385840D; Thu, 27 Apr 2023 10:29:58 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 9BFA2385840D DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1682591398; bh=nnHl6XDWtxAsjptjuRfy2AEQjHAAIO/qFyYHriYyG6Q=; h=From:To:Subject:Date:From; b=ZEB//tk9DcCHhcvb/ahKc+8xATafzFExj1MMv3sOxY5WJvxIb19kwX+4fd7lSHbKY KM/a6HG3iCdfDiMIJ+3MPrL2PaeAfcxvgsk7EjvcKQ3J/9D3bwG5LVxSN0WjD/xNsf 4pC54MPO+CYT330hwYfjXynNkzKAA7wZWvUff/9M= 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 r14-290] libstdc++: Add @headerfile and @since to doxygen comments [PR40380] X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: f9412cedd6c0e7417b30d9a80d3f45c8746223b4 X-Git-Newrev: 865869dc6943eb5dee855bc1ea88b09b7dabc641 Message-Id: <20230427102958.9BFA2385840D@sourceware.org> Date: Thu, 27 Apr 2023 10:29:58 +0000 (GMT) List-Id: https://gcc.gnu.org/g:865869dc6943eb5dee855bc1ea88b09b7dabc641 commit r14-290-g865869dc6943eb5dee855bc1ea88b09b7dabc641 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. 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 5d040e2897d..8247ee6bdc6 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 b6024365d4f..e5f094fd13e 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 e1e68bd7e04..72b1ef46d14 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 b4adf49e94a..9dd0f896e46 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 0d7bb10c1a0..853c55f0100 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: @@ -736,6 +740,10 @@ namespace __detail /// @} /// Exception type thrown by the Filesystem library + /** + * @headerfile filesystem + * @since C++17 + */ class filesystem_error : public std::system_error { public: @@ -798,6 +806,8 @@ namespace __detail /** Create a path from a UTF-8-encoded sequence of char * * @relates std::filesystem::path + * @headerfile filesystem + * @since C++17 */ template, @@ -822,6 +832,8 @@ namespace __detail /** Create a path from a UTF-8-encoded sequence of char * * @relates std::filesystem::path + * @headerfile filesystem + * @since C++17 */ template, @@ -923,6 +935,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 0644b077d71..ae961a9f254 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 d4d4bfca588..ad462c5933c 100644 --- a/libstdc++-v3/include/bits/stl_bvector.h +++ b/libstdc++-v3/include/bits/stl_bvector.h @@ -684,6 +684,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 e1ce90ea5a4..059916d0a7f 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 6b11d4b3eaf..2efd53d4680 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 8f70f89f7b1..a3998775d94 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 9ce05e0da6e..ddaf7fec738 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 86ff83d1373..acb29396d26 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 f11ccdac07a..2f63bc5f1fa 100644 --- a/libstdc++-v3/include/bits/unordered_map.h +++ b/libstdc++-v3/include/bits/unordered_map.h @@ -83,6 +83,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. @@ -1226,6 +1228,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 68fcfd2ec66..f3b0c078baa 100644 --- a/libstdc++-v3/include/bits/unordered_set.h +++ b/libstdc++-v3/include/bits/unordered_set.h @@ -80,6 +80,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>. @@ -948,6 +950,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 eff2b934f56..d46e842826d 100644 --- a/libstdc++-v3/include/std/filesystem +++ b/libstdc++-v3/include/std/filesystem @@ -41,6 +41,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 a536665566b..5c0fb09a60e 100644 --- a/libstdc++-v3/include/std/iomanip +++ b/libstdc++-v3/include/std/iomanip @@ -457,6 +457,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