From 2f7f1aca2959712d4d66f1409719a5bde871a626 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Sat, 4 May 2019 15:35:29 +0100 Subject: [PATCH] Improve API docs for header * include/std/system_error (error_category, error_code) (error_condition): Improve docs. * libsupc++/exception: Add missing @addtogroup Doxygen command. * libsupc++/exception_ptr.h (exception_ptr): Link equality operators to class documentation. Suppress documentation for implementation details. * libsupc++/nested_exception.h (throw_with_nested, rethrow_if_nested): Suppress documentation for implementation details. From-SVN: r270873 --- libstdc++-v3/ChangeLog | 9 +++ libstdc++-v3/include/std/system_error | 82 ++++++++++++++++++++--- libstdc++-v3/libsupc++/exception | 4 ++ libstdc++-v3/libsupc++/exception_ptr.h | 7 ++ libstdc++-v3/libsupc++/nested_exception.h | 8 +++ 5 files changed, 99 insertions(+), 11 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 9965009eb3e..b1719103583 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,14 @@ 2019-05-04 Jonathan Wakely + * include/std/system_error (error_category, error_code) + (error_condition): Improve docs. + * libsupc++/exception: Add missing @addtogroup Doxygen command. + * libsupc++/exception_ptr.h (exception_ptr): Link equality operators + to class documentation. Suppress documentation for implementation + details. + * libsupc++/nested_exception.h (throw_with_nested, rethrow_if_nested): + Suppress documentation for implementation details. + * include/std/system_error (error_code): Remove friend declaration for hash. (hash::operator()): Use public member functions to access diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error index a60c96accb2..768eddaefd1 100644 --- a/libstdc++-v3/include/std/system_error +++ b/libstdc++-v3/include/std/system_error @@ -44,6 +44,10 @@ namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION + /** @addtogroup diagnostics + * @{ + */ + class error_code; class error_condition; class system_error; @@ -70,7 +74,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif // C++17 inline namespace _V2 { - /// error_category + /** Abstract base class for types defining a category of error codes. + * + * An error category defines a context that give meaning to the integer + * stored in an `error_code` or `error_category` object. For example, + * the standard `errno` constants such a `EINVAL` and `ENOMEM` are + * 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. + */ class error_category { public: @@ -131,18 +143,31 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; // DR 890. - _GLIBCXX_CONST const error_category& system_category() noexcept; + + /// Error category for `errno` error codes. _GLIBCXX_CONST const error_category& generic_category() noexcept; + /// Error category for other error codes defined by the OS. + _GLIBCXX_CONST const error_category& system_category() noexcept; + } // end inline namespace error_code make_error_code(errc) noexcept; - template - struct hash; - - /// error_code - // Implementation-specific error identification + /** Class error_code + * + * This class is a value type storing an integer error number and a + * category that gives meaning to the error number. Typically this is done + * close the the point where the error happens, to capture the original + * error value. + * + * An `error_code` object can be used to store the original error value + * emitted by some subsystem, with a category relevant to the subsystem. + * For example, errors from POSIX library functions can be represented by + * 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. + */ struct error_code { error_code() noexcept @@ -198,6 +223,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; // 19.4.2.6 non-member functions + + /// @relates error_code @{ + inline error_code make_error_code(errc __e) noexcept { return error_code(static_cast(__e), generic_category()); } @@ -215,10 +243,19 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e) { return (__os << __e.category().name() << ':' << __e.value()); } + // @} + error_condition make_error_condition(errc) noexcept; - /// error_condition - // Portable error identification + /** Class error_condition + * + * This class represents error conditions that may be visible at an API + * boundary. Different `error_code` values that can occur within a library + * or module might map to the same `error_condition`. + * + * An `error_condition` represents something that the program can test for, + * and subsequently take appropriate action. + */ struct error_condition { error_condition() noexcept @@ -272,10 +309,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; // 19.4.3.6 non-member functions + + /// Create an `error_condition` representing a standard `errc` condition. + /// @relates error_condition inline error_condition make_error_condition(errc __e) noexcept { return error_condition(static_cast(__e), generic_category()); } + /// Define an ordering for error_condition objects. + /// @relates error_condition inline bool operator<(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -286,11 +328,15 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } // 19.4.4 Comparison operators + + /// @relates error_code inline bool operator==(const error_code& __lhs, const error_code& __rhs) noexcept { return (__lhs.category() == __rhs.category() && __lhs.value() == __rhs.value()); } + /// @relates error_code + /// @relates error_condition inline bool operator==(const error_code& __lhs, const error_condition& __rhs) noexcept { @@ -298,6 +344,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION || __rhs.category().equivalent(__lhs, __rhs.value())); } + /// @relates error_code + /// @relates error_condition inline bool operator==(const error_condition& __lhs, const error_code& __rhs) noexcept { @@ -305,6 +353,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION || __lhs.category().equivalent(__rhs, __lhs.value())); } + /// @relates error_condition inline bool operator==(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -313,18 +362,24 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION && __lhs.value() == __rhs.value()); } + /// @relates error_code inline bool operator!=(const error_code& __lhs, const error_code& __rhs) noexcept { 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 { return !(__lhs == __rhs); } + /// @relates error_condition inline bool operator!=(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -332,9 +387,12 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @brief Thrown to indicate error code of underlying system. + * @brief An exception type that includes an `error_code` value. * - * @ingroup exceptions + * Typically used to report errors from the operating system and other + * low-level APIs. + * + * @ingroup exceptions */ class system_error : public std::runtime_error { @@ -385,6 +443,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #ifndef _GLIBCXX_COMPATIBILITY_CXX0X // DR 1182. /// std::hash specialization for error_code. + /// @relates error_code template<> struct hash : public __hash_base @@ -401,6 +460,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus >= 201703L // DR 2686. /// std::hash specialization for error_condition. + /// @relates error_condition template<> struct hash : public __hash_base diff --git a/libstdc++-v3/libsupc++/exception b/libstdc++-v3/libsupc++/exception index 073bfdda42d..88be4a4757b 100644 --- a/libstdc++-v3/libsupc++/exception +++ b/libstdc++-v3/libsupc++/exception @@ -41,6 +41,10 @@ extern "C++" { namespace std { + /** @addtogroup exceptions + * @{ + */ + /** If an %exception is thrown which is not listed in a function's * %exception specification, one of these may be thrown. */ class bad_exception : public exception diff --git a/libstdc++-v3/libsupc++/exception_ptr.h b/libstdc++-v3/libsupc++/exception_ptr.h index 3f21a70e54c..6dfb20ace5c 100644 --- a/libstdc++-v3/libsupc++/exception_ptr.h +++ b/libstdc++-v3/libsupc++/exception_ptr.h @@ -49,6 +49,7 @@ namespace std * @addtogroup exceptions * @{ */ + namespace __exception_ptr { class exception_ptr; @@ -154,6 +155,8 @@ namespace std __attribute__ ((__pure__)); }; + /// @relates exception_ptr @{ + bool operator==(const exception_ptr&, const exception_ptr&) _GLIBCXX_USE_NOEXCEPT __attribute__ ((__pure__)); @@ -166,10 +169,14 @@ namespace std swap(exception_ptr& __lhs, exception_ptr& __rhs) { __lhs.swap(__rhs); } + // @} + + /// @cond undocumented template inline void __dest_thunk(void* __x) { static_cast<_Ex*>(__x)->~_Ex(); } + /// @endcond } // namespace __exception_ptr diff --git a/libstdc++-v3/libsupc++/nested_exception.h b/libstdc++-v3/libsupc++/nested_exception.h index 52d3ea8b336..df33a66784a 100644 --- a/libstdc++-v3/libsupc++/nested_exception.h +++ b/libstdc++-v3/libsupc++/nested_exception.h @@ -76,6 +76,8 @@ namespace std { return _M_ptr; } }; + /// @cond undocumented + template struct _Nested_exception : public _Except, public nested_exception { @@ -106,6 +108,8 @@ namespace std __throw_with_nested_impl(_Tp&& __t, false_type) { throw std::forward<_Tp>(__t); } + /// @endcond + /// If @p __t is derived from nested_exception, throws @p __t. /// Else, throws an implementation-defined object derived from both. template @@ -123,6 +127,8 @@ namespace std std::__throw_with_nested_impl(std::forward<_Tp>(__t), __nest{}); } + /// @cond undocumented + // Determine if dynamic_cast would be well-formed. template using __rethrow_if_nested_cond = typename enable_if< @@ -145,6 +151,8 @@ namespace std __rethrow_if_nested_impl(const void*) { } + /// @endcond + /// If @p __ex is derived from nested_exception, @p __ex.rethrow_nested(). template inline void