Documentation: purge QSet and QHash members that no longer exist

QMutableSet/HashIterator can not walk backwards, neither can the STL iterator.
When function documentation was shared with other iterator types, move it into
separate section to avoid linking to incorrect see-alsos.

Remove or fix other member function documentation that had errors, e.g.
in parameter types after move to qsizetype.

Change-Id: Ic7f97a295eff63ee748998b10f08a160706fa650
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

1 files changed, 53 insertions, 163 deletions

diff --git a/src/corelib/tools/qiterator.qdoc b/src/corelib/tools/qiterator.qdoc
index 2c07dcf423..eacc504557 100644
--- a/src/corelib/tools/qiterator.qdoc
+++ b/src/corelib/tools/qiterator.qdoc
@@ -357,10 +357,6 @@
 
     \image javaiterators1.png
 
-    Here's how to iterate over the elements in reverse order:
-
-    \snippet code/doc_src_qiterator.cpp 18
-
     If you want to remove items as you iterate over the set, use
     remove().
 
@@ -425,7 +421,6 @@
 /*! \fn template <class T> void QListIterator<T>::toBack()
     \fn template <class T> void QSetIterator<T>::toBack()
     \fn template <class T> void QMutableListIterator<T>::toBack()
-    \fn template <class T> void QMutableSetIterator<T>::toBack()
 
     Moves the iterator to the back of the container (after the last
     item).
@@ -433,10 +428,17 @@
     \sa toFront(), previous()
 */
 
+/*! \fn template <class T> void QMutableSetIterator<T>::toBack()
+
+    Moves the iterator to the back of the container (after the last
+    item).
+
+    \sa toFront()
+*/
+
 /*! \fn template <class T> bool QListIterator<T>::hasNext() const
     \fn template <class T> bool QSetIterator<T>::hasNext() const
     \fn template <class T> bool QMutableListIterator<T>::hasNext() const
-    \fn template <class T> bool QMutableSetIterator<T>::hasNext() const
 
     Returns \c true if there is at least one item ahead of the iterator,
     i.e. the iterator is \e not at the back of the container;
@@ -445,9 +447,17 @@
     \sa hasPrevious(), next()
 */
 
+/*! \fn template <class T> bool QMutableSetIterator<T>::hasNext() const
+
+    Returns \c true if there is at least one item ahead of the iterator,
+    i.e. the iterator is \e not at the back of the container;
+    otherwise returns \c false.
+
+    \sa next()
+*/
+
 /*! \fn template <class T> const T &QListIterator<T>::next()
     \fn template <class T> const T &QSetIterator<T>::next()
-    \fn template <class T> const T &QMutableSetIterator<T>::next()
 
     Returns the next item and advances the iterator by one position.
 
@@ -457,6 +467,25 @@
     \sa hasNext(), peekNext(), previous()
 */
 
+/* \fn template <class T> const T &QMutableSetIterator<T>::next()
+    Returns the next item and advances the iterator by one position.
+
+    Calling this function on an iterator located at the back of the
+    container leads to undefined results.
+
+    \sa hasNext(), peekNext()
+*/
+
+/*! \fn template <class T> const T &QMutableSetIterator<T>::next()
+
+    Returns the next item and advances the iterator by one position.
+
+    Calling this function on an iterator located at the back of the
+    container leads to undefined results.
+
+    \sa hasNext(), peekNext()
+*/
+
 /*! \fn template <class T> T &QMutableListIterator<T>::next()
 
     Returns a reference to the next item, and advances the iterator
@@ -470,7 +499,6 @@
 
 /*! \fn template <class T> const T &QListIterator<T>::peekNext() const
     \fn template <class T> const T &QSetIterator<T>::peekNext() const
-    \fn template <class T> const T &QMutableSetIterator<T>::peekNext() const
 
     Returns the next item without moving the iterator.
 
@@ -480,25 +508,25 @@
     \sa hasNext(), next(), peekPrevious()
 */
 
-/*! \fn template <class T> T &QMutableListIterator<T>::peekNext() const
+/*!
+    \fn template <class T> const T &QMutableSetIterator<T>::peekNext() const
 
-    Returns a reference to the next item, without moving the iterator.
+    Returns the next item without moving the iterator.
 
     Calling this function on an iterator located at the back of the
     container leads to undefined results.
 
-    \sa hasNext(), next(), peekPrevious()
+    \sa hasNext(), next()
 */
 
