[committed] libstdc++: Suppress Doxygen docs for more implementation details

Message ID CACb0b4=DqALg32D0Sf-8dKoEpAgoRjh9bRSHXXJ0ucsu=9Bdkg@mail.gmail.com
State Committed
Headers
Series [committed] libstdc++: Suppress Doxygen docs for more implementation details |

Commit Message

Jonathan Wakely Oct. 21, 2021, 10:23 p.m. UTC
  I messed up the CC to gcc-patches for this ...

---------- Forwarded message ---------
From: Jonathan Wakely via Libstdc++ <libstdc++@gcc.gnu.org>
Date: Thu, 21 Oct 2021 at 22:56
Subject: [committed] libstdc++: Suppress Doxygen docs for more
implementation details
To: <patches@gcc.gnu.org>, <libstdc++@gcc.gnu.org>


Tested x86_64-linux, committed to trunk.

libstdc++-v3/ChangeLog:

        * include/bits/alloc_traits.h: Suppress doxygen documentation.
        * include/bits/allocated_ptr.h: Likewise.
        * include/bits/enable_special_members.h: Likewise.
        * include/bits/hashtable.h: Likewise.
        * include/bits/hashtable_policy.h: Likewise.
        * include/bits/uses_allocator.h: Likewise.
        * include/bits/node_handle.h: Document node handles and suppress
        documentation for protected members.
        * include/std/any: Suppress documentation for implementation
        details.
---
 libstdc++-v3/include/bits/alloc_traits.h      |  4 ++++
 libstdc++-v3/include/bits/allocated_ptr.h     |  2 ++
 .../include/bits/enable_special_members.h     |  2 ++
 libstdc++-v3/include/bits/hashtable.h         |  2 ++
 libstdc++-v3/include/bits/hashtable_policy.h  |  2 ++
 libstdc++-v3/include/bits/node_handle.h       | 20 +++++++++++++++++++
 libstdc++-v3/include/bits/uses_allocator.h    |  2 ++
 libstdc++-v3/include/std/any                  |  8 +++++++-
 8 files changed, 41 insertions(+), 1 deletion(-)

   class any
   {
@@ -337,9 +339,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     }
 #endif

+    /// @cond undocumented
     template<typename _Tp>
       static constexpr bool __is_valid_cast()
       { return __or_<is_reference<_Tp>,
is_copy_constructible<_Tp>>::value; }
+    /// @endcond

   private:
     enum _Op {
@@ -356,8 +360,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     void (*_M_manager)(_Op, const any*, _Arg*);
     _Storage _M_storage;

+    /// @cond undocumented
     template<typename _Tp>
       friend void* __any_caster(const any* __any);
+    /// @endcond

     // Manage in-place contained object.
     template<typename _Tp>
  

Patch

diff --git a/libstdc++-v3/include/bits/alloc_traits.h
b/libstdc++-v3/include/bits/alloc_traits.h
index 05b584f742f..602a90d4d8a 100644
--- a/libstdc++-v3/include/bits/alloc_traits.h
+++ b/libstdc++-v3/include/bits/alloc_traits.h
@@ -45,6 +45,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #if __cplusplus >= 201103L
 #define __cpp_lib_allocator_traits_is_always_equal 201411

+  /// @cond undocumented
   struct __allocator_traits_base
   {
     template<typename _Tp, typename _Up, typename = void>
@@ -77,10 +78,13 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
   template<typename _Alloc, typename _Up>
     using __alloc_rebind
       = typename __allocator_traits_base::template __rebind<_Alloc,
_Up>::type;
+  /// @endcond

   /**
    * @brief  Uniform interface to all allocator types.
+   * @headerfile memory
    * @ingroup allocators
+   * @since C++11
   */
   template<typename _Alloc>
     struct allocator_traits : __allocator_traits_base
diff --git a/libstdc++-v3/include/bits/allocated_ptr.h
b/libstdc++-v3/include/bits/allocated_ptr.h
index 340964eed15..695695f7d11 100644
--- a/libstdc++-v3/include/bits/allocated_ptr.h
+++ b/libstdc++-v3/include/bits/allocated_ptr.h
@@ -40,6 +40,7 @@ 
 namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
+/// @cond undocumented

   /// Non-standard RAII type for managing pointers obtained from
allocators.
   template<typename _Alloc>
@@ -97,6 +98,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
       return { __a, std::allocator_traits<_Alloc>::allocate(__a, 1) };
     }

+/// @endcond
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std

diff --git a/libstdc++-v3/include/bits/enable_special_members.h
b/libstdc++-v3/include/bits/enable_special_members.h
index 8361a063b4d..ac59f72e328 100644
--- a/libstdc++-v3/include/bits/enable_special_members.h
+++ b/libstdc++-v3/include/bits/enable_special_members.h
@@ -37,6 +37,7 @@ 
 namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
+/// @cond undocumented

   struct _Enable_default_constructor_tag
   {
@@ -308,6 +309,7 @@  template<typename _Tag>
     operator=(_Enable_copy_move&&) noexcept                         =
delete;
   };

+/// @endcond
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std

diff --git a/libstdc++-v3/include/bits/hashtable.h
b/libstdc++-v3/include/bits/hashtable.h
index ff8af2201cd..25c45d3ba85 100644
--- a/libstdc++-v3/include/bits/hashtable.h
+++ b/libstdc++-v3/include/bits/hashtable.h
@@ -41,6 +41,7 @@ 
 namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
+/// @cond undocumented

   template<typename _Tp, typename _Hash>
     using __cache_default
@@ -2546,6 +2547,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
       = __enable_if_t<!__or_<is_integral<_Hash>,
__is_allocator<_Hash>>::value>;
 #endif

+/// @endcond
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std

diff --git a/libstdc++-v3/include/bits/hashtable_policy.h
b/libstdc++-v3/include/bits/hashtable_policy.h
index 994c7b61046..8c72043e368 100644
--- a/libstdc++-v3/include/bits/hashtable_policy.h
+++ b/libstdc++-v3/include/bits/hashtable_policy.h
@@ -38,6 +38,7 @@ 
 namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
+/// @cond undocumented

   template<typename _Key, typename _Value, typename _Alloc,
           typename _ExtractKey, typename _Equal,
@@ -1970,6 +1971,7 @@  namespace __detail

  ///@} hashtable-detail
 } // namespace __detail
