Improve generated libstdc++ API docs

	* doc/doxygen/user.cfg.in: Use EXTENSION_MAPPING tag. Add new headers
	to INPUT. Remove obsolete XML_SCHEMA and XML_DTD tags. Update
	PREDEFINED macros. Set BRIEF_MEMBER_DESC for man-pages.
	* include/backward/strstream: Correct @file comment.
	* include/bits/forward_list.h: Improve Doxygen comments.
	* include/bits/locale_facets_nonio.h: Likewise.
	* include/bits/mutex.h: Likewise.
	* include/bits/shared_ptr.h: Likewise.
	* include/bits/stl_deque.h: Likewise.
	* include/debug/vector (_Safe_vector): Add @brief section to comment.
	* include/experimental/bits/fs_dir.h: Correct @file comment.
	* include/experimental/bits/fs_fwd.h: Likewise.
	* include/experimental/bits/fs_ops.h: Likewise.
	* include/experimental/bits/fs_path.h: Likewise.
	* include/experimental/bits/string_view.tcc: Likewise.
	* include/experimental/optional: Document experimental status.
	* include/experimental/string_view: Correct @file comment.
	* include/ext/pb_ds/detail/bin_search_tree_/traits.hpp: Reduce
	whitespace to avoid Doxygen bug.
	* include/std/bitset: Remove redundant @class Doxygen command. Add
	parentheses to avoid Doxygen bug.
	* include/std/mutex: Improve Doxygen comments.
	* include/tr2/dynamic_bitset: Add missing @param documentation.
	* scripts/run_doxygen: Rename man pages for std::experimental types.

From-SVN: r231512

libstdc++-v3/ChangeLog

+2015-12-10  Jonathan Wakely  <jwakely@redhat.com>
+
+	* doc/doxygen/user.cfg.in: Use EXTENSION_MAPPING tag. Add new headers
+	to INPUT. Remove obsolete XML_SCHEMA and XML_DTD tags. Update
+	PREDEFINED macros. Set BRIEF_MEMBER_DESC for man-pages.
+	* include/backward/strstream: Correct @file comment.
+	* include/bits/forward_list.h: Improve Doxygen comments.
+	* include/bits/locale_facets_nonio.h: Likewise.
+	* include/bits/mutex.h: Likewise.
+	* include/bits/shared_ptr.h: Likewise.
+	* include/bits/stl_deque.h: Likewise.
+	* include/debug/vector (_Safe_vector): Add @brief section to comment.
+	* include/experimental/bits/fs_dir.h: Correct @file comment.
+	* include/experimental/bits/fs_fwd.h: Likewise.
+	* include/experimental/bits/fs_ops.h: Likewise.
+	* include/experimental/bits/fs_path.h: Likewise.
+	* include/experimental/bits/string_view.tcc: Likewise.
+	* include/experimental/optional: Document experimental status.
+	* include/experimental/string_view: Correct @file comment.
+	* include/ext/pb_ds/detail/bin_search_tree_/traits.hpp: Reduce
+	whitespace to avoid Doxygen bug.
+	* include/std/bitset: Remove redundant @class Doxygen command. Add
+	parentheses to avoid Doxygen bug.
+	* include/std/mutex: Improve Doxygen comments.
+	* include/tr2/dynamic_bitset: Add missing @param documentation.
+	* scripts/run_doxygen: Rename man pages for std::experimental types.
+
 2015-12-04  Jonathan Wakely  <jwakely@redhat.com>
 
 	PR libstdc++/57060

libstdc++-v3/doc/doxygen/user.cfg.in

@@ -90,7 +90,7 @@ OUTPUT_LANGUAGE        = English
 # documentation (similar to Javadoc). Set to NO to disable this.
 # The default value is: YES.
 
-BRIEF_MEMBER_DESC      = NO
+BRIEF_MEMBER_DESC      = @do_man@
 
 # If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief
 # description of a member or function before the detailed description
@@ -272,7 +272,7 @@ OPTIMIZE_OUTPUT_VHDL   = NO
 # Note that for custom extensions you also need to set FILE_PATTERNS otherwise
 # the files are not read by doxygen.
 
