Improve docs for mutexes

* include/bits/unique_lock.h: Fix/improve doxygen markup.
	* include/std/mutex: Likewise.
	* include/std/shared_mutex: Likewise.

From-SVN: r270812

libstdc++-v3/ChangeLog

@@ -1,5 +1,9 @@
 2019-05-02  Jonathan Wakely  <jwakely@redhat.com>
 
+	* include/bits/unique_lock.h: Fix/improve doxygen markup.
+	* include/std/mutex: Likewise.
+	* include/std/shared_mutex: Likewise.
+
 	* include/bits/fs_dir.h: Fix/improve doxygen markup.
 	* include/bits/fs_fwd.h: Likewise.
 	* include/bits/fs_ops.h: Likewise.

libstdc++-v3/include/bits/unique_lock.h

@@ -43,17 +43,14 @@ namespace std _GLIBCXX_VISIBILITY(default)
 {
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
-  /**
-   * @ingroup mutexes
-   * @{
-   */
-
   /** @brief A movable scoped lock type.
    *
    * A unique_lock controls mutex ownership within a scope. Ownership of the
    * mutex can be delayed until after construction and can be transferred
    * to another unique_lock by move construction or move assignment. If a
    * mutex lock is owned when the destructor runs ownership will be released.
+   *
+   * @ingroup mutexes
    */
   template<typename _Mutex>
     class unique_lock
@@ -232,12 +229,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     };
 
   /// Swap overload for unique_lock objects.
+  /// @relates unique_lock
   template<typename _Mutex>
     inline void
     swap(unique_lock<_Mutex>& __x, unique_lock<_Mutex>& __y) noexcept
     { __x.swap(__y); }
 
-  // @} group mutexes
 _GLIBCXX_END_NAMESPACE_VERSION
 } // namespace
 

libstdc++-v3/include/std/mutex

@@ -55,7 +55,7 @@ namespace std _GLIBCXX_VISIBILITY(default)
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
-   * @ingroup mutexes
+   * @addtogroup mutexes
    * @{
    */
 
@@ -463,6 +463,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
 #endif // _GLIBCXX_HAS_GTHREADS
 
+  /// @cond undocumented
   template<typename _Lock>
     inline unique_lock<_Lock>
     __try_to_lock(_Lock& __l)
@@ -504,6 +505,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
             }
 	}
     };
+  /// @endcond
 
   /** @brief Generic try_lock.
    *  @param __l1 Meets Lockable requirements (try_lock() may throw).
@@ -624,7 +626,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif // C++17
 
 #ifdef _GLIBCXX_HAS_GTHREADS
-  /// once_flag
+  /// Flag type used by std::call_once
   struct once_flag
   {
   private:
@@ -645,6 +647,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       call_once(once_flag& __once, _Callable&& __f, _Args&&... __args);
   };
 
+  /// @cond undocumented
 #ifdef _GLIBCXX_HAVE_TLS
   extern __thread void* __once_callable;
   extern __thread void (*__once_call)();
@@ -659,8 +662,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
 
   extern "C" void __once_proxy(void);
+  /// @endcond
 
-  /// call_once
+  /// Invoke a callable and synchronize with other calls using the same flag
   template<typename _Callable, typename... _Args>
     void
     call_once(once_flag& __once, _Callable&& __f, _Args&&... __args)

libstdc++-v3/include/std/shared_mutex

@@ -42,7 +42,7 @@ namespace std _GLIBCXX_VISIBILITY(default)
 _GLIBCXX_BEGIN_NAMESPACE_VERSION
 
   /**
-   * @ingroup mutexes
+   * @addtogroup mutexes
    * @{
    */
 
@@ -56,6 +56,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #define __cpp_lib_shared_timed_mutex 201402
   class shared_timed_mutex;
 
+  /// @cond undocumented
+
 #if _GLIBCXX_USE_PTHREAD_RWLOCK_T
 #ifdef __gthrw
 #define _GLIBCXX_GTHRW(name) \
@@ -395,6 +397,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     }
   };
 #endif
+  /// @endcond
 
 #if __cplusplus > 201402L
   /// The standard shared mutex type.
@@ -432,11 +435,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   };
 #endif // C++17
 
+  /// @cond undocumented
 #if _GLIBCXX_USE_PTHREAD_RWLOCK_T && _GTHREAD_USE_MUTEX_TIMEDLOCK
   using __shared_timed_mutex_base = __shared_mutex_pthread;
 #else
   using __shared_timed_mutex_base = __shared_mutex_cv;
 #endif
+  /// @endcond
 
   /// The standard shared timed mutex type.
   class shared_timed_mutex
@@ -754,6 +759,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     };
 
   /// Swap specialization for shared_lock
+  /// @relates shared_mutex
   template<typename _Mutex>
     void
     swap(shared_lock<_Mutex>& __x, shared_lock<_Mutex>& __y) noexcept