+/// @endcond
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std

diff --git a/libstdc++-v3/include/bits/node_handle.h
b/libstdc++-v3/include/bits/node_handle.h
index 9a43caf4836..7d8d0dc8cea 100644
--- a/libstdc++-v3/include/bits/node_handle.h
+++ b/libstdc++-v3/include/bits/node_handle.h
@@ -44,6 +44,21 @@  namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION

+  /**
+   * @defgroup node_handles Node handles
+   * @ingroup associative_containers
+   * @since C++17
+   *
+   * The associative containers (`map`, `set`, `multimap` and `multiset`)
+   * support extracting and re-inserting nodes from the container. Those
+   * operations use the container's `node_handle` type, which is an alias
+   * for a `_Node_handle<...>` type. You should always use the container's
+   * `node_handle` type (e.g. `std::set<int>::node_handle`) to refer to
+   * these types, not the non-standard internal `_Node_handle` names.
+   *
+   * @{
+   */
+
   /// Base class for node handle types of maps and sets.
   template<typename _Val, typename _NodeAlloc>
     class _Node_handle_common
@@ -64,6 +79,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION

       [[nodiscard]] bool empty() const noexcept { return _M_ptr ==
nullptr; }

+    /// @cond undocumented
     protected:
       constexpr _Node_handle_common() noexcept : _M_ptr() { }

@@ -214,6 +230,8 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
       template<typename _Key2, typename _Value2, typename _KeyOfValue,
               typename _Compare, typename _ValueAlloc>
        friend class _Rb_tree;
+
+      /// @endcond
     };

   /// Node handle type for maps.
@@ -367,6 +385,8 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
       _NodeHandle      node;
     };

+  /// @}
+
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std

diff --git a/libstdc++-v3/include/bits/uses_allocator.h
b/libstdc++-v3/include/bits/uses_allocator.h
index 358c5713da5..bd4467094a2 100644
--- a/libstdc++-v3/include/bits/uses_allocator.h
+++ b/libstdc++-v3/include/bits/uses_allocator.h
@@ -35,6 +35,7 @@ 
 namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
+/// @cond undocumented

   // This is used for std::experimental::erased_type from Library
Fundamentals.
   struct __erased_type { };
@@ -188,6 +189,7 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
          std::forward<_Args>(__args)...);
     }

+/// @endcond
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace std

diff --git a/libstdc++-v3/include/std/any b/libstdc++-v3/include/std/any
index e3d9d774de4..9c102a58b26 100644
--- a/libstdc++-v3/include/std/any
+++ b/libstdc++-v3/include/std/any
@@ -72,8 +72,10 @@  _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /**
    *  @brief A type-safe container of any type.
    *
-   *  An @c any object's state is either empty or it stores a contained
object
+   *  An `any` object's state is either empty or it stores a contained
object
    *  of CopyConstructible type.
+   *
+   *  @since C++17
    */