From patchwork Fri May 13 12:40:43 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53934 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 7F27C395BC12 for ; Fri, 13 May 2022 12:51:57 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 7F27C395BC12 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446317; bh=F++HGcVSW4I+gJh5z7bF9DYihCjujI+2hFPJXg/5xak=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=Kp7HAfMHawXaiDMXFC4nnJZB4ydW/aDR5vDTL9r/fcj+I6/okoocBd56wgnu6Sd7J nhrbsay8NUHTTya2VKTwzmW8qCrQB5Oiyyg+Egbn5rQYei6TXM+WmecH4rDTZ4ImC8 R+IpKtR1D+nrtczyXKM2WCAhQh1Of09dsC7e+9fg= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTPS id D80CF395B416 for ; Fri, 13 May 2022 12:40:59 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org D80CF395B416 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-578-woJLAXYxM-SlX8Gbtlsccg-1; Fri, 13 May 2022 08:40:55 -0400 X-MC-Unique: woJLAXYxM-SlX8Gbtlsccg-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 1C42985A5BE; Fri, 13 May 2022 12:40:55 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id BDA261121330; Fri, 13 May 2022 12:40:54 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 05/12] libstdc++: Improve doxygen docs for Date: Fri, 13 May 2022 13:40:43 +0100 Message-Id: <20220513124050.4028450-5-jwakely@redhat.com> In-Reply-To: <20220513124050.4028450-1-jwakely@redhat.com> References: <20220513124050.4028450-1-jwakely@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.78 on 10.11.54.3 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-12.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=unavailable autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Jonathan Wakely via Gcc-patches From: Jonathan Wakely Reply-To: Jonathan Wakely Errors-To: gcc-patches-bounces+patchwork=sourceware.org@gcc.gnu.org Sender: "Gcc-patches" Tested powerpc64le-linux, pushed to trunk. -- >8 -- libstdc++-v3/ChangeLog: * include/std/system_error: Improve doxygen comments. --- libstdc++-v3/include/std/system_error | 136 ++++++++++++++++++++------ 1 file changed, 107 insertions(+), 29 deletions(-) diff --git a/libstdc++-v3/include/std/system_error b/libstdc++-v3/include/std/system_error index dcef94e16e2..95508da73dd 100644 --- a/libstdc++-v3/include/std/system_error +++ b/libstdc++-v3/include/std/system_error @@ -85,13 +85,20 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2) /** Abstract base class for types defining a category of error codes. * - * An error category defines a context that give meaning to the integer + * An error category defines a context that gives meaning to the integer * stored in an `error_code` or `error_condition` 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. * + * A user-defined category can override the `equivalent` member functions + * to define correspondence between errors in different categories. + * For example, a category for errors from disk I/O could consider some + * of its error numbers equivalent to ENOSPC and ENOENT in the generic + * category. + * + * @headerfile system_error * @since C++11 */ class error_category @@ -104,6 +111,7 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2) error_category(const error_category&) = delete; error_category& operator=(const error_category&) = delete; + /// A string that identifies the error category. virtual const char* name() const noexcept = 0; @@ -118,6 +126,7 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2) _M_message(int) const; public: + /// A description of the error condition corresponding to the number. _GLIBCXX_DEFAULT_ABI_TAG virtual string message(int) const = 0; @@ -131,31 +140,36 @@ _GLIBCXX_BEGIN_INLINE_ABI_NAMESPACE(_V2) #endif public: + /// Return an error_condition corresponding to `i` in this category. virtual error_condition default_error_condition(int __i) const noexcept; + /// Test whether `cond` corresponds to `i` for this category. virtual bool equivalent(int __i, const error_condition& __cond) const noexcept; + /// Test whether `code` corresponds to `i` for this category. virtual bool equivalent(const error_code& __code, int __i) const noexcept; + /// An error_category only compares equal to itself. bool operator==(const error_category& __other) const noexcept { return this == &__other; } + /// Ordered comparison that defines a total order for error categories. #if __cpp_lib_three_way_comparison strong_ordering operator<=>(const error_category& __rhs) const noexcept { return std::compare_three_way()(this, &__rhs); } #else - bool - operator!=(const error_category& __other) const noexcept - { return this != &__other; } - bool operator<(const error_category& __other) const noexcept { return less()(this, &__other); } + + bool + operator!=(const error_category& __other) const noexcept + { return this != &__other; } #endif }; @@ -191,8 +205,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) * library might be represented by an HTTP response status code (e.g. 404) * and a custom category defined by the library. * + * @headerfile system_error * @since C++11 - * @ingroup diagnostics */ class error_code { @@ -226,20 +240,25 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) operator=(_ErrorCodeEnum __e) noexcept { return *this = make_error_code(__e); } + /// The error value. int value() const noexcept { return _M_value; } + /// The error category that this error belongs to. const error_category& category() const noexcept { return *_M_cat; } + /// An `error_condition` for this error's category and value. error_condition default_error_condition() const noexcept; + /// The category's description of the value. _GLIBCXX_DEFAULT_ABI_TAG string message() const { return category().message(value()); } + /// Test whether `value()` is non-zero. explicit operator bool() const noexcept { return _M_value != 0; } @@ -249,14 +268,28 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) const error_category* _M_cat; }; - // 19.4.2.6 non-member functions - - /// @relates error_code @{ + // C++11 19.5.2.5 non-member functions + /** Create an `error_code` representing a standard `errc` condition. + * + * The `std::errc` constants correspond to `errno` macros and so use the + * generic category. + * + * @relates error_code + * @since C++11 + */ inline error_code make_error_code(errc __e) noexcept { return error_code(static_cast(__e), generic_category()); } + /** Ordered comparison for std::error_code. + * + * This defines a total order by comparing the categories, and then + * if they are equal comparing the values. + * + * @relates error_code + * @since C++11 + */ #if __cpp_lib_three_way_comparison inline strong_ordering operator<=>(const error_code& __lhs, const error_code& __rhs) noexcept @@ -275,13 +308,16 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) } #endif + /** Write a std::error_code to an ostream. + * + * @relates error_code + * @since C++11 + */ template basic_ostream<_CharT, _Traits>& operator<<(basic_ostream<_CharT, _Traits>& __os, const error_code& __e) { return (__os << __e.category().name() << ':' << __e.value()); } - /// @} - error_condition make_error_condition(errc) noexcept; /** Class error_condition @@ -293,14 +329,17 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) * An `error_condition` represents something that the program can test for, * and subsequently take appropriate action. * + * @headerfile system_error * @since C++11 */ class error_condition { public: + /// Initialize with a zero (no error) value and the generic category. error_condition() noexcept : _M_value(0), _M_cat(&generic_category()) { } + /// Initialize with the specified value and category. error_condition(int __v, const error_category& __cat) noexcept : _M_value(__v), _M_cat(&__cat) { } @@ -309,6 +348,7 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) error_condition(_ErrorConditionEnum __e) noexcept { *this = make_error_condition(__e); } + /// Set the value and category. void assign(int __v, const error_category& __cat) noexcept { @@ -323,22 +363,28 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) operator=(_ErrorConditionEnum __e) noexcept { return *this = make_error_condition(__e); } + /// Reset the value and category to the default-constructed state. void clear() noexcept { assign(0, generic_category()); } - // 19.4.3.4 observers + // C++11 19.5.3.4 observers + + /// The error value. int value() const noexcept { return _M_value; } + /// The error category that this error belongs to. const error_category& category() const noexcept { return *_M_cat; } + /// The category's description of the value. _GLIBCXX_DEFAULT_ABI_TAG string message() const { return category().message(value()); } + /// Test whether `value()` is non-zero. explicit operator bool() const noexcept { return _M_value != 0; } @@ -348,42 +394,75 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) const error_category* _M_cat; }; - // 19.4.3.6 non-member functions + // C++11 19.5.3.5 non-member functions - /// Create an `error_condition` representing a standard `errc` condition. - /// @relates error_condition + /** Create an `error_condition` representing a standard `errc` condition. + * + * The `std::errc` constants correspond to `errno` macros and so use the + * generic category. + * + * @relates error_condition + * @since C++11 + */ inline error_condition make_error_condition(errc __e) noexcept { return error_condition(static_cast(__e), generic_category()); } - // 19.4.4 Comparison operators + // C++11 19.5.4 Comparison operators - /// @relates error_code + /** Equality comparison for std::error_code. + * + * Returns true only if they have the same category and the same value. + * + * @relates error_condition + * @since C++11 + */ inline bool operator==(const error_code& __lhs, const error_code& __rhs) noexcept - { return (__lhs.category() == __rhs.category() - && __lhs.value() == __rhs.value()); } + { + return __lhs.category() == __rhs.category() + && __lhs.value() == __rhs.value(); + } - /// @relates error_code + /** Equality comparison for std::error_code and std::error_condition. + * + * Uses each category's `equivalent` member function to check whether + * the values correspond to an equivalent error in that category. + * + * @relates error_condition + * @since C++11 + */ inline bool operator==(const error_code& __lhs, const error_condition& __rhs) noexcept { - return (__lhs.category().equivalent(__lhs.value(), __rhs) - || __rhs.category().equivalent(__lhs, __rhs.value())); + return __lhs.category().equivalent(__lhs.value(), __rhs) + || __rhs.category().equivalent(__lhs, __rhs.value()); } - /// @relates error_condition + /** Equality comparison for std::error_condition. + * + * Returns true only if they have the same category and the same value. + * + * @relates error_condition + * @since C++11 + */ inline bool operator==(const error_condition& __lhs, const error_condition& __rhs) noexcept { - return (__lhs.category() == __rhs.category() - && __lhs.value() == __rhs.value()); + return __lhs.category() == __rhs.category() + && __lhs.value() == __rhs.value(); } + /** Ordered comparison for std::error_condition. + * + * This defines a total order by comparing the categories, and then + * if they are equal comparing the values. + * + * @relates error_condition + * @since C++11 + */ #if __cpp_lib_three_way_comparison - /// Define an ordering for error_condition objects. - /// @relates error_condition inline strong_ordering operator<=>(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -393,8 +472,6 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) return __lhs.value() <=> __rhs.value(); } #else - /// Define an ordering for error_condition objects. - /// @relates error_condition inline bool operator<(const error_condition& __lhs, const error_condition& __rhs) noexcept @@ -441,6 +518,7 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) * Typically used to report errors from the operating system and other * low-level APIs. * + * @headerfile system_error * @since C++11 * @ingroup exceptions */