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 --git a/libstdc++-v3/include/bits/basic_string.h b/libstdc++-v3/include/bits/basic_string.h
index 3f38f20dd189b1dc293f2a9c595e81c16578bf01..e02b1b97c5cbc05b0810c73016427705f67b77b5 100644 (file)
--- 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 87720690cd33fe65180e63a8c3c683259da610fe..6dd2388342988b1128d85568dd623047d27bccfe 100644 (file)
--- 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 bbb1740296b9d86dc279d543417c60731d1b3a0f..69725a255e8ad60527fca47c4ca330c33afc3272 100644 (file)
--- 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 84e8e8984e8a501ed33848dc2ef1e6cc8405733d..968a5cf52a0561766c42b4eeccda2876e547d661 100644 (file)
--- 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 60bfd99995f583c3fea44b34b05d24f536f90373..e42c040a0b8613943247636c0ba16c2b734172ee 100644 (file)
--- 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 fdaaac88c7cd4650230e7f03d52dcb8ed83cea14..dbb1a9fd083fe56638a0b3ac161aa1fe6107f2b0 100644 (file)
--- 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 d256af40f407b9110f0f21d1c1303448847a966b..f90d3c47f3d3ee929acaf13a0bff6a0b5333e824 100644 (file)
--- 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 9c2b0745673431b4b396ba27982170478838137e..b1ed460af1c3b55a447680131e8cd526511ccb18 100644 (file)
--- 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 f6b08bca3f3ecd6539dae563fcbc289a7f1e5915..586ec8ba06c8ecab72b98d082e4e5fd70ac61d5d 100644 (file)
--- 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 1fbccd70c3db3d6abc666fea20feb1cb0ad99bfd..023773722a2de1bab15ccdd3a3db8c396dbb6ee8 100644 (file)
--- 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 b6c9746f48160361b079d61da2c00a30dcf5fed0..ba301bb31aebcf097a9f7f264f7f4e9d5438d71d 100644 (file)
--- 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 b4ff3989a5dd5555949a212b236ed54be7e670fb..977474acd7f0f98c23570084e4f296e82fba25f3 100644 (file)
--- 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 d5edfde8caf450845f36b035128645aecb1e57d2..90cfa874756fe112bd63199ffa44c1b2d1de3aa6 100644 (file)
--- 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 d2fa2c511712e0afc4b031efbc21344e768e1c10..157c11e6087bb80092d6c1a072b8ff54a6e2b609 100644 (file)
--- 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 dd112a254ad3c47863cba7fb07e81c1176081bab..1e0313597c0b318c7da87dd6d6587f2b60f9658b 100644 (file)
--- 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 537168139936af245b494d0ca9e89d34335b8435..5aba3d418b68f8140985415dc3bc4f3b6d19a31e 100644 (file)
--- 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