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.

From-SVN: r270873

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index 9965009eb3e6ddfca3520881955f5b07d8dc2839..b17191035834a31422ad9bb1485dd39f3cf88c0a 100644 (file)
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -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

diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error
index a60c96accb2171982068056e79d147d328d2ad13..768eddaefd15db43c9ae194807a1d0920ece941b 100644 (file)
--- 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.
+   *
+   * Typically used to report errors from the operating system and other
+   * low-level APIs.
    *
-   *  @ingroup exceptions
+   * @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 073bfdda42d324213f61d52d5c80a194efa9a1e7..88be4a4757b9dd65ddb7d8638da9753f74cfc011 100644 (file)
--- 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 3f21a70e54ce572612f2f76bbecc0cd91c2031bf..6dfb20ace5cefb3e13b83a3ffe345a9b667d2826 100644 (file)
--- 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 52d3ea8b336c93aa522e591d2c213b630b90b381..df33a66784a69cc8f6c4a229fe84e86a9238c3c5 100644 (file)
--- 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