Doc: Fix documentation warnings for QIterable and related classes

Task-number: QTBUG-86295
Change-Id: I1d4c851ae7d2910ab6276ab2215b5f6e550a12c8
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

3 files changed, 38 insertions, 25 deletions

diff --git a/src/corelib/kernel/qassociativeiterable.cpp b/src/corelib/kernel/qassociativeiterable.cpp
index 7b4c103c63..f978acbd8b 100644
--- a/src/corelib/kernel/qassociativeiterable.cpp
+++ b/src/corelib/kernel/qassociativeiterable.cpp
@@ -296,8 +296,7 @@ void QAssociativeIterable::setValue(const QVariant &key, const QVariant &mapped)
 }
 
 /*!
-    \class QAssociativeIterable::const_iterator
-    \since 5.2
+    \typealias QAssociativeIterable::const_iterator
     \inmodule QtCore
     \brief The QAssociativeIterable::const_iterator allows iteration over a container in a QVariant.
 
@@ -310,7 +309,7 @@ void QAssociativeIterable::setValue(const QVariant &key, const QVariant &mapped)
 */
 
 /*!
-    \class QAssociativeIterable::iterator
+    \typealias QAssociativeIterable::iterator
     \since 6.0
     \inmodule QtCore
     \brief The QAssociativeIterable::iterator allows iteration over a container in a QVariant.
diff --git a/src/corelib/kernel/qiterable.cpp b/src/corelib/kernel/qiterable.cpp
index 0001a2311a..7ee7be2696 100644
--- a/src/corelib/kernel/qiterable.cpp
+++ b/src/corelib/kernel/qiterable.cpp
@@ -283,7 +283,21 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
-    \fn template<class Container> QConstIterator<Container>::QConstIterator(const QIterable<Container> *iterable, void *iterator)
+    \fn template <class Container> QIterator<Container> QIterator<Container>::operator+(qsizetype j, const QIterator<Container> &k)
+
+    Returns an iterator to the item at \a j positions forward from iterator \a k.
+*/
+
+/*!
+    \struct QConstIterator
+    \since 6.0
+    \inmodule QtCore
+    \brief The QConstIterator allows iteration over a container in a QVariant.
+    \sa QIterator, QIterable
+*/
+
+/*!
+    \fn template <class Container> QConstIterator<Container>::QConstIterator(const QIterable<Container> *iterable, void *iterator)
 
     Creates a QConstIterator to wrap \a iterator, operating on \a iterable.
  */
@@ -339,7 +353,7 @@ QT_BEGIN_NAMESPACE
     If the container in the QVariant does not support bi-directional iteration, calling this function
     leads to undefined results.
 
-    \sa operator++(), canReverseIterate()
+    \sa operator++(), QIterable::canReverseIterate()
 */
 
 /*!
@@ -353,7 +367,7 @@ QT_BEGIN_NAMESPACE
     If the container in the QVariant does not support bi-directional iteration, calling this function
     leads to undefined results.
 
-    \sa canReverseIterate()
+    \sa QIterable::canReverseIterate()
 */
 
 /*!
@@ -372,7 +386,7 @@ QT_BEGIN_NAMESPACE
     If the container in the QVariant does not support bi-directional iteration, calling this function
     leads to undefined results.
 
-    \sa operator+=(), operator-(), canReverseIterate()
+    \sa operator+=(), operator-(), QIterable::canReverseIterate()
 */
 
 /*!
@@ -393,25 +407,26 @@ QT_BEGIN_NAMESPACE
     If the container in the QVariant does not support bi-directional iteration, calling this function
     leads to undefined results.
 
-    \sa operator+(), operator-=(), canReverseIterate()
+    \sa operator+(), operator-=(), QIterable::canReverseIterate()
 */
 
 /*!
-    \fn template<class Container> qsizetype QConstIterator<Container>::operator-(const QConstIterator<Container> &j) const
+    \fn template <class Container> qsizetype QConstIterator<Container>::operator-(const QConstIterator<Container> &j) const
 
     Returns the distance between the two iterators.
 
-    \sa operator+(), operator-=(), canReverseIterator()
+    \sa operator+(), operator-=(), QIterable::canReverseIterate()
  */
 
 /*!
     \class QIterable
+    \inmodule QtCore
     \since 6.0
     \brief QIterable is a template class that is the base class for QSequentialIterable and QAssociativeIterable.
 */
 
 /*!
-    \fn template<class Container> bool QIterable<Container>::canInputIterate() const
+    \fn template <class Container> bool QIterable<Container>::canInputIterate() const
 
     Returns whether the container has an input iterator. This corresponds to
     the std::input_iterator_tag iterator trait of the iterator and
@@ -490,10 +505,10 @@ QT_BEGIN_NAMESPACE
     \inmodule QtCore
     \brief QTaggedIterator is a template class that wraps an iterator and exposes standard iterator traits.
 
-    In order to use an iterator any of the standard algorithms, it iterator
+    In order to use an iterator any of the standard algorithms, its iterator
     traits need to be known. As QSequentialIterable can work with many different
     kinds of containers, we cannot declare the traits in the iterator classes
-    themselves. StdIterator gives you a way to explicitly declare a trait for
+    themselves. A QTaggedIterator gives you a way to explicitly declare a trait for
     a concrete instance of an iterator or QConstIterator.
 */
 
