[PATCH] Improve API docs for <system_error> header
Jonathan Wakely
jwakely@redhat.com
Sat May 4 14:36:00 GMT 2019
* 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.
Committed to trunk.
-------------- next part --------------
commit e6af564ce9bab326e0a9693d374c37c95c8ad39d
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Sat May 4 14:56:35 2019 +0100
Improve API docs for <system_error> 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.
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<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>
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<typename _Ex>
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<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
More information about the Libstdc++
mailing list