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>

2 files changed, 54 insertions, 433 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()
 
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
index b6aae2c7ca..a98ce6cb06 100644
--- a/src/corelib/tools/qset.qdoc
+++ b/src/corelib/tools/qset.qdoc
@@ -185,7 +185,7 @@
     \sa reserve(), squeeze()
 */
 
-/*! \fn template <class T> void QSet<T>::reserve(int size)
+/*! \fn template <class T> void QSet<T>::reserve(qsizetype size)
 
     Ensures that the set's internal hash table consists of at
     least \a size buckets.
@@ -278,12 +278,6 @@
     \sa remove(), find()
 */
 
-/*!
-    \fn template <class T> QSet<T>::iterator QSet<T>::erase(iterator pos)
-    \since 4.2
-    \overload
-*/
-
 /*! \fn template <class T> QSet<T>::const_iterator QSet<T>::find(const T &value) const
     \since 4.2
 
@@ -398,58 +392,6 @@
     \sa constBegin(), end()
 */
 
-/*! \fn template <class T> QSet<T>::reverse_iterator QSet<T>::rbegin()
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-    \since 5.6
-
-    Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
-    item in the set, in reverse order.
-
-    \sa begin(), crbegin(), rend()
-*/
-
-/*! \fn template <class T> QSet<T>::const_reverse_iterator QSet<T>::rbegin() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-    \since 5.6
-    \overload
-*/
-
-/*! \fn template <class T> QSet<T>::const_reverse_iterator QSet<T>::crbegin() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-    \since 5.6
-
-    Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to the first
-    item in the set, in reverse order.
-
-    \sa begin(), rbegin(), rend()
-*/
-
-/*! \fn template <class T> QSet<T>::reverse_iterator QSet<T>::rend()
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-    \since 5.6
-
-    Returns a \l{STL-style iterators}{STL-style} reverse iterator pointing to one past
-    the last item in the set, in reverse order.
-
-    \sa end(), crend(), rbegin()
-*/
-
-/*! \fn template <class T> QSet<T>::const_reverse_iterator QSet<T>::rend() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-    \since 5.6
-    \overload
-*/
-
-/*! \fn template <class T> QSet<T>::const_reverse_iterator QSet<T>::crend() const
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-    \since 5.6
-
-    Returns a const \l{STL-style iterators}{STL-style} reverse iterator pointing to one
-    past the last item in the set, in reverse order.
-
-    \sa end(), rend(), rbegin()
-*/
-
 /*!
     \typedef QSet::Iterator
     \since 4.2
@@ -511,40 +453,6 @@
     Typedef for T. Provided for STL compatibility.
 */
 
-/*! \typedef QSet::reverse_iterator
-    \since 5.6
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    The QSet::reverse_iterator typedef provides an STL-style non-const
-    reverse iterator for QSet.
-
-    It is simply a typedef for \c{std::reverse_iterator<QSet::iterator>}.
-
-    \warning Iterators on implicitly shared containers do not work
-    exactly like STL-iterators. You should avoid copying a container
-    while iterators are active on that container. For more information,
-    read \l{Implicit sharing iterator problem}.
-
-    \sa QSet::rbegin(), QSet::rend(), QSet::const_reverse_iterator, QSet::iterator
-*/
-
-/*! \typedef QSet::const_reverse_iterator
-    \since 5.6
-    \obsolete Deprecated in order to align with std::unordered_set functionality.
-
-    The QSet::const_reverse_iterator typedef provides an STL-style const
-    reverse iterator for QSet.
-
-    It is simply a typedef for \c{std::reverse_iterator<QSet::const_iterator>}.
-
-    \warning Iterators on implicitly shared containers do not work
-    exactly like STL-iterators. You should avoid copying a container
-    while iterators are active on that container. For more information,
-    read \l{Implicit sharing iterator problem}.
-
-    \sa QSet::rbegin(), QSet::rend(), QSet::reverse_iterator, QSet::const_iterator
-*/
-
 /*!
     \fn template <class T> QSet<T>::insert(const T &value)
 
@@ -927,196 +835,19 @@
     current item.
 */
 