-EXTENSION_MAPPING      =
+EXTENSION_MAPPING      = no_extension=C++ .h=C++ .tcc=C++ .hpp=C++
 
 # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments
 # according to the Markdown format, which allows for more readable
@@ -757,6 +757,7 @@ INPUT                  = @srcdir@/doc/doxygen/doxygroups.cc \
                          include/bitset \
                          include/chrono \
                          include/complex \
+                         include/codecvt \
                          include/condition_variable \
                          include/deque \
                          include/forward_list \
@@ -812,6 +813,7 @@ INPUT                  = @srcdir@/doc/doxygen/doxygroups.cc \
                          include/cmath \
                          include/csetjmp \
                          include/csignal \
+                         include/cstdalign \
                          include/cstdarg \
                          include/cstdbool \
                          include/cstddef \
@@ -822,6 +824,7 @@ INPUT                  = @srcdir@/doc/doxygen/doxygroups.cc \
                          include/ctgmath \
                          include/ctime \
                          include/cwchar \
+                         include/cuchar \
                          include/cwctype \
                          include/ \
                          include/bits \
@@ -831,6 +834,7 @@ INPUT                  = @srcdir@/doc/doxygen/doxygroups.cc \
                          include/backward/hash_set \
                          include/backward/strstream \
                          include/debug \
+                         include/debug/array \
                          include/debug/bitset \
                          include/debug/deque \
                          include/debug/forward_list \
@@ -853,6 +857,7 @@ INPUT                  = @srcdir@/doc/doxygen/doxygroups.cc \
                          include/profile/unordered_set \
                          include/profile/vector \
                          include/ext/algorithm \
+                         include/ext/cmath \
                          include/ext/functional \
                          include/ext/iterator \
                          include/ext/memory \
@@ -886,9 +891,36 @@ INPUT                  = @srcdir@/doc/doxygen/doxygroups.cc \
                          include/tr2/ratio \
                          include/tr2/type_traits \
                          include/decimal/decimal \
+                         include/experimental/bits \
+                         include/experimental/algorithm \
                          include/experimental/any \
+                         include/experimental/array \
+                         include/experimental/chrono \
+                         include/experimental/deque \
+                         include/experimental/filesystem \
+                         include/experimental/forward_list \
+                         include/experimental/functional \
+                         include/experimental/iterator \
+                         include/experimental/list \
+                         include/experimental/map \
+                         include/experimental/memory \
+                         include/experimental/memory_resource \
+                         include/experimental/numeric \
                          include/experimental/optional \
+                         include/experimental/propagate_const \
+                         include/experimental/random \
+                         include/experimental/ratio \
+                         include/experimental/regex \
+                         include/experimental/set \
+                         include/experimental/string \
                          include/experimental/string_view \
+                         include/experimental/system_error \
+                         include/experimental/tuple \
+                         include/experimental/type_traits \
+                         include/experimental/unordered_map \
+                         include/experimental/unordered_set \
+                         include/experimental/utility \
+                         include/experimental/vector \
                          include/ext \
                          include/ext/pb_ds \
                          include/ext/pb_ds/detail \
@@ -1965,18 +1997,6 @@ GENERATE_XML           = @do_xml@
 
 XML_OUTPUT             = xml
 
-# The XML_SCHEMA tag can be used to specify a XML schema, which can be used by a
-# validating XML parser to check the syntax of the XML files.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_SCHEMA             =
-
-# The XML_DTD tag can be used to specify a XML DTD, which can be used by a
-# validating XML parser to check the syntax of the XML files.
-# This tag requires that the tag GENERATE_XML is set to YES.
-
-XML_DTD                =
-
 # If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to
 # the XML output. Note that enabling this will significantly increase the size
@@ -2111,9 +2131,10 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = __cplusplus=201103L \
+PREDEFINED             = __cplusplus=201402L \
                          __GTHREADS \
                          _GLIBCXX_HAS_GTHREADS \
+                         _GLIBCXX_HAVE_TLS \
                          _GLIBCXX_INCLUDE_AS_CXX11 \
                          "_GLIBCXX_PURE= " \
                          "_GLIBCXX_CONST= " \
