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.

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;

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
 

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