[committed 12/12] libstdc++: Improve doxygen docs for <mutex>

[Jonathan Wakely <jwakely@redhat.com>]

Tested powerpc64le-linux, pushed to trunk.

-- >8 --

libstdc++-v3/ChangeLog:

	* doc/doxygen/user.cfg.in (PREDEFINED): Define
	_GTHREAD_USE_MUTEX_TIMEDLOCK macro.
	* include/bits/std_mutex.h (mutex, lock_guard): Use @since and
	@headerfile.
	* include/bits/unique_lock.h (unique_lock): Likewise.
	* include/std/mutex (recursive_mutex, timed_mutex)
	(recursive_timed_mutex, scoped_lock): Likewise.
---
 libstdc++-v3/doc/doxygen/user.cfg.in    |  1 +
 libstdc++-v3/include/bits/std_mutex.h   | 21 +++++++++++++-
 libstdc++-v3/include/bits/unique_lock.h |  2 ++
 libstdc++-v3/include/std/mutex          | 38 +++++++++++++++++++++++--
 4 files changed, 58 insertions(+), 4 deletions(-)

diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in
index 4d21968cc57..c034b864928 100644
--- a/libstdc++-v3/doc/doxygen/user.cfg.in
+++ b/libstdc++-v3/doc/doxygen/user.cfg.in
@@ -2325,6 +2325,7 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = __cplusplus=202002L \
                          __GTHREADS \
                          _GLIBCXX_HAS_GTHREADS \
+                         _GTHREAD_USE_MUTEX_TIMEDLOCK \
                          _GLIBCXX_HAVE_TLS \
                          _GLIBCXX_INCLUDE_AS_CXX11 \
                          "_GLIBCXX_PURE= " \
diff --git a/libstdc++-v3/include/bits/std_mutex.h b/libstdc++-v3/include/bits/std_mutex.h
index d3a1d5eaec9..b22e0e12793 100644
--- a/libstdc++-v3/include/bits/std_mutex.h
+++ b/libstdc++-v3/include/bits/std_mutex.h
@@ -53,6 +53,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    */
 
 #ifdef _GLIBCXX_HAS_GTHREADS
+  /// @cond undocumented
+
   // Common base class for std::mutex and std::timed_mutex
   class __mutex_base
   {
@@ -78,8 +80,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     __mutex_base(const __mutex_base&) = delete;
     __mutex_base& operator=(const __mutex_base&) = delete;
   };
+  /// @endcond
 
-  /// The standard mutex type.
+  /** The standard mutex type.
+   *
+   * A simple, non-recursive, non-timed mutex.
+   *
+   * Do not call `lock()` and `unlock()` directly, use a scoped lock type
+   * such as `std::unique_lock`, `std::lock_guard`, or (since C++17)
+   * `std::scoped_lock`.
+   *
+   * @headerfile mutex
+   * @since C++11
+   */
   class mutex : private __mutex_base
   {
   public:
@@ -123,6 +136,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     { return &_M_mutex; }
   };
 
+  /// @cond undocumented
+
   // Implementation details for std::condition_variable
   class __condvar
   {
@@ -192,6 +207,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     __gthread_cond_t _M_cond;
 #endif
   };
+  /// @endcond
 
 #endif // _GLIBCXX_HAS_GTHREADS
 
@@ -218,6 +234,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *
    * A lock_guard controls mutex ownership within a scope, releasing
    * ownership in the destructor.
+   *
+   * @headerfile mutex
+   * @since C++11
    */
   template<typename _Mutex>
     class lock_guard
diff --git a/libstdc++-v3/include/bits/unique_lock.h b/libstdc++-v3/include/bits/unique_lock.h
index 1f1aa15c463..9ed7ba25766 100644
--- a/libstdc++-v3/include/bits/unique_lock.h
+++ b/libstdc++-v3/include/bits/unique_lock.h
@@ -51,7 +51,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    * to another unique_lock by move construction or move assignment. If a
    * mutex lock is owned when the destructor runs ownership will be released.
    *
+   * @headerfile mutex
    * @ingroup mutexes
+   * @since C++11
    */
   template<typename _Mutex>
     class unique_lock
diff --git a/libstdc++-v3/include/std/mutex b/libstdc++-v3/include/std/mutex
index f500818d9c9..b9590bbf276 100644
--- a/libstdc++-v3/include/std/mutex
+++ b/libstdc++-v3/include/std/mutex
@@ -62,6 +62,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    */
 
 #ifdef _GLIBCXX_HAS_GTHREADS
+  /// @cond undocumented
 
   // Common base class for std::recursive_mutex and std::recursive_timed_mutex
   class __recursive_mutex_base
@@ -89,8 +90,17 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     { __gthread_recursive_mutex_destroy(&_M_mutex); }
 #endif
   };
+  /// @endcond
 
-  /// The standard recursive mutex type.
+  /** The standard recursive mutex type.
+   *
+   * A recursive mutex can be locked more than once by the same thread.
+   * Other threads cannot lock the mutex until the owning thread unlocks it
+   * as many times as it was locked.
+   *
+   * @headerfile mutex
+   * @since C++11
+   */
   class recursive_mutex : private __recursive_mutex_base
   {
   public:
@@ -132,6 +142,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   };
 
 #if _GTHREAD_USE_MUTEX_TIMEDLOCK
+  /// @cond undocumented
+
   template<typename _Derived>
     class __timed_mutex_impl
     {
@@ -207,8 +219,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	  return false;
 	}
     };
+  /// @endcond
 
-  /// The standard timed mutex type.
+  /** The standard timed mutex type.
+   *
+   * A non-recursive mutex that supports a timeout when trying to acquire the
+   * lock.
+   *
+   * @headerfile mutex
+   * @since C++11
+   */
   class timed_mutex
   : private __mutex_base, public __timed_mutex_impl<timed_mutex>
   {
@@ -273,7 +293,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
   };
 
-  /// recursive_timed_mutex
+  /** The standard recursive timed mutex type.
+   *
+   * A recursive mutex that supports a timeout when trying to acquire the
+   * lock. A recursive mutex can be locked more than once by the same thread.
+   * Other threads cannot lock the mutex until the owning thread unlocks it
+   * as many times as it was locked.
+   *
+   * @headerfile mutex
+   * @since C++11
+   */
   class recursive_timed_mutex
   : private __recursive_mutex_base,
     public __timed_mutex_impl<recursive_timed_mutex>
@@ -687,6 +716,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
    *
    * A scoped_lock controls mutex ownership within a scope, releasing
    * ownership in the destructor.
+   *
+   * @headerfile mutex
+   * @since C++17
    */
   template<typename... _MutexTypes>
     class scoped_lock
-- 
2.34.1