[gcc r17-247] libstdc++: Improve Doxygen comments for <iterator> contents
Jonathan Wakely
redi@gcc.gnu.org
Fri May 1 12:31:33 GMT 2026
https://gcc.gnu.org/g:8050bda5ec6892c312bfaafa753532cba7b54d8c
commit r17-247-g8050bda5ec6892c312bfaafa753532cba7b54d8c
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Fri May 1 12:15:17 2026 +0100
libstdc++: Improve Doxygen comments for <iterator> 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.
Diff:
---
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 6439deb608a6..ea083543c1d4 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<input_iterator _It> class basic_const_iterator;
+ /// @cond undocumented
namespace __detail
{
template<typename _It>
@@ -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<input_iterator _It>
using const_iterator
= __conditional_t<__detail::__constant_iterator<_It>, _It, basic_const_iterator<_It>>;
+ /// @cond undocumented
namespace __detail
{
template<typename _Sent>
@@ -2661,6 +2664,7 @@ _GLIBCXX_BEGIN_NAMESPACE_VERSION
struct __const_sentinel<_Sent>
{ using type = const_iterator<_Sent>; };
} // namespace __detail
+ /// @endcond
template<semiregular _Sent>
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 d85b39365400..2762090c6e48 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<typename _Iter>
@@ -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<typename _InputIterator>
_GLIBCXX_NODISCARD __attribute__((__always_inline__))
@@ -194,6 +199,8 @@ namespace __detail
std::__iterator_category(__first));
}
+ /// @cond undocumented
+
template<typename _InputIterator, typename _Distance>
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<typename _InputIterator, typename _Distance>
@@ -316,6 +325,7 @@ namespace __detail
#endif // C++11
+ /// @cond undocumented
#if __glibcxx_algorithm_iterator_requirements // C++ >= 20
template<typename _Iter>
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 9c008276b98f..2366b5b5ce3e 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<typename _Category, typename _Tp, typename _Distance = ptrdiff_t,
typename _Pointer = _Tp*, typename _Reference = _Tp&>
@@ -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<typename _Iterator>
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<typename _Iter>
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
More information about the Libstdc++-cvs
mailing list