From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: 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 7C432395B41F for ; Fri, 13 May 2022 12:41:00 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 7C432395B41F Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-442-MXP_FyMsNlilsDBg8oVI9A-1; Fri, 13 May 2022 08:40:58 -0400 X-MC-Unique: MXP_FyMsNlilsDBg8oVI9A-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id C1B7E1C05AF5; Fri, 13 May 2022 12:40:57 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 88A5E2026D6A; Fri, 13 May 2022 12:40:57 +0000 (UTC) From: Jonathan Wakely To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 08/12] libstdc++: Improve doxygen docs for std::allocator Date: Fri, 13 May 2022 13:40:46 +0100 Message-Id: <20220513124050.4028450-8-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.4 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain Content-Transfer-Encoding: 8bit X-Spam-Status: No, score=-13.0 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: libstdc++@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libstdc++ mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 13 May 2022 12:41:02 -0000 Tested powerpc64le-linux, pushed to trunk. -- >8 -- libstdc++-v3/ChangeLog: * doc/doxygen/user.cfg.in (PREDEFINED): Define __allocator_base so that Doxygen shows the right base-class for std::allocator. * include/bits/alloc_traits.h: Improve doxygen docs. * include/bits/allocator.h: Likewise. * include/bits/new_allocator.h: Likewise. * include/ext/new_allocator.h: Likewise. --- libstdc++-v3/doc/doxygen/user.cfg.in | 1 + libstdc++-v3/include/bits/alloc_traits.h | 5 +++++ libstdc++-v3/include/bits/allocator.h | 15 ++++++++++++++- libstdc++-v3/include/bits/new_allocator.h | 19 +++++++++++++------ libstdc++-v3/include/ext/new_allocator.h | 12 +++++++++--- 5 files changed, 42 insertions(+), 10 deletions(-) diff --git a/libstdc++-v3/doc/doxygen/user.cfg.in b/libstdc++-v3/doc/doxygen/user.cfg.in index 02ce290d3ad..cfda7ab13c4 100644 --- a/libstdc++-v3/doc/doxygen/user.cfg.in +++ b/libstdc++-v3/doc/doxygen/user.cfg.in @@ -2405,6 +2405,7 @@ PREDEFINED = __cplusplus=202002L \ _GLIBCXX_HAVE_IS_CONSTANT_EVALUATED \ _GLIBCXX_HAVE_BUILTIN_LAUNDER \ "_GLIBCXX_DOXYGEN_ONLY(X)=X " \ + __allocator_base=std::__new_allocator \ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/libstdc++-v3/include/bits/alloc_traits.h b/libstdc++-v3/include/bits/alloc_traits.h index a4d06d3fc7a..f9ca37fd7d6 100644 --- a/libstdc++-v3/include/bits/alloc_traits.h +++ b/libstdc++-v3/include/bits/alloc_traits.h @@ -661,6 +661,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return __rhs; } }; + /// @cond undocumented #if __cplusplus < 201703L template inline void @@ -818,8 +819,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION __a.deallocate(__a.allocate(1u), 1u); }; #endif + /// @endcond #endif // C++11 + /// @cond undocumented + /** * Destroy a range of objects using the supplied allocator. For * non-default allocators we do not optimize away invocation of @@ -849,6 +853,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { _Destroy(__first, __last); } + /// @endcond _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/bits/allocator.h b/libstdc++-v3/include/bits/allocator.h index f7770165273..ee1121b080a 100644 --- a/libstdc++-v3/include/bits/allocator.h +++ b/libstdc++-v3/include/bits/allocator.h @@ -67,7 +67,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION // explicit specialization, with the historical ABI properties, but with // the same members that are present in the primary template. - /// allocator specialization. + /** std::allocator specialization. + * + * @headerfile memory + */ template<> class allocator { @@ -119,6 +122,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * for further details. * * @tparam _Tp Type of allocated object. + * + * @headerfile memory */ template class allocator : public __allocator_base<_Tp> @@ -209,6 +214,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION // Inherit everything else. }; + /** Equality comparison for std::allocator objects + * + * @return true, for all std::allocator objects. + * @relates std::allocator + */ template inline _GLIBCXX20_CONSTEXPR bool operator==(const allocator<_T1>&, const allocator<_T2>&) @@ -223,6 +233,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { return false; } #endif + /// @cond undocumented + // Invalid allocator partial specializations. // allocator_traits::rebind_alloc can be used to form a valid allocator type. template @@ -325,6 +337,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION } }; #endif + /// @endcond _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/bits/new_allocator.h b/libstdc++-v3/include/bits/new_allocator.h index 20ef20fe118..1a5bc51b956 100644 --- a/libstdc++-v3/include/bits/new_allocator.h +++ b/libstdc++-v3/include/bits/new_allocator.h @@ -43,14 +43,21 @@ namespace std _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @brief An allocator that uses global new, as per C++03 [20.4.1]. - * @ingroup allocators + * @brief An allocator that uses global `new`, as per C++03 [20.4.1]. + * @ingroup allocators * - * This is precisely the allocator defined in the C++ Standard. - * - all allocation calls operator new - * - all deallocation calls operator delete + * This is precisely the allocator defined in the C++ Standard. + * - all allocation calls `operator new` + * - all deallocation calls `operator delete` * - * @tparam _Tp Type of allocated object. + * This is the default base-class implementation of `std::allocator`, + * and is also the base-class of the `__gnu_cxx::new_allocator` extension. + * You should use either `std::allocator` or `__gnu_cxx::new_allocator` + * instead of using this directly. + * + * @tparam _Tp Type of allocated object. + * + * @headerfile memory */ template class __new_allocator diff --git a/libstdc++-v3/include/ext/new_allocator.h b/libstdc++-v3/include/ext/new_allocator.h index b8f5fcccccc..96e6523977a 100644 --- a/libstdc++-v3/include/ext/new_allocator.h +++ b/libstdc++-v3/include/ext/new_allocator.h @@ -36,14 +36,20 @@ namespace __gnu_cxx _GLIBCXX_VISIBILITY(default) _GLIBCXX_BEGIN_NAMESPACE_VERSION /** - * @brief An allocator that uses global new, as per C++03 [20.4.1]. + * @brief An allocator that uses global `new`, as per C++03 [20.4.1]. * @ingroup allocators * * This is precisely the allocator defined in the C++ Standard. - * - all allocation calls operator new - * - all deallocation calls operator delete + * - all allocation calls `operator new` + * - all deallocation calls `operator delete` + * + * This is a non-standard extension that can be used to guarantee + * allocation from `new` even if the library has been configured to + * use a different implementation for `std::allocator`. * * @tparam _Tp Type of allocated object. + * + * @headerfile ext/new_allocator.h */ template class new_allocator : public std::__new_allocator<_Tp> -- 2.34.1