-/*!
-    \fn template <class T> bool QMutableSetIterator<T>::hasPrevious() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
+/*! \fn template <class T> T &QMutableListIterator<T>::peekNext() const
 
-    Returns \c true if there is at least one item behind the iterator,
-    i.e. the iterator is \e not at the front of the container;
-    otherwise returns \c false.
+    Returns a reference to the next item, without moving the iterator.
 
-    \sa hasNext(), previous()
+    Calling this function on an iterator located at the back of the
+    container leads to undefined results.
+
+    \sa hasNext(), next(), peekPrevious()
 */
 
 /*! \fn template <class T> bool QListIterator<T>::hasPrevious() const
@@ -512,19 +540,6 @@
     \sa hasNext(), previous()
 */
 
-/*!
-    \fn template <class T> const T &QMutableSetIterator<T>::previous()
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns the previous item and moves the iterator back by one
-    position.
-
-    Calling this function on an iterator located at the front of the
-    container leads to undefined results.
-
-    \sa hasPrevious(), peekPrevious(), next()
-*/
-
 /*! \fn template <class T> const T &QListIterator<T>::previous()
     \fn template <class T> const T &QSetIterator<T>::previous()
 
@@ -548,18 +563,6 @@
     \sa hasPrevious(), peekPrevious(), next()
 */
 
-/*!
-    \fn template <class T> const T &QMutableSetIterator<T>::peekPrevious() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns the previous item without moving the iterator.
-
-    Calling this function on an iterator located at the front of the
-    container leads to undefined results.
-
-    \sa hasPrevious(), previous(), peekNext()
-*/
-
 /*! \fn template <class T> const T &QListIterator<T>::peekPrevious() const
     \fn template <class T> const T &QSetIterator<T>::peekPrevious() const
 
@@ -583,7 +586,6 @@
 
 /*!
     \fn template <class T> bool QMutableSetIterator<T>::findNext(const T &value)
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
 
     Searches for \a value starting from the current iterator position
     forward. Returns \c true if \a value is found; otherwise returns \c false.
@@ -591,8 +593,6 @@
     After the call, if \a value was found, the iterator is positioned
     just after the matching item; otherwise, the iterator is
     positioned at the back of the container.
-
-    \sa findPrevious()
 */
 
 /*! \fn template <class T> bool QListIterator<T>::findNext(const T &value)
@@ -612,7 +612,6 @@
 /*! \fn template <class T> bool QListIterator<T>::findPrevious(const T &value)
     \fn template <class T> bool QSetIterator<T>::findPrevious(const T &value)
     \fn template <class T> bool QMutableListIterator<T>::findPrevious(const T &value)
-    \fn template <class T> bool QMutableSetIterator<T>::findPrevious(const T &value)
 
     Searches for \a value starting from the current iterator position
     backward. Returns \c true if \a value is found; otherwise returns
@@ -639,7 +638,7 @@
 /*! \fn template <class T> void QMutableSetIterator<T>::remove()
 
     Removes the last item that was jumped over using one of the
-    traversal functions (next(), previous(), findNext(), findPrevious()).
+    traversal functions (next(), findNext()).
 
     Example:
     \snippet code/doc_src_qiterator.cpp 22
@@ -662,7 +661,6 @@
 */
 
 /*! \fn template <class T> const T &QMutableListIterator<T>::value() const
-    \fn template <class T> const T &QMutableSetIterator<T>::value() const
 
     Returns the value of the last item that was jumped over using one
     of the traversal functions (next(), previous(), findNext(),
@@ -673,6 +671,12 @@
     equivalent to peekNext().
 */
 
+/*! \fn template <class T> const T &QMutableSetIterator<T>::value() const
+
+    Returns the value of the last item that was jumped over using
+    next() or findNext().
+*/
+
 /*!
     \fn template <class T> T &QMutableListIterator<T>::value()
     \overload
@@ -1252,28 +1256,6 @@
     \sa hasNext(), previous()
 */
 
