From 8050bda5ec6892c312bfaafa753532cba7b54d8c Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Fri, 1 May 2026 12:15:17 +0100 Subject: [PATCH] libstdc++: Improve Doxygen comments for contents Use markdown and suppress unwanted docs for internal helpers. libstdc++-v3/ChangeLog: * include/bits/stl_iterator.h: Prevent Doxygen from documenting namespace __detail as part of the Iterators topic. * include/bits/stl_iterator_base_funcs.h: Likewise. Also mark internal helpers as undocumented. (distance, advance): Improve Doxygen comments. * include/bits/stl_iterator_base_types.h (iterator): Use markdown in Doxygen comment. Add @deprecated. (iterator_traits): Improve wording of Doxygen comment. --- libstdc++-v3/include/bits/stl_iterator.h | 4 +++ .../include/bits/stl_iterator_base_funcs.h | 32 +++++++++++++------ .../include/bits/stl_iterator_base_types.h | 17 ++++++---- 3 files changed, 37 insertions(+), 16 deletions(-) diff --git a/libstdc++-v3/include/bits/stl_iterator.h b/libstdc++-v3/include/bits/stl_iterator.h index 6439deb608a..ea083543c1d 100644 --- a/libstdc++-v3/include/bits/stl_iterator.h +++ b/libstdc++-v3/include/bits/stl_iterator.h @@ -2619,6 +2619,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION template class basic_const_iterator; + /// @cond undocumented namespace __detail { template @@ -2646,11 +2647,13 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION struct __basic_const_iterator_iter_cat<_It> { using iterator_category = __iter_category_t<_It>; }; } // namespace detail + /// @endcond template using const_iterator = __conditional_t<__detail::__constant_iterator<_It>, _It, basic_const_iterator<_It>>; + /// @cond undocumented namespace __detail { template @@ -2661,6 +2664,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION struct __const_sentinel<_Sent> { using type = const_iterator<_Sent>; }; } // namespace __detail + /// @endcond template using const_sentinel = typename __detail::__const_sentinel<_Sent>::type; diff --git a/libstdc++-v3/include/bits/stl_iterator_base_funcs.h b/libstdc++-v3/include/bits/stl_iterator_base_funcs.h index d85b3936540..2762090c6e4 100644 --- a/libstdc++-v3/include/bits/stl_iterator_base_funcs.h +++ b/libstdc++-v3/include/bits/stl_iterator_base_funcs.h @@ -131,8 +131,10 @@ _GLIBCXX_END_NAMESPACE_CONTAINER #endif #ifdef __glibcxx_concepts +/// @cond undocumented namespace __detail { + // Satisfied if ITER_TRAITS(Iter)::iterator_category is valid and is // at least as strong as ITER_TRAITS(Iter)::iterator_concept. template @@ -149,21 +151,24 @@ namespace __detail = input_iterator<_Iter> && requires { typename __iter_traits<_Iter>::iterator_concept; } && ! __iter_category_converts_to_concept<_Iter>; + } // namespace __detail +/// @endcond #endif /** * @brief A generalization of pointer arithmetic. - * @param __first An input iterator. - * @param __last An input iterator. + * @param __first,__last Input iterators that form a valid range. * @return The distance between them. * - * Returns @c n such that __first + n == __last. This requires - * that @p __last must be reachable from @p __first. Note that @c - * n may be negative. + * Returns `n` such that `__first + n == __last`. + * This requires that `__last` must be reachable from `__first`, or + * for random access iterators either `__last` is reachable from `__first` + * or `__first` is reachable from `__last`. In the latter case, `n` + * may be negative. * - * For random access iterators, this uses their @c + and @c - operations - * and are constant time. For other %iterator classes they are linear time. + * For random access iterators, this uses their `+` and `-` operations + * and is constant time. For other %iterator classes they are linear time. */ template _GLIBCXX_NODISCARD __attribute__((__always_inline__)) @@ -194,6 +199,8 @@ namespace __detail std::__iterator_category(__first)); } + /// @cond undocumented + template inline _GLIBCXX14_CONSTEXPR void __advance(_InputIterator& __i, _Distance __n, input_iterator_tag) @@ -244,15 +251,17 @@ namespace __detail __advance(_OutputIterator&, _Distance, output_iterator_tag) = delete; #endif + /// @endcond + /** * @brief A generalization of pointer arithmetic. * @param __i An input iterator. * @param __n The @a delta by which to change @p __i. * - * This increments @p i by @p n. For bidirectional and random access - * iterators, @p __n may be negative, in which case @p __i is decremented. + * This increments `i` by `n`. For bidirectional and random access + * iterators, `__n` may be negative, in which case `__i` is decremented. * - * For random access iterators, this uses their @c + and @c - operations + * For random access iterators, this uses their `+` and `-` operations * and are constant time. For other %iterator classes they are linear time. */ template @@ -316,6 +325,7 @@ namespace __detail #endif // C++11 + /// @cond undocumented #if __glibcxx_algorithm_iterator_requirements // C++ >= 20 template consteval auto @@ -373,6 +383,8 @@ namespace __detail #define _GLIBCXX_ITER_MOVE(__it) _GLIBCXX_MOVE(*__it) #endif + /// @endcond + _GLIBCXX_END_NAMESPACE_VERSION } // namespace diff --git a/libstdc++-v3/include/bits/stl_iterator_base_types.h b/libstdc++-v3/include/bits/stl_iterator_base_types.h index 9c008276b98..2366b5b5ce3 100644 --- a/libstdc++-v3/include/bits/stl_iterator_base_types.h +++ b/libstdc++-v3/include/bits/stl_iterator_base_types.h @@ -122,7 +122,10 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * used in specializations and overloading. * * In particular, there are no default implementations of requirements - * such as @c operator++ and the like. (How could there be?) + * such as `operator++` and the like. (How could there be?) + * + * @deprecated Deprecated since C++17. The recommended alternative is to + * simply define the typedefs directly in your iterator class. */ template @@ -144,9 +147,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION * @brief Traits class for iterators. * * This class does nothing but define nested typedefs. The general - * version simply @a forwards the nested typedefs from the Iterator - * argument. Specialized versions for pointers and pointers-to-const - * provide tighter, more correct semantics. + * version simply declares aliases for the nested typedefs from the Iterator + * argument. Partial specializations for pointers define the typedefs + * appropriately for the semantics of pointers. */ template struct iterator_traits; @@ -230,6 +233,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION }; #endif + /// @cond undocumented /** * This function is not a part of the C++ standard but is syntactic * sugar for internal library use only. @@ -241,8 +245,6 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION __iterator_category(const _Iter&) { return typename iterator_traits<_Iter>::iterator_category(); } - ///@} - #if __cplusplus >= 201103L template using __iter_category_t @@ -281,6 +283,9 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION { enum { __value = __is_base_of(random_access_iterator_tag, _Cat) }; }; #endif + /// @endcond + /// @} + _GLIBCXX_END_NAMESPACE_VERSION } // namespace