From patchwork Fri May 13 12:40:47 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Wakely X-Patchwork-Id: 53938 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 AF5C1395C006 for ; Fri, 13 May 2022 12:58:47 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org AF5C1395C006 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1652446727; bh=95nkM62cXd/P4LLJRlNNXzJyZGEX/PZukwhLiEqEqnk=; 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=iEQdqBcSMCBwTiZFbMTa0+aNMDtrVABw/YO0xNzIZ40o30qApWqfabUlr2zc35xQ3 zd3Qskn5+fZ8EJrTZEpRc09usFUChqJpcOrCUWHeFh3Pf7puN/jt7CmDaIaKUzUB+e kWnuxVd6/UK9ANJ3TRbnPgAp/bbwor0MDXLKLtwQ= 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 DD1BB395B41B for ; Fri, 13 May 2022 12:41:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org DD1BB395B41B 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-498-tmpRwK9wOM-OmSOaf8cdgw-1; Fri, 13 May 2022 08:40:59 -0400 X-MC-Unique: tmpRwK9wOM-OmSOaf8cdgw-1 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id BC9BE85A5A8; Fri, 13 May 2022 12:40:58 +0000 (UTC) Received: from localhost (unknown [10.33.36.192]) by smtp.corp.redhat.com (Postfix) with ESMTP id 63DC014E0B40; Fri, 13 May 2022 12:40:58 +0000 (UTC) To: libstdc++@gcc.gnu.org, gcc-patches@gcc.gnu.org Subject: [committed 09/12] libstdc++: Improve doxygen docs for algorithms and more Date: Fri, 13 May 2022 13:40:47 +0100 Message-Id: <20220513124050.4028450-9-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.85 on 10.11.54.7 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, KAM_SHORT, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham 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/bits/ostream_insert.h: Mark helper functions as undocumented by Doxygen. * include/bits/stl_algo.h: Use markdown for formatting and mark helper functions as undocumented. * include/bits/stl_numeric.h: Likewise. * include/bits/stl_pair.h (pair): Add @headerfile. --- libstdc++-v3/include/bits/ostream_insert.h | 4 + libstdc++-v3/include/bits/stl_algo.h | 198 +++++++++++---------- libstdc++-v3/include/bits/stl_numeric.h | 10 +- libstdc++-v3/include/bits/stl_pair.h | 4 + 4 files changed, 112 insertions(+), 104 deletions(-) diff --git a/libstdc++-v3/include/bits/ostream_insert.h b/libstdc++-v3/include/bits/ostream_insert.h index 9442ea130d3..f236353b2a6 100644 --- a/libstdc++-v3/include/bits/ostream_insert.h +++ b/libstdc++-v3/include/bits/ostream_insert.h @@ -40,6 +40,8 @@ namespace std _GLIBCXX_VISIBILITY(default) { _GLIBCXX_BEGIN_NAMESPACE_VERSION + /// @cond undocumented + template inline void __ostream_write(basic_ostream<_CharT, _Traits>& __out, @@ -124,6 +126,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #endif #endif + /// @endcond + _GLIBCXX_END_NAMESPACE_VERSION } // namespace std diff --git a/libstdc++-v3/include/bits/stl_algo.h b/libstdc++-v3/include/bits/stl_algo.h index 6619ff7bf1d..1d8ed4e5fa8 100644 --- a/libstdc++-v3/include/bits/stl_algo.h +++ b/libstdc++-v3/include/bits/stl_algo.h @@ -1617,6 +1617,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) __gnu_cxx::__ops::__pred_iter(__pred)); } + /// @cond undocumented + /// This is a helper function for the sort routines. template _GLIBCXX20_CONSTEXPR @@ -1671,6 +1673,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) return __result_real_last; } + /// @endcond + /** * @brief Copy the smallest elements of a sequence. * @ingroup sorting_algorithms @@ -1680,14 +1684,14 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) * @param __result_last Another random-access iterator. * @return An iterator indicating the end of the resulting sequence. * - * Copies and sorts the smallest N values from the range @p [__first,__last) - * to the range beginning at @p __result_first, where the number of - * elements to be copied, @p N, is the smaller of @p (__last-__first) and - * @p (__result_last-__result_first). - * After the sort if @e i and @e j are iterators in the range - * @p [__result_first,__result_first+N) such that i precedes j then - * *j<*i is false. - * The value returned is @p __result_first+N. + * Copies and sorts the smallest `N` values from the range + * `[__first, __last)` to the range beginning at `__result_first`, where + * the number of elements to be copied, `N`, is the smaller of + * `(__last - __first)` and `(__result_last - __result_first)`. + * After the sort if `i` and `j` are iterators in the range + * `[__result_first,__result_first + N)` such that `i` precedes `j` then + * `*j < *i` is false. + * The value returned is `__result_first + N`. */ template _GLIBCXX20_CONSTEXPR @@ -1730,14 +1734,14 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) * @param __comp A comparison functor. * @return An iterator indicating the end of the resulting sequence. * - * Copies and sorts the smallest N values from the range @p [__first,__last) - * to the range beginning at @p result_first, where the number of - * elements to be copied, @p N, is the smaller of @p (__last-__first) and - * @p (__result_last-__result_first). - * After the sort if @e i and @e j are iterators in the range - * @p [__result_first,__result_first+N) such that i precedes j then - * @p __comp(*j,*i) is false. - * The value returned is @p __result_first+N. + * Copies and sorts the smallest `N` values from the range + * `[__first, __last)` to the range beginning at `result_first`, where + * the number of elements to be copied, `N`, is the smaller of + * `(__last - __first)` and `(__result_last - __result_first)`. + * After the sort if `i` and `j` are iterators in the range + * `[__result_first, __result_first + N)` such that `i` precedes `j` then + * `__comp(*j, *i)` is false. + * The value returned is `__result_first + N`. */ template @@ -1774,6 +1778,8 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) __gnu_cxx::__ops::__iter_comp_iter(__comp)); } + /// @cond undocumented + /// This is a helper function for the sort routine. template _GLIBCXX20_CONSTEXPR @@ -1967,21 +1973,22 @@ _GLIBCXX_END_INLINE_ABI_NAMESPACE(_V2) std::__insertion_sort(__first, __last, __comp); } + /// @endcond + // nth_element // lower_bound moved to stl_algobase.h /** - * @brief Finds the first position in which @p __val could be inserted + * @brief Finds the first position in which `__val` could be inserted * without changing the ordering. * @ingroup binary_search_algorithms - * @param __first An iterator. - * @param __last Another iterator. + * @param __first An iterator to the start of a sorted range. + * @param __last A past-the-end iterator for the sorted range. * @param __val The search term. * @param __comp A functor to use for comparisons. - * @return An iterator pointing to the first element not less - * than @p __val, or end() if every element is less - * than @p __val. + * @return An iterator pointing to the first element _not less than_ + * `__val`, or `end()` if every element is less than `__val`. * @ingroup binary_search_algorithms * * The comparison function should have the same effects on ordering as @@ -4313,8 +4320,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __new_value The replacement value. * @return replace() returns no value. * - * For each iterator @c i in the range @p [__first,__last) if @c *i == - * @p __old_value then the assignment @c *i = @p __new_value is performed. + * For each iterator `i` in the range `[__first,__last)` if + * `*i == __old_value` then the assignment `*i = __new_value` is performed. */ template _GLIBCXX20_CONSTEXPR @@ -4346,8 +4353,8 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __new_value The replacement value. * @return replace_if() returns no value. * - * For each iterator @c i in the range @p [__first,__last) if @p __pred(*i) - * is true then the assignment @c *i = @p __new_value is performed. + * For each iterator `i` in the range `[__first,__last)` if `__pred(*i)` + * is true then the assignment `*i = __new_value` is performed. */ template _GLIBCXX20_CONSTEXPR @@ -4375,12 +4382,11 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @ingroup mutating_algorithms * @param __first A forward iterator. * @param __last A forward iterator. - * @param __gen A function object taking no arguments and returning - * std::iterator_traits<_ForwardIterator>::value_type + * @param __gen A function object callable with no arguments. * @return generate() returns no value. * - * Performs the assignment @c *i = @p __gen() for each @c i in the range - * @p [__first,__last). + * Performs the assignment `*i = __gen()` for each `i` in the range + * `[__first, __last)`. */ template _GLIBCXX20_CONSTEXPR @@ -4404,14 +4410,13 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @ingroup mutating_algorithms * @param __first A forward iterator. * @param __n The length of the sequence. - * @param __gen A function object taking no arguments and returning - * std::iterator_traits<_ForwardIterator>::value_type - * @return The end of the sequence, @p __first+__n + * @param __gen A function object callable with no arguments. + * @return The end of the sequence, i.e., `__first + __n` * - * Performs the assignment @c *i = @p __gen() for each @c i in the range - * @p [__first,__first+__n). + * Performs the assignment `*i = __gen()` for each `i` in the range + * `[__first, __first + __n)`. * - * If @p __n is negative, the function does nothing and returns @p __first. + * If `__n` is negative, the function does nothing and returns `__first`. */ // _GLIBCXX_RESOLVE_LIB_DEFECTS // DR 865. More algorithms that throw away information @@ -4441,19 +4446,16 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __result An output iterator. * @return An iterator designating the end of the resulting sequence. * - * Copies each element in the range @p [__first,__last) to the range - * beginning at @p __result, except that only the first element is copied + * Copies each element in the range `[__first, __last)` to the range + * beginning at `__result`, except that only the first element is copied * from groups of consecutive elements that compare equal. - * unique_copy() is stable, so the relative order of elements that are + * `unique_copy()` is stable, so the relative order of elements that are * copied is unchanged. - * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 241. Does unique_copy() require CopyConstructible and Assignable? - * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 538. 241 again: Does unique_copy() require CopyConstructible and - * Assignable? - */ + */ + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 241. Does unique_copy() require CopyConstructible and Assignable? + // DR 538. 241 again: Does unique_copy() require CopyConstructible and + // Assignable? template _GLIBCXX20_CONSTEXPR inline _OutputIterator @@ -4485,16 +4487,15 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __binary_pred A binary predicate. * @return An iterator designating the end of the resulting sequence. * - * Copies each element in the range @p [__first,__last) to the range - * beginning at @p __result, except that only the first element is copied - * from groups of consecutive elements for which @p __binary_pred returns + * Copies each element in the range `[__first, __last)` to the range + * beginning at `__result`, except that only the first element is copied + * from groups of consecutive elements for which `__binary_pred` returns * true. - * unique_copy() is stable, so the relative order of elements that are + * `unique_copy()` is stable, so the relative order of elements that are * copied is unchanged. - * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 241. Does unique_copy() require CopyConstructible and Assignable? - */ + */ + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 241. Does unique_copy() require CopyConstructible and Assignable? template _GLIBCXX20_CONSTEXPR @@ -4526,7 +4527,7 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __last A forward iterator. * @return Nothing. * - * Reorder the elements in the range @p [__first,__last) using a random + * Reorder the elements in the range `[__first, __last)` using a random * distribution, so that every possible ordering of the sequence is * equally likely. * @@ -4565,10 +4566,10 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __rand The RNG functor or function. * @return Nothing. * - * Reorders the elements in the range @p [__first,__last) using @p __rand to - * provide a random distribution. Calling @p __rand(N) for a positive - * integer @p N should return a randomly chosen integer from the - * range [0,N). + * Reorders the elements in the range `[__first, __last)` using `__rand` + * to provide a random distribution. Calling `__rand(N)` for a positive + * integer `N` should return a randomly chosen integer from the + * range `[0, N)`. * * @deprecated * Since C++14 `std::random_shuffle` is not part of the C++ standard. @@ -4607,13 +4608,13 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __first A forward iterator. * @param __last A forward iterator. * @param __pred A predicate functor. - * @return An iterator @p middle such that @p __pred(i) is true for each - * iterator @p i in the range @p [__first,middle) and false for each @p i - * in the range @p [middle,__last). + * @return An iterator `middle` such that `__pred(i)` is true for each + * iterator `i` in the range `[__first, middle)` and false for each `i` + * in the range `[middle, __last)`. * - * @p __pred must not modify its operand. @p partition() does not preserve + * `__pred` must not modify its operand. `partition()` does not preserve * the relative ordering of elements in each group, use - * @p stable_partition() if this is needed. + * `stable_partition()` if this is needed. */ template _GLIBCXX20_CONSTEXPR @@ -4641,13 +4642,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __last Another iterator. * @return Nothing. * - * Sorts the smallest @p (__middle-__first) elements in the range - * @p [first,last) and moves them to the range @p [__first,__middle). The - * order of the remaining elements in the range @p [__middle,__last) is - * undefined. - * After the sort if @e i and @e j are iterators in the range - * @p [__first,__middle) such that i precedes j and @e k is an iterator in - * the range @p [__middle,__last) then *j<*i and *k<*i are both false. + * Sorts the smallest `(__middle - __first)` elements in the range + * `[first, last)` and moves them to the range `[__first, __middle)`. The + * order of the remaining elements in the range `[__middle, __last)` is + * unspecified. + * After the sort if `i` and `j` are iterators in the range + * `[__first, __middle)` such that `i` precedes `j` and `k` is an iterator + * in the range `[__middle, __last)` then `*j < *i` and `*k < *i` are + * both false. */ template _GLIBCXX20_CONSTEXPR @@ -4679,14 +4681,14 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __comp A comparison functor. * @return Nothing. * - * Sorts the smallest @p (__middle-__first) elements in the range - * @p [__first,__last) and moves them to the range @p [__first,__middle). The - * order of the remaining elements in the range @p [__middle,__last) is - * undefined. - * After the sort if @e i and @e j are iterators in the range - * @p [__first,__middle) such that i precedes j and @e k is an iterator in - * the range @p [__middle,__last) then @p *__comp(j,*i) and @p __comp(*k,*i) - * are both false. + * Sorts the smallest `(__middle - __first)` elements in the range + * `[__first, __last)` and moves them to the range `[__first, __middle)`. + * The order of the remaining elements in the range `[__middle, __last)` is + * unspecified. + * After the sort if `i` and `j` are iterators in the range + * `[__first, __middle)` such that `i` precedes `j` and `k` is an iterator + * in the range `[__middle, __last)` then `*__comp(j, *i)` and + * `__comp(*k, *i)` are both false. */ template _GLIBCXX20_CONSTEXPR @@ -4718,12 +4720,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __last Another iterator. * @return Nothing. * - * Rearranges the elements in the range @p [__first,__last) so that @p *__nth + * Rearranges the elements in the range `[__first, __last)` so that `*__nth` * is the same element that would have been in that position had the - * whole sequence been sorted. The elements either side of @p *__nth are - * not completely sorted, but for any iterator @e i in the range - * @p [__first,__nth) and any iterator @e j in the range @p [__nth,__last) it - * holds that *j < *i is false. + * whole sequence been sorted. The elements either side of `*__nth` are + * not completely sorted, but for any iterator `i` in the range + * `[__first, __nth)` and any iterator `j` in the range `[__nth, __last)` it + * holds that `*j < *i` is false. */ template _GLIBCXX20_CONSTEXPR @@ -4758,12 +4760,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __comp A comparison functor. * @return Nothing. * - * Rearranges the elements in the range @p [__first,__last) so that @p *__nth + * Rearranges the elements in the range `[__first, __last)` so that `*__nth` * is the same element that would have been in that position had the - * whole sequence been sorted. The elements either side of @p *__nth are - * not completely sorted, but for any iterator @e i in the range - * @p [__first,__nth) and any iterator @e j in the range @p [__nth,__last) it - * holds that @p __comp(*j,*i) is false. + * whole sequence been sorted. The elements either side of `*__nth` are + * not completely sorted, but for any iterator `i` in the range + * `[__first, __nth)` and any iterator `j` in the range `[__nth, __last)` + * it holds that `__comp(*j, *i)` is false. */ template _GLIBCXX20_CONSTEXPR @@ -4796,12 +4798,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __last Another iterator. * @return Nothing. * - * Sorts the elements in the range @p [__first,__last) in ascending order, - * such that for each iterator @e i in the range @p [__first,__last-1), - * *(i+1)<*i is false. + * Sorts the elements in the range `[__first, __last)` in ascending order, + * such that for each iterator `i` in the range `[__first, __last - 1)`, + * `*(i+1) < *i` is false. * * The relative ordering of equivalent elements is not preserved, use - * @p stable_sort() if this is needed. + * `stable_sort()` if this is needed. */ template _GLIBCXX20_CONSTEXPR @@ -4827,12 +4829,12 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __comp A comparison functor. * @return Nothing. * - * Sorts the elements in the range @p [__first,__last) in ascending order, - * such that @p __comp(*(i+1),*i) is false for every iterator @e i in the - * range @p [__first,__last-1). + * Sorts the elements in the range `[__first, __last)` in ascending order, + * such that `__comp(*(i+1), *i)` is false for every iterator `i` in the + * range `[__first, __last - 1)`. * * The relative ordering of equivalent elements is not preserved, use - * @p stable_sort() if this is needed. + * `stable_sort()` if this is needed. */ template _GLIBCXX20_CONSTEXPR diff --git a/libstdc++-v3/include/bits/stl_numeric.h b/libstdc++-v3/include/bits/stl_numeric.h index ea017d41e76..f71236cab5d 100644 --- a/libstdc++-v3/include/bits/stl_numeric.h +++ b/libstdc++-v3/include/bits/stl_numeric.h @@ -328,10 +328,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __last End of input range. * @param __result Output sums. * @return Iterator pointing just beyond the values written to result. - * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 539. partial_sum and adjacent_difference should mention requirements */ + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 539. partial_sum and adjacent_difference should mention requirements template _GLIBCXX20_CONSTEXPR _OutputIterator @@ -371,10 +370,9 @@ _GLIBCXX_BEGIN_NAMESPACE_ALGO * @param __result Output sum. * @param __binary_op Function object. * @return Iterator pointing just beyond the values written to result. - * - * _GLIBCXX_RESOLVE_LIB_DEFECTS - * DR 539. partial_sum and adjacent_difference should mention requirements */ + // _GLIBCXX_RESOLVE_LIB_DEFECTS + // DR 539. partial_sum and adjacent_difference should mention requirements template _GLIBCXX20_CONSTEXPR diff --git a/libstdc++-v3/include/bits/stl_pair.h b/libstdc++-v3/include/bits/stl_pair.h index 0eb78345ca4..831e770d54b 100644 --- a/libstdc++-v3/include/bits/stl_pair.h +++ b/libstdc++-v3/include/bits/stl_pair.h @@ -180,6 +180,8 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @tparam _T2 Type of second object. * * + * + * @headerfile utility */ template struct pair @@ -757,9 +759,11 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION #if __cplusplus >= 201103L // Various functions which give std::pair a tuple-like interface. + /// @cond undocumented template struct __is_tuple_like_impl> : true_type { }; + /// @endcond /// Partial specialization for std::pair template