{"id":2231804,"url":"http://patchwork.ozlabs.org/api/1.1/patches/2231804/?format=json","web_url":"http://patchwork.ozlabs.org/project/gcc/patch/20260501123235.2541613-1-jwakely@redhat.com/","project":{"id":17,"url":"http://patchwork.ozlabs.org/api/1.1/projects/17/?format=json","name":"GNU Compiler Collection","link_name":"gcc","list_id":"gcc-patches.gcc.gnu.org","list_email":"gcc-patches@gcc.gnu.org","web_url":null,"scm_url":null,"webscm_url":null},"msgid":"<20260501123235.2541613-1-jwakely@redhat.com>","date":"2026-05-01T12:32:01","name":"[committed,1/3] libstdc++: Improve Doxygen comments for contents","commit_ref":null,"pull_url":null,"state":"new","archived":false,"hash":"99d274fec58eab681b7cc8a2064a188732a7cb7b","submitter":{"id":48004,"url":"http://patchwork.ozlabs.org/api/1.1/people/48004/?format=json","name":"Jonathan Wakely","email":"jwakely@redhat.com"},"delegate":null,"mbox":"http://patchwork.ozlabs.org/project/gcc/patch/20260501123235.2541613-1-jwakely@redhat.com/mbox/","series":[{"id":502455,"url":"http://patchwork.ozlabs.org/api/1.1/series/502455/?format=json","web_url":"http://patchwork.ozlabs.org/project/gcc/list/?series=502455","date":"2026-05-01T12:32:01","name":"[committed,1/3] libstdc++: Improve Doxygen comments for contents","version":1,"mbox":"http://patchwork.ozlabs.org/series/502455/mbox/"}],"comments":"http://patchwork.ozlabs.org/api/patches/2231804/comments/","check":"pending","checks":"http://patchwork.ozlabs.org/api/patches/2231804/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":["incoming@patchwork.ozlabs.org","gcc-patches@gcc.gnu.org"],"Delivered-To":["patchwork-incoming@legolas.ozlabs.org","gcc-patches@gcc.gnu.org"],"Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=NWil6dn1;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org\n (client-ip=2620:52:6:3111::32; helo=vm01.sourceware.org;\n envelope-from=gcc-patches-bounces~incoming=patchwork.ozlabs.org@gcc.gnu.org;\n receiver=patchwork.ozlabs.org)","sourceware.org;\n\tdkim=pass (1024-bit key,\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=NWil6dn1","sourceware.org; dmarc=pass (p=quarantine dis=none)\n header.from=redhat.com","sourceware.org; spf=pass smtp.mailfrom=redhat.com","server2.sourceware.org;\n arc=none smtp.remote-ip=170.10.133.124"],"Received":["from vm01.sourceware.org (vm01.sourceware.org\n [IPv6:2620:52:6:3111::32])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519 server-signature ECDSA (secp384r1) server-digest SHA384)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g6VnW3Wdnz1yHZ\n\tfor ; Fri, 01 May 2026 22:33:17 +1000 (AEST)","from vm01.sourceware.org (localhost [127.0.0.1])\n\tby sourceware.org (Postfix) with ESMTP id 87482437423D\n\tfor ; Fri, 1 May 2026 12:33:15 +0000 (GMT)","from us-smtp-delivery-124.mimecast.com\n (us-smtp-delivery-124.mimecast.com [170.10.133.124])\n by sourceware.org (Postfix) with ESMTP id 262694BABF08\n for ; Fri, 1 May 2026 12:32:42 +0000 (GMT)","from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com\n (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by\n relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3,\n cipher=TLS_AES_256_GCM_SHA384) id us-mta-578-6lmfKkJNM0KHBINbHU_NGg-1; Fri,\n 01 May 2026 08:32:38 -0400","from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com\n (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest\n SHA256)\n (No client certificate requested)\n by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS\n id D723E195608F; Fri, 1 May 2026 12:32:37 +0000 (UTC)","from zen.kayari.org (unknown [10.44.50.237])\n by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP\n id C646A1955D84; Fri, 1 May 2026 12:32:36 +0000 (UTC)"],"DKIM-Filter":["OpenDKIM Filter v2.11.0 sourceware.org 87482437423D","OpenDKIM Filter v2.11.0 sourceware.org 262694BABF08"],"DMARC-Filter":"OpenDMARC Filter v1.4.2 sourceware.org 262694BABF08","ARC-Filter":"OpenARC Filter v1.0.0 sourceware.org 262694BABF08","ARC-Seal":"i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1777638762; cv=none;\n b=JLStokxWMdpjc/znQqzSxIrNdzCJ2YnyLUHjqNt7ODjp6CeRzUHloq53MRLiBJFUdbNIOvLpzP3LFSMu1Xw+6wKD7hjtXLENT14oSM0RvsRLgIxAHe5bXvEEMof5qtgA8W+0X5pSR7liFsdVAfqR+q27Ip7zsPILy8DkAMDYXxo=","ARC-Message-Signature":"i=1; a=rsa-sha256; d=sourceware.org; s=key;\n t=1777638762; c=relaxed/simple;\n bh=MTDMcAWXrUrY5YrEO44wCiUyXULX7kb7PRW7x0+TnBE=;\n h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version;\n b=s/i4NmgNcA6B3zjYuJIa7jWVoRQaNqmvoczIsRcWlX+JYc3UHbMDaGTB8IwDcnttxpZvrPbaJim0VNJjOh0vO22FzfffUjGkT9eDNlYyEtjra7F8N+2nfZNsYZ5vJSdsuul7+V4zBy+PKAkGpa/1703YoQgKnrbzG6/Mx/RpySU=","ARC-Authentication-Results":"i=1; server2.sourceware.org","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1777638761;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:mime-version:mime-version:content-type:content-type:\n content-transfer-encoding:content-transfer-encoding;\n bh=uq3wiNFbHo9iUn4DPbbQYTX8EHNV1thPa5SJqdl/hjo=;\n b=NWil6dn1hGwYq3T0F1oXDr4AjJc72h3d4j/1nZR82AMdW/doUrzSF8tllGCPIRDnSHyZ3R\n AWxHRg3PSVMGGm4W78Uvi35nX90i4DLw9Z2hsNZjUWxHVouJ0toU9LNWwTvRLvpdFUfI1z\n PBbAXj7T10rFTNhdbUK15WHMNG+59bs=","X-MC-Unique":"6lmfKkJNM0KHBINbHU_NGg-1","X-Mimecast-MFC-AGG-ID":"6lmfKkJNM0KHBINbHU_NGg_1777638758","From":"Jonathan Wakely ","To":"gcc-patches@gcc.gnu.org,\n\tlibstdc++@gcc.gnu.org","Subject":"[committed 1/3] libstdc++: Improve Doxygen comments for \n contents","Date":"Fri, 1 May 2026 13:32:01 +0100","Message-ID":"<20260501123235.2541613-1-jwakely@redhat.com>","MIME-Version":"1.0","X-Scanned-By":"MIMEDefang 3.0 on 10.30.177.17","X-Mimecast-Spam-Score":"0","X-Mimecast-MFC-PROC-ID":"syWYZH6WwC4A2Snb8-q057gbWTnf_T1ABKvU--86qVA_1777638758","X-Mimecast-Originator":"redhat.com","Content-Type":"text/plain","Content-Transfer-Encoding":"8bit","X-BeenThere":"gcc-patches@gcc.gnu.org","X-Mailman-Version":"2.1.30","Precedence":"list","List-Id":"Gcc-patches mailing list ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"gcc-patches-bounces~incoming=patchwork.ozlabs.org@gcc.gnu.org"},"content":"Use markdown and suppress unwanted docs for internal helpers.\n\nlibstdc++-v3/ChangeLog:\n\n\t* include/bits/stl_iterator.h: Prevent Doxygen from documenting\n\tnamespace __detail as part of the Iterators topic.\n\t* include/bits/stl_iterator_base_funcs.h: Likewise. Also mark\n\tinternal helpers as undocumented.\n\t(distance, advance): Improve Doxygen comments.\n\t* include/bits/stl_iterator_base_types.h (iterator): Use\n\tmarkdown in Doxygen comment. Add @deprecated.\n\t(iterator_traits): Improve wording of Doxygen comment.\n---\n\nTested x86_64-linux. Pushed to trunk.\n\n libstdc++-v3/include/bits/stl_iterator.h | 4 +++\n .../include/bits/stl_iterator_base_funcs.h | 32 +++++++++++++------\n .../include/bits/stl_iterator_base_types.h | 17 ++++++----\n 3 files changed, 37 insertions(+), 16 deletions(-)","diff":"diff --git a/libstdc++-v3/include/bits/stl_iterator.h b/libstdc++-v3/include/bits/stl_iterator.h\nindex 6439deb608a6..ea083543c1d4 100644\n--- a/libstdc++-v3/include/bits/stl_iterator.h\n+++ b/libstdc++-v3/include/bits/stl_iterator.h\n@@ -2619,6 +2619,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n \n template class basic_const_iterator;\n \n+ /// @cond undocumented\n namespace __detail\n {\n template\n@@ -2646,11 +2647,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n struct __basic_const_iterator_iter_cat<_It>\n { using iterator_category = __iter_category_t<_It>; };\n } // namespace detail\n+ /// @endcond\n \n template\n using const_iterator\n = __conditional_t<__detail::__constant_iterator<_It>, _It, basic_const_iterator<_It>>;\n \n+ /// @cond undocumented\n namespace __detail\n {\n template\n@@ -2661,6 +2664,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n struct __const_sentinel<_Sent>\n { using type = const_iterator<_Sent>; };\n } // namespace __detail\n+ /// @endcond\n \n template\n using const_sentinel = typename __detail::__const_sentinel<_Sent>::type;\ndiff --git a/libstdc++-v3/include/bits/stl_iterator_base_funcs.h b/libstdc++-v3/include/bits/stl_iterator_base_funcs.h\nindex d85b39365400..2762090c6e48 100644\n--- a/libstdc++-v3/include/bits/stl_iterator_base_funcs.h\n+++ b/libstdc++-v3/include/bits/stl_iterator_base_funcs.h\n@@ -131,8 +131,10 @@ _GLIBCXX_END_NAMESPACE_CONTAINER\n #endif\n \n #ifdef __glibcxx_concepts\n+/// @cond undocumented\n namespace __detail\n {\n+\n // Satisfied if ITER_TRAITS(Iter)::iterator_category is valid and is\n // at least as strong as ITER_TRAITS(Iter)::iterator_concept.\n template\n@@ -149,21 +151,24 @@ namespace __detail\n = input_iterator<_Iter>\n \t && requires { typename __iter_traits<_Iter>::iterator_concept; }\n \t && ! __iter_category_converts_to_concept<_Iter>;\n+\n } // namespace __detail\n+/// @endcond\n #endif\n \n /**\n * @brief A generalization of pointer arithmetic.\n- * @param __first An input iterator.\n- * @param __last An input iterator.\n+ * @param __first,__last Input iterators that form a valid range.\n * @return The distance between them.\n *\n- * Returns @c n such that __first + n == __last. This requires\n- * that @p __last must be reachable from @p __first. Note that @c\n- * n may be negative.\n+ * Returns `n` such that `__first + n == __last`.\n+ * This requires that `__last` must be reachable from `__first`, or\n+ * for random access iterators either `__last` is reachable from `__first`\n+ * or `__first` is reachable from `__last`. In the latter case, `n`\n+ * may be negative.\n *\n- * For random access iterators, this uses their @c + and @c - operations\n- * and are constant time. For other %iterator classes they are linear time.\n+ * For random access iterators, this uses their `+` and `-` operations\n+ * and is constant time. For other %iterator classes they are linear time.\n */\n template\n _GLIBCXX_NODISCARD __attribute__((__always_inline__))\n@@ -194,6 +199,8 @@ namespace __detail\n \t\t\t std::__iterator_category(__first));\n }\n \n+ /// @cond undocumented\n+\n template\n inline _GLIBCXX14_CONSTEXPR void\n __advance(_InputIterator& __i, _Distance __n, input_iterator_tag)\n@@ -244,15 +251,17 @@ namespace __detail\n __advance(_OutputIterator&, _Distance, output_iterator_tag) = delete;\n #endif\n \n+ /// @endcond\n+\n /**\n * @brief A generalization of pointer arithmetic.\n * @param __i An input iterator.\n * @param __n The @a delta by which to change @p __i.\n *\n- * This increments @p i by @p n. For bidirectional and random access\n- * iterators, @p __n may be negative, in which case @p __i is decremented.\n+ * This increments `i` by `n`. For bidirectional and random access\n+ * iterators, `__n` may be negative, in which case `__i` is decremented.\n *\n- * For random access iterators, this uses their @c + and @c - operations\n+ * For random access iterators, this uses their `+` and `-` operations\n * and are constant time. For other %iterator classes they are linear time.\n */\n template\n@@ -316,6 +325,7 @@ namespace __detail\n \n #endif // C++11\n \n+ /// @cond undocumented\n #if __glibcxx_algorithm_iterator_requirements // C++ >= 20\n template\n consteval auto\n@@ -373,6 +383,8 @@ namespace __detail\n #define _GLIBCXX_ITER_MOVE(__it) _GLIBCXX_MOVE(*__it)\n #endif\n \n+ /// @endcond\n+\n _GLIBCXX_END_NAMESPACE_VERSION\n } // namespace\n \ndiff --git a/libstdc++-v3/include/bits/stl_iterator_base_types.h b/libstdc++-v3/include/bits/stl_iterator_base_types.h\nindex 9c008276b98f..2366b5b5ce3e 100644\n--- a/libstdc++-v3/include/bits/stl_iterator_base_types.h\n+++ b/libstdc++-v3/include/bits/stl_iterator_base_types.h\n@@ -122,7 +122,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n * used in specializations and overloading.\n *\n * In particular, there are no default implementations of requirements\n- * such as @c operator++ and the like. (How could there be?)\n+ * such as `operator++` and the like. (How could there be?)\n+ *\n+ * @deprecated Deprecated since C++17. The recommended alternative is to\n+ * simply define the typedefs directly in your iterator class.\n */\n template\n@@ -144,9 +147,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n * @brief Traits class for iterators.\n *\n * This class does nothing but define nested typedefs. The general\n- * version simply @a forwards the nested typedefs from the Iterator\n- * argument. Specialized versions for pointers and pointers-to-const\n- * provide tighter, more correct semantics.\n+ * version simply declares aliases for the nested typedefs from the Iterator\n+ * argument. Partial specializations for pointers define the typedefs\n+ * appropriately for the semantics of pointers.\n */\n template\n struct iterator_traits;\n@@ -230,6 +233,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n };\n #endif\n \n+ /// @cond undocumented\n /**\n * This function is not a part of the C++ standard but is syntactic\n * sugar for internal library use only.\n@@ -241,8 +245,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n __iterator_category(const _Iter&)\n { return typename iterator_traits<_Iter>::iterator_category(); }\n \n- ///@}\n-\n #if __cplusplus >= 201103L\n template\n using __iter_category_t\n@@ -281,6 +283,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION\n { enum { __value = __is_base_of(random_access_iterator_tag, _Cat) }; };\n #endif\n \n+ /// @endcond\n+ /// @}\n+\n _GLIBCXX_END_NAMESPACE_VERSION\n } // namespace\n \n","prefixes":["committed","1/3"]}