mirrors/gcc
0
0
Fork 0
mirror of https://gcc.gnu.org/git/gcc.git synced 2024-12-19 09:05:17 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve API docs for <system_error> header

Browse Source 
* 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
This commit is contained in:
Jonathan Wakely 2019-05-04 15:35:29 +01:00 committed by Jonathan Wakely
parent fe6fb0d159
commit 2f7f1aca29
5 changed files with 99 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
libstdc++-v3/ChangeLog
View File

@ -1,5 +1,14 @@
2019-05-04 Jonathan Wakely <jwakely@redhat.com>
* 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<error_code>.
(hash<error_code>::operator()): Use public member functions to access

82
libstdc++-v3/include/std/system_error
View File

@ -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<typename _Tp>
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<int>(__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<int>(__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<error_code>
: public __hash_base<size_t, error_code>
@ -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<error_condition>
: public __hash_base<size_t, error_condition>

4
libstdc++-v3/libsupc++/exception
View File

@ -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

7
libstdc++-v3/libsupc++/exception_ptr.h
View File

@ -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<typename _Ex>
inline void
__dest_thunk(void* __x)
{ static_cast<_Ex*>(__x)->~_Ex(); }
/// @endcond
} // namespace __exception_ptr

8
libstdc++-v3/libsupc++/nested_exception.h
View File

@ -76,6 +76,8 @@ namespace std
{ return _M_ptr; }
};
/// @cond undocumented
template<typename _Except>
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<typename _Tp>
@ -123,6 +127,8 @@ namespace std
std::__throw_with_nested_impl(std::forward<_Tp>(__t), __nest{});
}
/// @cond undocumented
// Determine if dynamic_cast<const nested_exception&> would be well-formed.
template<typename _Tp>
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<typename _Ex>
inline void