From 8abb919aa8098ca16d127bb88494e7f75a6296f4 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Fri, 11 Dec 2015 12:46:50 +0000 Subject: [PATCH] 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/debug/vector (_Safe_vector): Add @brief section to comment. * include/experimental/fs_fwd.h: Correct @file comment. * include/experimental/fs_ops.h: Likewise. * include/experimental/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: r231563 --- libstdc++-v3/ChangeLog | 22 +++++++++++++ libstdc++-v3/doc/doxygen/user.cfg.in | 32 ++++++++++--------- libstdc++-v3/include/backward/strstream | 5 ++- libstdc++-v3/include/bits/forward_list.h | 5 ++- .../include/bits/locale_facets_nonio.h | 2 +- libstdc++-v3/include/debug/vector | 9 ++++-- libstdc++-v3/include/experimental/fs_fwd.h | 7 ++-- libstdc++-v3/include/experimental/fs_ops.h | 5 +-- libstdc++-v3/include/experimental/optional | 6 ++++ libstdc++-v3/include/experimental/string_view | 2 +- .../include/experimental/string_view.tcc | 2 +- .../pb_ds/detail/bin_search_tree_/traits.hpp | 9 ++---- libstdc++-v3/include/std/bitset | 4 +-- libstdc++-v3/include/std/mutex | 23 +++++++++---- libstdc++-v3/include/tr2/dynamic_bitset | 3 ++ libstdc++-v3/scripts/run_doxygen | 17 ++++++++++ 16 files changed, 106 insertions(+), 47 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index fedd4da3e907..ce94ef98e061 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,25 @@ +2015-12-11 Jonathan Wakely + + * 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/debug/vector (_Safe_vector): Add @brief section to comment. + * include/experimental/fs_fwd.h: Correct @file comment. + * include/experimental/fs_ops.h: Likewise. + * include/experimental/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-08 Jonathan Wakely * doc/xml/manual/abi.xml: Backport documentation improvements from diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index ff2db489d6ef..ccd5fbb1173e 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/libstdc++-v3/doc/doxygen/user.cfg.in @@ -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 \ @@ -831,6 +833,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 +856,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 +890,18 @@ INPUT = @srcdir@/doc/doxygen/doxygroups.cc \ include/tr2/ratio \ include/tr2/type_traits \ include/decimal/decimal \ + include/experimental \ + include/experimental/algorithm \ include/experimental/any \ + include/experimental/chrono \ + include/experimental/filesystem \ + include/experimental/functional \ include/experimental/optional \ + include/experimental/ratio \ include/experimental/string_view \ + include/experimental/system_error \ + include/experimental/tuple \ + include/experimental/type_traits \ include/ext \ include/ext/pb_ds \ include/ext/pb_ds/detail \ @@ -1965,18 +1978,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 +2112,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= " \ @@ -2144,7 +2146,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= " \ diff --git a/libstdc++-v3/include/backward/strstream b/libstdc++-v3/include/backward/strstream index 9288e56395ec..10e2dfe34367 100644 --- a/libstdc++-v3/include/backward/strstream +++ b/libstdc++-v3/include/backward/strstream @@ -40,9 +40,8 @@ // MAY BE REMOVED in a future standard revision. One should use the // header 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 diff --git a/libstdc++-v3/include/bits/forward_list.h b/libstdc++-v3/include/bits/forward_list.h index 88eee1f745b1..0cdd75bd4150 100644 --- a/libstdc++-v3/include/bits/forward_list.h +++ b/libstdc++-v3/include/bits/forward_list.h @@ -463,7 +463,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. @@ -1083,6 +1084,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&&, @@ -1093,6 +1095,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER splice_after(const_iterator __pos, forward_list&, const_iterator __before, const_iterator __last) { _M_splice_after(__pos, __before, __last); } + // @} /** * @brief Remove all elements equal to value. diff --git a/libstdc++-v3/include/bits/locale_facets_nonio.h b/libstdc++-v3/include/bits/locale_facets_nonio.h index 7eae6c80653f..527296b78f09 100644 --- a/libstdc++-v3/include/bits/locale_facets_nonio.h +++ b/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. diff --git a/libstdc++-v3/include/debug/vector b/libstdc++-v3/include/debug/vector index bf0a88eb01c9..085e5f73ade4 100644 --- a/libstdc++-v3/include/debug/vector +++ b/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 class _Safe_vector diff --git a/libstdc++-v3/include/experimental/fs_fwd.h b/libstdc++-v3/include/experimental/fs_fwd.h index a5ed2c5de0ef..dd6f5e6dd2ce 100644 --- a/libstdc++-v3/include/experimental/fs_fwd.h +++ b/libstdc++-v3/include/experimental/fs_fwd.h @@ -22,8 +22,9 @@ // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see // . -/** @file experimental/filesystem - * This is a TS C++ Library header. +/** @file experimental/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, diff --git a/libstdc++-v3/include/experimental/fs_ops.h b/libstdc++-v3/include/experimental/fs_ops.h index 6b7d4709ee5b..91b890203fe8 100644 --- a/libstdc++-v3/include/experimental/fs_ops.h +++ b/libstdc++-v3/include/experimental/fs_ops.h @@ -22,8 +22,9 @@ // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see // . -/** @file experimental/filesystem - * This is a TS C++ Library header. +/** @file experimental/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 diff --git a/libstdc++-v3/include/experimental/optional b/libstdc++-v3/include/experimental/optional index 811235bfce47..f6e3fa0258ab 100644 --- a/libstdc++-v3/include/experimental/optional +++ b/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 no guarantee of compatibility + * between different GCC releases for these features. */ #if __cplusplus <= 201103L diff --git a/libstdc++-v3/include/experimental/string_view b/libstdc++-v3/include/experimental/string_view index 9c2b773573f3..f11a1878c56a 100644 --- a/libstdc++-v3/include/experimental/string_view +++ b/libstdc++-v3/include/experimental/string_view @@ -23,7 +23,7 @@ // . /** @file experimental/string_view - * This is a Standard C++ Library header. + * This is a TS C++ Library header. */ // diff --git a/libstdc++-v3/include/experimental/string_view.tcc b/libstdc++-v3/include/experimental/string_view.tcc index 75a34f90b2de..942184206a65 100644 --- a/libstdc++-v3/include/experimental/string_view.tcc +++ b/libstdc++-v3/include/experimental/string_view.tcc @@ -24,7 +24,7 @@ /** @file experimental/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} */ // diff --git a/libstdc++-v3/include/ext/pb_ds/detail/bin_search_tree_/traits.hpp b/libstdc++-v3/include/ext/pb_ds/detail/bin_search_tree_/traits.hpp index da01e1a2d4d3..674fa9201258 100644 --- a/libstdc++-v3/include/ext/pb_ds/detail/bin_search_tree_/traits.hpp +++ b/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 { private: typedef types_traits type_traits; diff --git a/libstdc++-v3/include/std/bitset b/libstdc++-v3/include/std/bitset index d6be839bd77e..44df60c115b3 100644 --- a/libstdc++-v3/include/std/bitset +++ b/libstdc++-v3/include/std/bitset @@ -663,7 +663,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER }; #if __cplusplus >= 201103L - template + template struct _Sanitize_val { static constexpr unsigned long long @@ -681,8 +681,6 @@ _GLIBCXX_BEGIN_NAMESPACE_CONTAINER #endif /** - * @class bitset - * * @brief The %bitset class represents a @e fixed-size sequence of bits. * @ingroup utilities * diff --git a/libstdc++-v3/include/std/mutex b/libstdc++-v3/include/std/mutex index deb85dfefe04..b80a8a0123f1 100644 --- a/libstdc++-v3/include/std/mutex +++ b/libstdc++-v3/include/std/mutex @@ -114,7 +114,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @{ */ - /// mutex + /// The standard mutex type. class mutex : private __mutex_base { public: @@ -158,7 +158,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return &_M_mutex; } }; - /// recursive_mutex + /// The standard recursive mutex type. class recursive_mutex : private __recursive_mutex_base { public: @@ -243,7 +243,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } }; - /// timed_mutex + /// The standard timed mutex type. class timed_mutex : private __mutex_base, public __timed_mutex_impl { @@ -295,7 +295,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return &_M_mutex; } }; - /// recursive_timed_mutex + /// The standard recursive timed mutex type. class recursive_timed_mutex : private __recursive_mutex_base, public __timed_mutex_impl @@ -360,13 +360,22 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// and manage it. struct adopt_lock_t { }; + /// 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 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 class lock_guard { diff --git a/libstdc++-v3/include/tr2/dynamic_bitset b/libstdc++-v3/include/tr2/dynamic_bitset index 183179f25d1c..77bddc32b954 100644 --- a/libstdc++-v3/include/tr2/dynamic_bitset +++ b/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'. diff --git a/libstdc++-v3/scripts/run_doxygen b/libstdc++-v3/scripts/run_doxygen index 461adaa7da0b..021ebd0b561f 100644 --- a/libstdc++-v3/scripts/run_doxygen +++ b/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::/'`