From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id 1074B397EC1D; Wed, 11 Aug 2021 15:42:33 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 1074B397EC1D MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r11-8846] libstdc++: Improvements to Doxygen markup X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/releases/gcc-11 X-Git-Oldrev: 63758bead0337b5225016711bf9d540cf7cc80b1 X-Git-Newrev: ea32f15d44e4f50f3eb9deb3135e0b6d50f7ec43 Message-Id: <20210811154233.1074B397EC1D@sourceware.org> Date: Wed, 11 Aug 2021 15:42:33 +0000 (GMT) X-BeenThere: libstdc++-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 11 Aug 2021 15:42:33 -0000 https://gcc.gnu.org/g:ea32f15d44e4f50f3eb9deb3135e0b6d50f7ec43 commit r11-8846-gea32f15d44e4f50f3eb9deb3135e0b6d50f7ec43 Author: Jonathan Wakely Date: Thu Jul 1 00:30:54 2021 +0100 libstdc++: Improvements to Doxygen markup This attempts to improve the doxygen output to work around what seems to be some bugs in doxygen (issues 8635 and 8638). The @addtogroup command doesn't work for entities inside a nested namespace (see 8635) so we need to close and reopen groups on entering and elaving nested namespaces. This fixes the problem that chrono::duration and chrono::time_point were not documented in the "Time" documentation group. I am unable to make the path classes appear as part of their relevant groups (File System and Filesystem TS), nor the contents of or . I have made some minor improvements to the docs for those types, including starting to address PR 97001 by adding @since to the doxygen comments. This change also excludes the header from Doxygen processing, so we don't get an unwanted "Networking-ts" group in the documentation. Signed-off-by: Jonathan Wakely libstdc++-v3/ChangeLog: * doc/doxygen/doxygroups.cc: Fix docs for std::literals. * doc/doxygen/user.cfg.in: Exclude the Networking TS header. Add some more predefined macros. * include/bits/fs_fwd.h: Move @addtogroup commands inside namespaces. Add better documentation. * include/bits/fs_path.h: Likewise. * include/experimental/bits/fs_fwd.h: Likewise. * include/experimental/bits/fs_path.h: Likewise. * include/ext/throw_allocator.h: Fix typo and improve docs. * include/std/chrono: Move @addtogroup commands. * include/std/system_error: Move @addtogroup commands. * libsupc++/exception: Improve documentation. * libsupc++/exception.h: Add @since documentation. (cherry picked from commit f2ce64b53fa76a4c192fe51b2f6c5a863a3b1241) Diff: --- libstdc++-v3/doc/doxygen/doxygroups.cc | 4 +- libstdc++-v3/doc/doxygen/user.cfg.in | 7 ++- libstdc++-v3/include/bits/fs_fwd.h | 34 ++++++++--- libstdc++-v3/include/bits/fs_path.h | 20 +++++-- libstdc++-v3/include/experimental/bits/fs_fwd.h | 24 ++++++-- libstdc++-v3/include/experimental/bits/fs_path.h | 12 +++- libstdc++-v3/include/ext/throw_allocator.h | 2 +- libstdc++-v3/include/std/chrono | 72 +++++++++++++++++------- libstdc++-v3/include/std/system_error | 26 +++++++-- libstdc++-v3/libsupc++/exception | 20 ++++--- libstdc++-v3/libsupc++/exception.h | 1 + 11 files changed, 163 insertions(+), 59 deletions(-) diff --git a/libstdc++-v3/doc/doxygen/doxygroups.cc b/libstdc++-v3/doc/doxygen/doxygroups.cc index 506cb145b35..42f7d447520 100644 --- a/libstdc++-v3/doc/doxygen/doxygroups.cc +++ b/libstdc++-v3/doc/doxygen/doxygroups.cc @@ -19,7 +19,7 @@ /** @namespace std * @brief ISO C++ entities toplevel namespace is std. */ -/** @namespace std +/** @namespace std::literals * @brief ISO C++ inline namespace for literal suffixes. */ /** @namespace std::__detail @@ -43,7 +43,7 @@ * @ingroup extensions */ /** @namespace __gnu_cxx::__detail - * @brief Implementation details not part of the namespace __gnu_cxx + * @brief Implementation details not part of the namespace __gnu_cxx * interface. */ /** @namespace __gnu_internal diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index 2c7df479a25..25f7e1ef33f 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/libstdc++-v3/doc/doxygen/user.cfg.in @@ -1092,7 +1092,8 @@ RECURSIVE = NO # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = Makefile +EXCLUDE = Makefile \ + include/experimental/bits/net.h # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -2446,7 +2447,9 @@ PREDEFINED = __cplusplus=201703L \ "_GLIBCXX17_DEPRECATED_SUGGEST(E)= " \ "_GLIBCXX20_DEPRECATED(E)= " \ "_GLIBCXX20_DEPRECATED(E)= " \ - _GLIBCXX17_INLINE=inline + _GLIBCXX17_INLINE=inline \ + _GLIBCXX_CHRONO_INT64_T=int64_t \ + _GLIBCXX_DEFAULT_ABI_TAG # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/libstdc++-v3/include/bits/fs_fwd.h b/libstdc++-v3/include/bits/fs_fwd.h index 3a1ff35f8e2..a7f5a37709c 100644 --- a/libstdc++-v3/include/bits/fs_fwd.h +++ b/libstdc++-v3/include/bits/fs_fwd.h @@ -40,17 +40,18 @@ namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION -/** @addtogroup filesystem - * @{ - */ - /// ISO C++ 2017 namespace for File System library namespace filesystem { #if _GLIBCXX_USE_CXX11_ABI +/// @cond undocumented inline namespace __cxx11 __attribute__((__abi_tag__ ("cxx11"))) { } +/// @endcond #endif +/** @addtogroup filesystem + * @{ + */ class file_status; _GLIBCXX_BEGIN_NAMESPACE_CXX11 @@ -61,6 +62,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 class recursive_directory_iterator; _GLIBCXX_END_NAMESPACE_CXX11 + /// Information about free space on a disk struct space_info { uintmax_t capacity; @@ -72,12 +74,13 @@ _GLIBCXX_END_NAMESPACE_CXX11 #endif }; + /// Enumerated type representing the type of a file enum class file_type : signed char { none = 0, not_found = -1, regular = 1, directory = 2, symlink = 3, block = 4, character = 5, fifo = 6, socket = 7, unknown = 8 }; - /// Bitmask type + /// Bitmask type controlling effects of `filesystem::copy` enum class copy_options : unsigned short { none = 0, skip_existing = 1, overwrite_existing = 2, update_existing = 4, @@ -86,6 +89,8 @@ _GLIBCXX_END_NAMESPACE_CXX11 directories_only = 64, create_symlinks = 128, create_hard_links = 256 }; + /// @{ + /// @relates copy_options constexpr copy_options operator&(copy_options __x, copy_options __y) noexcept { @@ -128,9 +133,10 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline copy_options& operator^=(copy_options& __x, copy_options __y) noexcept { return __x = __x ^ __y; } + /// @} - /// Bitmask type + /// Bitmask type representing file access permissions enum class perms : unsigned { none = 0, owner_read = 0400, @@ -153,6 +159,8 @@ _GLIBCXX_END_NAMESPACE_CXX11 unknown = 0xFFFF, }; + /// @{ + /// @relates perm_options constexpr perms operator&(perms __x, perms __y) noexcept { @@ -195,8 +203,9 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline perms& operator^=(perms& __x, perms __y) noexcept { return __x = __x ^ __y; } + /// @} - /// Bitmask type + /// Bitmask type controlling changes to permissions enum class perm_options : unsigned { replace = 0x1, add = 0x2, @@ -204,6 +213,8 @@ _GLIBCXX_END_NAMESPACE_CXX11 nofollow = 0x8 }; + /// @{ + /// @relates perm_options constexpr perm_options operator&(perm_options __x, perm_options __y) noexcept { @@ -246,12 +257,15 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline perm_options& operator^=(perm_options& __x, perm_options __y) noexcept { return __x = __x ^ __y; } + /// @} - // Bitmask type + /// Bitmask type controlling directory iteration enum class directory_options : unsigned char { none = 0, follow_directory_symlink = 1, skip_permission_denied = 2 }; + /// @{ + /// @relates directory_options constexpr directory_options operator&(directory_options __x, directory_options __y) noexcept { @@ -294,7 +308,9 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline directory_options& operator^=(directory_options& __x, directory_options __y) noexcept { return __x = __x ^ __y; } + /// @} + /// The type used for file timestamps using file_time_type = __file_clock::time_point; // operational functions @@ -338,8 +354,8 @@ _GLIBCXX_END_NAMESPACE_CXX11 bool is_regular_file(file_status) noexcept; bool is_symlink(file_status) noexcept; -} // namespace filesystem /// @} +} // namespace filesystem _GLIBCXX_END_NAMESPACE_VERSION } // namespace std #endif // C++17 diff --git a/libstdc++-v3/include/bits/fs_path.h b/libstdc++-v3/include/bits/fs_path.h index 5e285204527..4fcd1def92f 100644 --- a/libstdc++-v3/include/bits/fs_path.h +++ b/libstdc++-v3/include/bits/fs_path.h @@ -63,15 +63,13 @@ namespace filesystem { _GLIBCXX_BEGIN_NAMESPACE_CXX11 - /** @addtogroup filesystem - * @{ - */ - class path; /// @cond undocumented namespace __detail { + /// @addtogroup filesystem + /// @{ template inline constexpr bool __is_encoded_char = false; template<> @@ -238,10 +236,15 @@ namespace __detail return basic_string<_EcharT>(__first, __last); } + /// @} group filesystem } // namespace __detail /// @endcond - /// A filesystem path. + /// @addtogroup filesystem + /// @{ + + /// A filesystem path + /// @ingroup filesystem class path { public: @@ -693,7 +696,8 @@ namespace __detail struct _Parser; }; - /// @relates std::filesystem::path @{ + /// @{ + /// @relates std::filesystem::path inline void swap(path& __lhs, path& __rhs) noexcept { __lhs.swap(__rhs); } @@ -1347,6 +1351,8 @@ namespace __detail _GLIBCXX_END_NAMESPACE_CXX11 } // namespace filesystem +/// @cond undocumented + inline ptrdiff_t distance(filesystem::path::iterator __first, filesystem::path::iterator __last) { return __path_iter_distance(__first, __last); } @@ -1358,6 +1364,8 @@ template extern template class __shared_ptr; +/// @endcond + _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/experimental/bits/fs_fwd.h b/libstdc++-v3/include/experimental/bits/fs_fwd.h index 2b0655d2a69..8d63e095be5 100644 --- a/libstdc++-v3/include/experimental/bits/fs_fwd.h +++ b/libstdc++-v3/include/experimental/bits/fs_fwd.h @@ -60,6 +60,11 @@ inline namespace __cxx11 __attribute__((__abi_tag__ ("cxx11"))) { } * such as paths, regular files, and directories. * * ISO/IEC TS 18822:2015 C++ File System Technical Specification + * + * @since C++11 + * + * @remark Link using `-lstdc++fs` to use these types and functions. + * * @{ */ @@ -72,6 +77,7 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 class recursive_directory_iterator; _GLIBCXX_END_NAMESPACE_CXX11 + /// Information about free space on a disk struct space_info { uintmax_t capacity; @@ -79,12 +85,13 @@ _GLIBCXX_END_NAMESPACE_CXX11 uintmax_t available; }; + /// Enumerated type representing the type of a file enum class file_type : signed char { none = 0, not_found = -1, regular = 1, directory = 2, symlink = 3, block = 4, character = 5, fifo = 6, socket = 7, unknown = 8 }; - /// Bitmask type + /// Bitmask type controlling effects of `filesystem::copy` enum class copy_options : unsigned short { none = 0, skip_existing = 1, overwrite_existing = 2, update_existing = 4, @@ -93,6 +100,8 @@ _GLIBCXX_END_NAMESPACE_CXX11 directories_only = 64, create_symlinks = 128, create_hard_links = 256 }; + /// @{ + /// @relates copy_options constexpr copy_options operator&(copy_options __x, copy_options __y) noexcept { @@ -135,9 +144,9 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline copy_options& operator^=(copy_options& __x, copy_options __y) noexcept { return __x = __x ^ __y; } + /// @} - - /// Bitmask type + /// Bitmask type representing file access permissions enum class perms : unsigned { none = 0, owner_read = 0400, @@ -163,6 +172,8 @@ _GLIBCXX_END_NAMESPACE_CXX11 symlink_nofollow = 0x40000 }; + /// @{ + /// @relates std::experimental::filesystem::perms constexpr perms operator&(perms __x, perms __y) noexcept { @@ -205,12 +216,15 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline perms& operator^=(perms& __x, perms __y) noexcept { return __x = __x ^ __y; } + /// @} - // Bitmask type + /// Bitmask type controlling directory iteration enum class directory_options : unsigned char { none = 0, follow_directory_symlink = 1, skip_permission_denied = 2 }; + /// @{ + /// @relates directory_options constexpr directory_options operator&(directory_options __x, directory_options __y) noexcept { @@ -253,7 +267,9 @@ _GLIBCXX_END_NAMESPACE_CXX11 inline directory_options& operator^=(directory_options& __x, directory_options __y) noexcept { return __x = __x ^ __y; } + /// @} + /// The type used for file timestamps using file_time_type = std::chrono::system_clock::time_point; // operational functions diff --git a/libstdc++-v3/include/experimental/bits/fs_path.h b/libstdc++-v3/include/experimental/bits/fs_path.h index 1fb84ec1e78..a2bc931c696 100644 --- a/libstdc++-v3/include/experimental/bits/fs_path.h +++ b/libstdc++-v3/include/experimental/bits/fs_path.h @@ -71,13 +71,13 @@ _GLIBCXX_BEGIN_NAMESPACE_CXX11 using std::basic_string_view; #endif + /// @cond undocumented +namespace __detail +{ /** @addtogroup filesystem-ts * @{ */ - /// @cond undocumented -namespace __detail -{ template::type> using __is_encoded_char @@ -188,10 +188,16 @@ namespace __detail #endif >::value, _UnqualVal>::type; + /// @} group filesystem-ts } // namespace __detail /// @endcond + /** @addtogroup filesystem-ts + * @{ + */ + /// A filesystem path. + /// @ingroup filesystem-ts class path { public: diff --git a/libstdc++-v3/include/ext/throw_allocator.h b/libstdc++-v3/include/ext/throw_allocator.h index f4b3174dec6..6abef705f9a 100644 --- a/libstdc++-v3/include/ext/throw_allocator.h +++ b/libstdc++-v3/include/ext/throw_allocator.h @@ -73,7 +73,7 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @brief Thown by exception safety machinery. + * @brief Thrown by utilities for testing exception safety. * @ingroup exceptions */ struct forced_error : public std::exception diff --git a/libstdc++-v3/include/std/chrono b/libstdc++-v3/include/std/chrono index 4631a727d73..a52304b1738 100644 --- a/libstdc++-v3/include/std/chrono +++ b/libstdc++-v3/include/std/chrono @@ -59,21 +59,32 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @ingroup utilities * * Classes and functions for time. - * @{ + * + * @since C++11 */ /** @namespace std::chrono * @brief ISO C++ 2011 namespace for date and time utilities + * @ingroup chrono */ namespace chrono { + /// @addtogroup chrono + /// @{ + + /// `chrono::duration` represents a distance between two points in time template> struct duration; + /// `chrono::time_point` represents a point in time as measured by a clock template struct time_point; + /// @} } + /// @addtogroup chrono + /// @{ + // 20.11.4.3 specialization of common_type (for duration, sfinae-friendly) /// @cond undocumented @@ -99,8 +110,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// @endcond + /// @{ + /// @relates chrono::duration + /// Specialization of common_type for chrono::duration types. - /// @relates duration template struct common_type, chrono::duration<_Rep2, _Period2>> @@ -110,7 +123,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { }; /// Specialization of common_type for two identical chrono::duration types. - /// @relates duration template struct common_type, chrono::duration<_Rep, _Period>> @@ -120,13 +132,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; /// Specialization of common_type for one chrono::duration type. - /// @relates duration template struct common_type> { using type = chrono::duration::type, typename _Period::type>; }; + /// @} // 20.11.4.3 specialization of common_type (for time_point, sfinae-friendly) @@ -144,8 +156,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// @endcond + /// @{ + /// @relates chrono::time_point + /// Specialization of common_type for chrono::time_point types. - /// @relates time_point template struct common_type, chrono::time_point<_Clock, _Duration2>> @@ -153,17 +167,16 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { }; /// Specialization of common_type for two identical chrono::time_point types. - /// @relates time_point template struct common_type, chrono::time_point<_Clock, _Duration>> { using type = chrono::time_point<_Clock, _Duration>; }; /// Specialization of common_type for one chrono::time_point type. - /// @relates time_point template struct common_type> { using type = chrono::time_point<_Clock, _Duration>; }; + /// @} /// @} group chrono @@ -442,7 +455,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// @endcond - /// duration template struct duration { @@ -623,7 +635,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION rep __r; }; - /// @relates duration @{ + /// @{ + /// @relates std::chrono::duration /// The sum of two durations. template constexpr duration<__common_rep_t<_Rep1, _Rep2>, _Period> operator*(const duration<_Rep1, _Period>& __d, const _Rep2& __s) @@ -680,7 +695,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __cd(__cd(__d).count() * __s); } - /// Multiply a duration by a scalar value. template constexpr duration<__common_rep_t<_Rep2, _Rep1>, _Period> operator*(const _Rep1& __s, const duration<_Rep2, _Period>& __d) @@ -731,9 +745,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION typedef typename common_type<__dur1,__dur2>::type __cd; return __cd(__cd(__lhs).count() % __cd(__rhs).count()); } + /// @} // comparisons + /** @{ + * Comparisons for chrono::duration + * @relates std::chrono::duration + */ + template constexpr bool @@ -802,6 +822,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// @} + /// @cond undocumented #ifdef _GLIBCXX_USE_C99_STDINT_TR1 # define _GLIBCXX_CHRONO_INT64_T int64_t #elif defined __INT64_TYPE__ @@ -811,6 +832,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION "Representation type for nanoseconds must have at least 64 bits"); # define _GLIBCXX_CHRONO_INT64_T long long #endif + /// @endcond /// nanoseconds using nanoseconds = duration<_GLIBCXX_CHRONO_INT64_T, nano>; @@ -846,7 +868,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #undef _GLIBCXX_CHRONO_INT64_T - /// time_point template struct time_point { @@ -970,7 +991,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } #endif // C++17 - /// @relates time_point @{ + /// @{ + /// @relates time_point /// Adjust a time point forwards by the given duration. template constexpr typename common_type<_Dur1, _Dur2>::type operator-(const time_point<_Clock, _Dur1>& __lhs, const time_point<_Clock, _Dur2>& __rhs) { return __lhs.time_since_epoch() - __rhs.time_since_epoch(); } + /// @} + + /** @{ + * Comparisons for time_point + * @relates chrono::time_point + */ template constexpr bool @@ -3130,7 +3154,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; #endif // C++20 - /// @} + /// @} group chrono } // namespace chrono #if __cplusplus > 201103L @@ -3164,6 +3188,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION */ inline namespace chrono_literals { + /// @addtogroup chrono + /// @{ + #pragma GCC diagnostic push #pragma GCC diagnostic ignored "-Wliteral-suffix" /// @cond undocumented @@ -3255,6 +3282,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // C++20 #pragma GCC diagnostic pop + /// @} } // inline namespace chrono_literals } // inline namespace literals @@ -3266,6 +3294,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus > 201703L namespace chrono { + /// @addtogroup chrono + /// @{ + // 12/24 HOURS FUNCTIONS constexpr bool @@ -3304,7 +3335,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION return __h + 12h; } } - } + /// @} group chrono + } // namespace chrono #endif #if __cplusplus >= 201703L diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error index 8c10a89ab46..142af7100d0 100644 --- a/libstdc++-v3/include/std/system_error +++ b/libstdc++-v3/include/std/system_error @@ -48,7 +48,7 @@ namespace std _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** @addtogroup diagnostics - * @{ + * @{ */ class error_code; @@ -75,8 +75,14 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION inline constexpr bool is_error_condition_enum_v = is_error_condition_enum<_Tp>::value; #endif // C++17 + /// @} + inline namespace _V2 { + /** @addtogroup diagnostics + * @{ + */ + /** Abstract base class for types defining a category of error codes. * * An error category defines a context that give meaning to the integer @@ -85,6 +91,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * associated with the "generic" category and other OS-specific error * numbers are associated with the "system" category, but a user-defined * category might give different meanings to the same numerical values. + * + * @since C++11 */ class error_category { @@ -159,8 +167,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /// Error category for other error codes defined by the OS. _GLIBCXX_CONST const error_category& system_category() noexcept; + /// @} } // end inline namespace + /** @addtogroup diagnostics + * @{ + */ + error_code make_error_code(errc) noexcept; /** Class error_code @@ -176,6 +189,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * an `errno` value and the "generic" category, but errors from an HTTP * library might be represented by an HTTP response status code (e.g. 404) * and a custom category defined by the library. + * + * @since C++11 + * @ingroup diagnostics */ class error_code { @@ -275,6 +291,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * * An `error_condition` represents something that the program can test for, * and subsequently take appropriate action. + * + * @since C++11 */ class error_condition { @@ -346,7 +364,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION && __lhs.value() == __rhs.value()); } /// @relates error_code - /// @relates error_condition inline bool operator==(const error_code& __lhs, const error_condition& __rhs) noexcept { @@ -386,7 +403,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION && __lhs.value() < __rhs.value())); } - /// @relates error_code /// @relates error_condition inline bool operator==(const error_condition& __lhs, const error_code& __rhs) noexcept @@ -401,12 +417,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return !(__lhs == __rhs); } /// @relates error_code - /// @relates error_condition inline bool operator!=(const error_code& __lhs, const error_condition& __rhs) noexcept { return !(__lhs == __rhs); } - /// @relates error_code /// @relates error_condition inline bool operator!=(const error_condition& __lhs, const error_code& __rhs) noexcept @@ -418,6 +432,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION const error_condition& __rhs) noexcept { return !(__lhs == __rhs); } #endif // three_way_comparison + /// @} /** * @brief An exception type that includes an `error_code` value. @@ -425,6 +440,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * Typically used to report errors from the operating system and other * low-level APIs. * + * @since C++11 * @ingroup exceptions */ class system_error : public std::runtime_error diff --git a/libstdc++-v3/libsupc++/exception b/libstdc++-v3/libsupc++/exception index 7c6d90ec525..a023e22ea89 100644 --- a/libstdc++-v3/libsupc++/exception +++ b/libstdc++-v3/libsupc++/exception @@ -46,7 +46,10 @@ namespace std */ /** If an %exception is thrown which is not listed in a function's - * %exception specification, one of these may be thrown. */ + * %exception specification, one of these may be thrown. + * + * @ingroup exceptions + */ class bad_exception : public exception { public: @@ -93,13 +96,13 @@ namespace std /** [18.6.4]/1: 'Returns true after completing evaluation of a * throw-expression until either completing initialization of the - * exception-declaration in the matching handler or entering @c unexpected() - * due to the throw; or after entering @c terminate() for any reason - * other than an explicit call to @c terminate(). [Note: This includes + * exception-declaration in the matching handler or entering `unexpected()` + * due to the throw; or after entering `terminate()` for any reason + * other than an explicit call to `terminate()`. [Note: This includes * stack unwinding [15.2]. end note]' * - * 2: 'When @c uncaught_exception() is true, throwing an - * %exception can result in a call of @c terminate() + * 2: 'When `uncaught_exception()` is true, throwing an + * %exception can result in a call of 1terminate()` * (15.5.1).' */ _GLIBCXX17_DEPRECATED @@ -107,7 +110,10 @@ namespace std #if __cplusplus >= 201703L || !defined(__STRICT_ANSI__) // c++17 or gnu++98 #define __cpp_lib_uncaught_exceptions 201411L - /// The number of uncaught exceptions. + /** The number of uncaught exceptions. + * @since C++17, or any non-strict mode, e.g. `-std=gnu++98` + * @see uncaught_exception() + */ int uncaught_exceptions() _GLIBCXX_USE_NOEXCEPT __attribute__ ((__pure__)); #endif diff --git a/libstdc++-v3/libsupc++/exception.h b/libstdc++-v3/libsupc++/exception.h index 373ce3fef57..60faa8836b8 100644 --- a/libstdc++-v3/libsupc++/exception.h +++ b/libstdc++-v3/libsupc++/exception.h @@ -44,6 +44,7 @@ namespace std /** * @defgroup exceptions Exceptions * @ingroup diagnostics + * @since C++98 * * Classes and functions for reporting errors via exceptions. * @{