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.

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 5d040e2..8247ee6 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 b602436..e5f094f 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 e1e68bd..72b1ef4 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 b4adf49..9dd0f89 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 0d7bb10..853c55f 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<typename _InputIterator,
 	   typename _Require = __detail::_Path2<_InputIterator>,
@@ -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<typename _Source,
 	   typename _Require = __detail::_Path<_Source>,
@@ -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 0644b07..ae961a9 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 d4d4bfc..ad462c5 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 e1ce90e..059916d 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 6b11d4b..2efd53d 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 8f70f89..a399877 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 9ce05e0..ddaf7fe 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 86ff83d..acb2939 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 f11ccda..2f63bc5 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 68fcfd2..f3b0c07 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 eff2b93..d46e842 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 <bits/fs_fwd.h>
diff --git a/libstdc++-v3/include/std/iomanip b/libstdc++-v3/include/std/iomanip
index a5366655..5c0fb09 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<typename _CharT>
     inline auto