-/*!
-    \fn template <class T> QSet<T>::iterator &QSet<T>::iterator::operator--()
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    The prefix -- operator (\c{--it}) makes the preceding item
-    current and returns an iterator to the new current item.
-
-    Calling this function on QSet::begin() leads to undefined
-    results.
-
-    \sa operator++()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::const_iterator &QSet<T>::const_iterator::operator--()
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    The prefix -- operator (\c{--it}) makes the preceding item
-    current and returns an iterator to the new current item.
-
-    Calling this function on QSet::begin() leads to undefined
-    results.
-
-    \sa operator++()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::iterator QSet<T>::iterator::operator--(int)
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    \overload
-
-    The postfix -- operator (\c{it--}) makes the preceding item
-    current and returns an iterator to the previously current item.
-*/
-
-/*!
-    \fn template <class T> QSet<T>::const_iterator QSet<T>::const_iterator::operator--(int)
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    \overload
-
-    The postfix -- operator (\c{it--}) makes the preceding item
-    current and returns an iterator to the previously current item.
-*/
-
-/*!
-    \fn template <class T> QSet<T>::iterator QSet<T>::iterator::operator+(int j) const
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Returns an iterator to the item at \a j positions forward from
-    this iterator. (If \a j is negative, the iterator goes backward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator-()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::const_iterator QSet<T>::const_iterator::operator+(int j) const
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Returns an iterator to the item at \a j positions forward from
-    this iterator. (If \a j is negative, the iterator goes backward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator-()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::iterator QSet<T>::iterator::operator-(int j) const
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Returns an iterator to the item at \a j positions backward from
-    this iterator. (If \a j is negative, the iterator goes forward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator+()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::const_iterator QSet<T>::const_iterator::operator-(int j) const
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Returns an iterator to the item at \a j positions backward from
-    this iterator. (If \a j is negative, the iterator goes forward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator+()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::iterator &QSet<T>::iterator::operator+=(int j)
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Advances the iterator by \a j items. (If \a j is negative, the
-    iterator goes backward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator-=(), operator+()
-
-*/
-
-/*!
-    \fn template <class T> QSet<T>::const_iterator &QSet<T>::const_iterator::operator+=(int j)
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Advances the iterator by \a j items. (If \a j is negative, the
-    iterator goes backward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator-=(), operator+()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::iterator &QSet<T>::iterator::operator-=(int j)
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Makes the iterator go back by \a j items. (If \a j is negative,
-    the iterator goes forward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator+=(), operator-()
-*/
-
-/*!
-    \fn template <class T> QSet<T>::const_iterator &QSet<T>::const_iterator::operator-=(int j)
-    \obsolete This operator is deprecated in order to align with std::unordered_set functionality.
-
-    Makes the iterator go back by \a j items. (If \a j is negative,
-    the iterator goes forward.)
-
-    This operation can be slow for large \a j values.
-
-    \sa operator+=(), operator-()
-*/
-
-/*! \fn template <class T> QList<T> QSet<T>::toList() const
-
-    Returns a new QList containing the elements in the set. The
-    order of the elements in the QList is undefined.
-
-    Example:
-
-    \snippet code/doc_src_qset.cpp 13
-
-    \include containers-range-constructor.qdocinc
-
-    \sa fromList(), QList::fromSet()
-*/
-
 /*! \fn template <class T> QList<T> QSet<T>::values() const
 
     Returns a new QList containing the elements in the set. The
     order of the elements in the QList is undefined.
 
-    This is the same as toList().
-
     \include containers-range-constructor.qdocinc
 
     This function creates a new list, in \l {linear time}. The time and memory
     use that entails can be avoided by iterating from \l constBegin() to
     \l constEnd().
-
-    \sa fromList(), QList::fromSet()
 */
 
 
-/*! \fn template <class T> QSet<T> QSet<T>::fromList(const QList<T> &list)
-
-    Returns a new QSet object containing the data contained in \a
-    list. Since QSet doesn't allow duplicates, the resulting QSet
-    might be smaller than the \a list, because QList can contain
-    duplicates.
-
-    Example:
-
-    \snippet code/doc_src_qset.cpp 14
-
-    \include containers-range-constructor.qdocinc
-
-    \sa toList(), QList::toSet()
-*/
-
 /*!
     \fn template <class T> QDataStream &operator<<(QDataStream &out, const QSet<T> &set)
     \relates QSet