From: Jonathan Wakely Date: Thu, 10 Dec 2015 14:02:52 +0000 (+0000) Subject: Improve generated libstdc++ API docs X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=6b4f890601a9bb1ff803cef04ee5779d49befb97;p=gcc.git 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 --- diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index f77428e1b2f..c46aede2f46 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,30 @@ +2015-12-10 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/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 PR libstdc++/57060 diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index ff2db489d6e..a62eeffa393 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/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= " \ diff --git a/libstdc++-v3/include/backward/strstream b/libstdc++-v3/include/backward/strstream index 9288e56395e..6d778f0e23a 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 @@ -53,7 +52,6 @@ #include #include #include -#include namespace std _GLIBCXX_VISIBILITY(default) { diff --git a/libstdc++-v3/include/bits/forward_list.h b/libstdc++-v3/include/bits/forward_list.h index d87f1754ed3..1229dd7a49b 100644 --- a/libstdc++-v3/include/bits/forward_list.h +++ b/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. diff --git a/libstdc++-v3/include/bits/locale_facets_nonio.h b/libstdc++-v3/include/bits/locale_facets_nonio.h index 7eae6c80653..527296b78f0 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/bits/mutex.h b/libstdc++-v3/include/bits/mutex.h index dd279899ee9..fabd2575920 100644 --- a/libstdc++-v3/include/bits/mutex.h +++ b/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 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 class unique_lock { diff --git a/libstdc++-v3/include/bits/shared_ptr.h b/libstdc++-v3/include/bits/shared_ptr.h index 26a0ad3d7b7..785d92b2e76 100644 --- a/libstdc++-v3/include/bits/shared_ptr.h +++ b/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} */ diff --git a/libstdc++-v3/include/bits/stl_deque.h b/libstdc++-v3/include/bits/stl_deque.h index f81ffd97d33..a507806e86b 100644 --- a/libstdc++-v3/include/bits/stl_deque.h +++ b/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. diff --git a/libstdc++-v3/include/debug/vector b/libstdc++-v3/include/debug/vector index fede4f0917c..6a4315a55f7 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/bits/fs_dir.h b/libstdc++-v3/include/experimental/bits/fs_dir.h index 0c5253fb62d..493c582a9a5 100644 --- a/libstdc++-v3/include/experimental/bits/fs_dir.h +++ b/libstdc++-v3/include/experimental/bits/fs_dir.h @@ -22,7 +22,7 @@ // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see // . -/** @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} */ diff --git a/libstdc++-v3/include/experimental/bits/fs_fwd.h b/libstdc++-v3/include/experimental/bits/fs_fwd.h index a5ed2c5de0e..c71d5031878 100644 --- a/libstdc++-v3/include/experimental/bits/fs_fwd.h +++ b/libstdc++-v3/include/experimental/bits/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/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, diff --git a/libstdc++-v3/include/experimental/bits/fs_ops.h b/libstdc++-v3/include/experimental/bits/fs_ops.h index 6b7d4709ee5..534c51a236f 100644 --- a/libstdc++-v3/include/experimental/bits/fs_ops.h +++ b/libstdc++-v3/include/experimental/bits/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/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 diff --git a/libstdc++-v3/include/experimental/bits/fs_path.h b/libstdc++-v3/include/experimental/bits/fs_path.h index 98820ad29b1..2056fb392c4 100644 --- a/libstdc++-v3/include/experimental/bits/fs_path.h +++ b/libstdc++-v3/include/experimental/bits/fs_path.h @@ -22,7 +22,7 @@ // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see // . -/** @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} */ diff --git a/libstdc++-v3/include/experimental/bits/string_view.tcc b/libstdc++-v3/include/experimental/bits/string_view.tcc index 0eb4f70a93c..96e49d860ff 100644 --- a/libstdc++-v3/include/experimental/bits/string_view.tcc +++ b/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} */ // diff --git a/libstdc++-v3/include/experimental/optional b/libstdc++-v3/include/experimental/optional index 811235bfce4..f6e3fa0258a 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 9931ad0557d..ebeb4403b2b 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/ext/pb_ds/detail/bin_search_tree_/traits.hpp b/libstdc++-v3/include/ext/pb_ds/detail/bin_search_tree_/traits.hpp index da01e1a2d4d..674fa920125 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 d6be839bd77..44df60c115b 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 5e5ced11efe..8345d20ea9c 100644 --- a/libstdc++-v3/include/std/mutex +++ b/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 { diff --git a/libstdc++-v3/include/tr2/dynamic_bitset b/libstdc++-v3/include/tr2/dynamic_bitset index 183179f25d1..77bddc32b95 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 461adaa7da0..021ebd0b561 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::/'`