@@ -2135,6 +2156,7 @@ PREDEFINED             = __cplusplus=201103L \
                          _GLIBCXX_USE_CONSTEXPR=constexpr \
                          "_GLIBCXX_THROW(E)= " \
                          _GLIBCXX_NOEXCEPT=noexcept \
+                         "_GLIBCXX_NOEXCEPT_IF(C)=noexcept(/*conditional*/)" \
                          _GLIBCXX_NOTHROW=noexcept \
                          _GLIBCXX_USE_NOEXCEPT=noexcept \
                          _GLIBCXX_USE_WCHAR_T \
@@ -2144,7 +2166,7 @@ PREDEFINED             = __cplusplus=201103L \
                          _GLIBCXX_USE_NANOSLEEP \
                          __cpp_exceptions \
                          __cpp_rtti \
-                         ATOMIC_INT_LOCK_FREE \
+                         ATOMIC_INT_LOCK_FREE=2 \
                          PB_DS_DATA_TRUE_INDICATOR \
                          PB_DS_STATIC_ASSERT=// \
                          "_GLIBCXX_BEGIN_NAMESPACE_ALGO= " \

libstdc++-v3/include/backward/strstream

@@ -40,9 +40,8 @@
 // MAY BE REMOVED in a future standard revision.  One should use the
 // header <sstream> instead.
 
-/** @file backward/strstream
- *  This is an internal header file, included by other library headers.
- *  Do not attempt to use it directly. @headername{sstream}
+/** @file strstream
+ *  This is a Standard C++ Library header.
  */
 
 #ifndef _BACKWARD_STRSTREAM
@@ -53,7 +52,6 @@
 #include <ios>
 #include <istream>
 #include <ostream>