-/*!
-    \fn template <class Key, class T> bool QHashIterator<Key, T>::hasPrevious() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns \c true if there is at least one item behind the iterator,
-    i.e. the iterator is \e not at the front of the container;
-    otherwise returns \c false.
-
-    \sa hasNext(), previous()
-*/
-
-/*!
-    \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::hasPrevious() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns \c true if there is at least one item behind the iterator,
-    i.e. the iterator is \e not at the front of the container;
-    otherwise returns \c false.
-
-    \sa hasNext(), previous()
-*/
-
 /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::previous()
     \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::previous()
     \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::previous()
@@ -1291,38 +1273,6 @@
     \sa hasPrevious(), peekPrevious(), next()
 */
 
-/*!
-    \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::previous()
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns the previous item and moves the iterator back by one
-    position.
-
-    Call key() on the return value to obtain the item's key, and
-    value() to obtain the value.
-
-    Calling this function on an iterator located at the front of the
-    container leads to undefined results.
-
-    \sa hasPrevious(), peekPrevious(), next()
-*/
-
-/*!
-    \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::previous()
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns the previous item and moves the iterator back by one
-    position.
-
-    Call key() on the return value to obtain the item's key, and
-    value() to obtain the value.
-
-    Calling this function on an iterator located at the front of the
-    container leads to undefined results.
-
-    \sa hasPrevious(), peekPrevious(), next()
-*/
-
 /*! \fn template <class Key, class T> QMapIterator<Key, T>::Item QMapIterator<Key, T>::peekPrevious() const
     \fn template <class Key, class T> QMutableMapIterator<Key, T>::Item QMutableMapIterator<Key, T>::peekPrevious() const
     \fn template <class Key, class T> QMultiMapIterator<Key, T>::Item QMultiMapIterator<Key, T>::peekPrevious() const
@@ -1339,36 +1289,6 @@
     \sa hasPrevious(), previous(), peekNext()
 */
 
-/*!
-    \fn template <class Key, class T> QHashIterator<Key, T>::Item QHashIterator<Key, T>::peekPrevious() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns the previous item without moving the iterator.
-
-    Call key() on the return value to obtain the item's key, and
-    value() to obtain the value.
-
-    Calling this function on an iterator located at the front of the
-    container leads to undefined results.
-
-    \sa hasPrevious(), previous(), peekNext()
-*/
-
-/*!
-    \fn template <class Key, class T> QMutableHashIterator<Key, T>::Item QMutableHashIterator<Key, T>::peekPrevious() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Returns the previous item without moving the iterator.
-
-    Call key() on the return value to obtain the item's key, and
-    value() to obtain the value.
-
-    Calling this function on an iterator located at the front of the
-    container leads to undefined results.
-
-    \sa hasPrevious(), previous(), peekNext()
-*/
-
 /*! \fn template <class Key, class T> const T &QMapIterator<Key, T>::value() const
     \fn template <class Key, class T> const T &QMultiMapIterator<Key, T>::value() const
 
@@ -1495,36 +1415,6 @@
     \sa findNext()
 */
 
-/*!
-    \fn template <class Key, class T> bool QHashIterator<Key, T>::findPrevious(const T &value)
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Searches for \a value starting from the current iterator position
-    backward. Returns \c true if a (key, value) pair with value \a value
-    is found; otherwise returns \c false.
-
-    After the call, if \a value was found, the iterator is positioned
-    just before the matching item; otherwise, the iterator is
-    positioned at the front of the container.
-
-    \sa findNext()
-*/
-
-/*!
-    \fn template <class Key, class T> bool QMutableHashIterator<Key, T>::findPrevious(const T &value)
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    Searches for \a value starting from the current iterator position
-    backward. Returns \c true if a (key, value) pair with value \a value
-    is found; otherwise returns \c false.
-
-    After the call, if \a value was found, the iterator is positioned
-    just before the matching item; otherwise, the iterator is
-    positioned at the front of the container.
-
-    \sa findNext()
-*/
-
 /*! \fn template <class Key, class T> void QMutableMapIterator<Key, T>::remove()
     \fn template <class Key, class T> void QMutableMultiMapIterator<Key, T>::remove()