@@ -502,7 +517,7 @@ QT_BEGIN_NAMESPACE
 
     Constructs a QTaggedIterator from an iterator or QConstIterator \a it. Checks
     whether the IteratorCategory passed as template argument matches the run
-    time capabilities of \a it and refuses \a it if not.
+    time capabilities of \a it; if there's no match, \a it is refused.
 */
 
 /*!
@@ -602,6 +617,12 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator+(qsizetype j, const QTaggedIterator &k)
+
+    Returns an iterator to the item at \a j positions forward from iterator \a k.
+*/
+
+/*!
     \fn template<class Iterator, typename IteratorCategory> QTaggedIterator<Iterator, IteratorCategory> QTaggedIterator<Iterator, IteratorCategory>::operator-(qsizetype j) const
 
     Returns an iterator to the item at \a j positions backward from
@@ -614,9 +635,9 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn template<class Iterator, typename IteratorCategory> qsizetype QTaggedIterator<Iterator, IteratorCategory>::operator-(const QTaggedIterator &j) const
+    \fn template <class Iterator, typename IteratorCategory> qsizetype QTaggedIterator<Iterator, IteratorCategory>::operator-(const QTaggedIterator<Iterator, IteratorCategory> &j) const
 
-    Returns the distance between the two iterators.
+    Returns the distance between this iterator and \a j.
 
     \sa operator+(), operator-=(), QIterable::canReverseIterate()
 */
diff --git a/src/corelib/kernel/qsequentialiterable.cpp b/src/corelib/kernel/qsequentialiterable.cpp
index 054d97d90f..aedcc9b373 100644
--- a/src/corelib/kernel/qsequentialiterable.cpp
+++ b/src/corelib/kernel/qsequentialiterable.cpp
@@ -196,29 +196,22 @@ void QSequentialIterable::set(qsizetype idx, const QVariant &value)
 }
 
 /*!
-    \class QSequentialIterable::const_iterator
-    \since 5.2
-    \inmodule QtCore
+    \typealias QSequentialIterable::const_iterator
     \brief The QSequentialIterable::const_iterator allows iteration over a container in a QVariant.
 
     A QSequentialIterable::const_iterator can only be created by a QSequentialIterable instance,
     and can be used in a way similar to other stl-style iterators.
 
     \snippet code/src_corelib_kernel_qvariant.cpp 9
-
-    \sa QSequentialIterable
 */
 
 /*!
-    \class QSequentialIterable::iterator
+    \typealias QSequentialIterable::iterator
     \since 6.0
-    \inmodule QtCore
     \brief The QSequentialIterable::iterator allows iteration over a container in a QVariant.
 
     A QSequentialIterable::iterator can only be created by a QSequentialIterable instance,
     and can be used in a way similar to other stl-style iterators.
-
-    \sa QSequentialIterable
 */
 
 /*!