-#include <string>
 
 namespace std _GLIBCXX_VISIBILITY(default)
 {

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

@@ -478,7 +478,8 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
 
       /**
        *  @brief  Creates a %forward_list with default constructed elements.
-       *  @param  __n  The number of elements to initially create.
+       *  @param  __n   The number of elements to initially create.
+       *  @param  __al  An allocator object.
        *
        *  This constructor creates the %forward_list with @a __n default
        *  constructed elements.
@@ -1096,6 +1097,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
        *  after @a __pos in constant time.
        *
        *  Undefined if @a __pos is in (__before,__last).
+       *  @{
        */
       void
       splice_after(const_iterator __pos, forward_list&&,
@@ -1106,6 +1108,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
       splice_after(const_iterator __pos, forward_list&,
                    const_iterator __before, const_iterator __last) noexcept
       { _M_splice_after(__pos, __before, __last); }
+      // @}
 
       /**
        *  @brief  Remove all elements equal to value.

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

@@ -709,7 +709,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11
        *
        *  @param __s        Start of string to parse.
        *  @param __end      End of string to parse.
-       *  @param __io       Source of the locale.
+       *  @param __f        Source of the locale.
        *  @param __err      Error flags to set.
        *  @param __tm       Pointer to struct tm to fill in.
        *  @param __format   Format specifier.

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

@@ -82,7 +82,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
     __mutex_base& operator=(const __mutex_base&) = delete;
   };
 
-  /// mutex
+  /// The standard mutex type.
   class mutex : private __mutex_base
   {
   public:
@@ -138,13 +138,20 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
   /// and manage it.
   struct adopt_lock_t { explicit adopt_lock_t() = default; };
 
+  /// Tag used to prevent a scoped lock from acquiring ownership of a mutex.
   constexpr defer_lock_t	defer_lock { };
+
+  /// Tag used to prevent a scoped lock from blocking if a mutex is locked.
   constexpr try_to_lock_t	try_to_lock { };
+
+  /// Tag used to make a scoped lock take ownership of a locked mutex.
   constexpr adopt_lock_t	adopt_lock { };
 
-  /// @brief  Scoped lock idiom.
-  // Acquire the mutex here with a constructor call, then release with
-  // the destructor call in accordance with RAII style.
+  /** @brief A simple scoped lock type.
+   *
+   * A lock_guard controls mutex ownership within a scope, releasing
+   * ownership in the destructor.
+   */
   template<typename _Mutex>
     class lock_guard
     {
@@ -167,7 +174,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
       mutex_type&  _M_device;
     };
 
-  /// unique_lock
+  /** @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.
+   */
   template<typename _Mutex>
     class unique_lock
     {

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

@@ -41,7 +41,7 @@
 // accompanying file LICENSE_1_0.txt or copy at
 // http://www.boost.org/LICENSE_1_0.txt)
 
-/** @file bits/shared_ptr.h
+/** @file
  *  This is an internal header file, included by other library headers.
  *  Do not attempt to use it directly. @headername{memory}
  */

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

@@ -895,6 +895,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
       /**
        *  @brief  Creates a %deque with default constructed elements.
        *  @param  __n  The number of elements to initially create.
+       *  @param  __a  An allocator.
        *
        *  This constructor fills the %deque with @a n default
        *  constructed elements.

libstdc++-v3/include/debug/vector

@@ -37,9 +37,12 @@
 
 namespace __gnu_debug
 {
-  /// Special vector safe base class to add a guaranteed capacity information
-  /// useful to detect code relying on the libstdc++ reallocation management
-  /// implementation detail.
+  /** @brief Base class for Debug Mode vector.
+   *
+   * Adds information about the guaranteed capacity, which is useful for
+   * detecting code which relies on non-portable implementation details of
+   * the libstdc++ reallocation policy.
+   */
   template<typename _SafeSequence,
 	   typename _BaseSequence>
     class _Safe_vector

libstdc++-v3/include/experimental/bits/fs_dir.h

@@ -22,7 +22,7 @@
 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 // <http://www.gnu.org/licenses/>.
 
-/** @file experimental/fs_dir.h
+/** @file experimental/bits/fs_dir.h
  *  This is an internal header file, included by other library headers.
  *  Do not attempt to use it directly. @headername{experimental/filesystem}
  */

libstdc++-v3/include/experimental/bits/fs_fwd.h

@@ -22,8 +22,9 @@
 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 // <http://www.gnu.org/licenses/>.
 
-/** @file experimental/filesystem
- *  This is a TS C++ Library header.
+/** @file experimental/bits/fs_fwd.h
+ *  This is an internal header file, included by other library headers.
+ *  Do not attempt to use it directly. @headername{experimental/filesystem}
  */
 
 #ifndef _GLIBCXX_EXPERIMENTAL_FS_FWD_H
@@ -52,7 +53,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
 
   /**
-   * @defgroup filesystem
+   * @defgroup filesystem Filesystem
    * @ingroup experimental
    *
    * Utilities for performing operations on file systems and their components,

libstdc++-v3/include/experimental/bits/fs_ops.h

@@ -22,8 +22,9 @@
 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 // <http://www.gnu.org/licenses/>.
 
-/** @file experimental/filesystem
- *  This is a TS C++ Library header.
+/** @file experimental/bits/fs_fwd.h
+ *  This is an internal header file, included by other library headers.
+ *  Do not attempt to use it directly. @headername{experimental/filesystem}
  */
 
 #ifndef _GLIBCXX_EXPERIMENTAL_FS_OPS_H

libstdc++-v3/include/experimental/bits/fs_path.h

@@ -22,7 +22,7 @@
 // see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 // <http://www.gnu.org/licenses/>.
 
-/** @file experimental/fs_path.h
+/** @file experimental/bits/fs_path.h
  *  This is an internal header file, included by other library headers.
  *  Do not attempt to use it directly. @headername{experimental/filesystem}
  */

libstdc++-v3/include/experimental/bits/string_view.tcc

@@ -24,7 +24,7 @@
 
 /** @file experimental/bits/string_view.tcc
  *  This is an internal header file, included by other library headers.
- *  Do not attempt to use it directly. @headername{string_view}
+ *  Do not attempt to use it directly. @headername{experimental/string_view}
  */
 
 //

libstdc++-v3/include/experimental/optional

@@ -33,6 +33,12 @@
  * @defgroup experimental Experimental
  *
  * Components specified by various Technical Specifications.
+ *
+ * As indicated by the std::experimental namespace and the  header paths,
+ * the contents of these Technical Specifications are experimental and not
+ * part of the C++ standard. As such the interfaces and implementations may
+ * change in the future, and there is <STRONG> no guarantee of compatibility
+ * between different GCC releases </STRONG> for these features.
  */
 
 #if __cplusplus <= 201103L

libstdc++-v3/include/experimental/string_view

@@ -23,7 +23,7 @@
 // <http://www.gnu.org/licenses/>.
 
 /** @file experimental/string_view
- *  This is a Standard C++ Library header.
+ *  This is a TS C++ Library header.
  */
 
 //

libstdc++-v3/include/ext/pb_ds/detail/bin_search_tree_/traits.hpp

@@ -166,13 +166,8 @@ namespace __gnu_pbds
 	     class Node_Update,
 	     class Node,
 	     typename _Alloc>
-    struct bin_search_tree_traits<
-      Key,
-      null_type,
-      Cmp_Fn,
-      Node_Update,
-      Node,
-      _Alloc>
+    struct
+    bin_search_tree_traits<Key, null_type, Cmp_Fn, Node_Update, Node, _Alloc>
     {
     private:
       typedef types_traits<Key, null_type, _Alloc, false> type_traits;

libstdc++-v3/include/std/bitset

@@ -663,7 +663,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
     };
 
 #if __cplusplus >= 201103L
-  template<size_t _Nb, bool = _Nb < _GLIBCXX_BITSET_BITS_PER_ULL>
+  template<size_t _Nb, bool = (_Nb < _GLIBCXX_BITSET_BITS_PER_ULL)>
     struct _Sanitize_val
     {
       static constexpr unsigned long long
@@ -681,8 +681,6 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER
 #endif
 
   /**
-   *  @class bitset <bitset>
-   *
    *  @brief The %bitset class represents a @e fixed-size sequence of bits.
    *  @ingroup utilities
    *

libstdc++-v3/include/std/mutex

@@ -87,7 +87,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 #endif
   };
 
-  /// recursive_mutex
+  /// The standard recursive mutex type.
   class recursive_mutex : private __recursive_mutex_base
   {
   public:
@@ -171,7 +171,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
 	}
     };
 
-  /// timed_mutex
+  /// The standard timed mutex type.
   class timed_mutex
   : private __mutex_base, public __timed_mutex_impl<timed_mutex>
   {

libstdc++-v3/include/tr2/dynamic_bitset

@@ -593,6 +593,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
        *  @param  __str  A string of '0' and '1' characters.
        *  @param  __pos  Index of the first character in @p __str to use.
        *  @param  __n    The number of characters to copy.
+       *  @param  __zero The character to use for unset bits.
+       *  @param  __one  The character to use for set bits.
+       *  @param  __alloc An allocator.
        *  @throw  std::out_of_range  If @p __pos is bigger the size of @p __str.
        *  @throw  std::invalid_argument  If a character appears in the string
        *                                 which is neither '0' nor '1'.

libstdc++-v3/scripts/run_doxygen

@@ -334,6 +334,23 @@ for f in *__profile_*; do
     mv $f $newname
 done
 
+# Remove inline namespaces used for versioning.
+for f in *_V2_*; do
+    newname=`echo $f | sed 's/_V2_/::/'`
+    sed 's/::_V2::/::/g' $f > $newname
+    rm $f
+done
+for f in *_experimental_filesystem_v?_*; do
+    newname=`echo $f | sed 's/_filesystem_v._/::filesystem::/'`
+    sed 's/::filesystem::v.::/::filesystem::/g' $f > $newname
+    rm $f
+done
+for f in *experimental_fundamentals_v?_*; do
+    newname=`echo $f | sed 's/experimental_.*_v[[:digit:]]_/experimental::/'`
+    sed 's/::experimental::fundamentals_v[[:digit:]]::/::experimental::/g' $f > $newname
+    rm $f
+done
+
 # Then, clean up other top-level namespaces.
 for f in std_tr1_*; do
     newname=`echo $f | sed 's/^std_tr1_/std::tr1::/'`