[gcc r12-10278] libstdc++: Add @headerfile and @since to doxygen comments [PR40380]
Jonathan Wakely
redi@gcc.gnu.org
Mon Mar 18 14:08:24 GMT 2024
https://gcc.gnu.org/g:afefe951acd8bae13be0e1b700262316254ce935
commit r12-10278-gafefe951acd8bae13be0e1b700262316254ce935
Author: Jonathan Wakely <jwakely@redhat.com>
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<typename _InputIterator,
typename _Require = __detail::_Path2<_InputIterator>,
@@ -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<typename _Source,
typename _Require = __detail::_Path<_Source>,
@@ -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<typename _CharT, typename _Traits>
std::basic_ostream<_CharT, _Traits>&
operator<<(std::basic_ostream<_CharT, _Traits>& __os,
const _Quoted_string<const _CharT*, _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 (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<typename _CharT, typename _Traits, typename _String>
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<typename _CharT, typename _Traits, typename _Alloc>
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 <bits/fs_fwd.h>
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<typename _CharT>
inline auto
More information about the Libstdc++-cvs
mailing list