Doc: Expand reasoning for QHash deprecations

and mark QHash::[const_|key_]iterator operators correctly as deprecated.

Change-Id: I01da16254759b9bdb7920709de45a72933d6b5c8
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 16 insertions, 2 deletions

diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index 7ebc374d9f..025c6e9dc0 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -1491,7 +1491,7 @@ uint qHash(long double key, uint seed) noexcept
 
 /*! \fn template <class Key, class T> QList<Key> QHash<Key, T>::uniqueKeys() const
     \since 4.2
-    \obsolete
+    \obsolete Use QMultiHash for storing multiple values with the same key.
 
     Returns a list containing all the keys in the map. Keys that occur multiple
     times in the map (because items were inserted with insertMulti(), or
@@ -1537,8 +1537,8 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QList<T> QHash<Key, T>::values(const Key &key) const
-    \obsolete
     \overload
+    \obsolete Use QMultiHash for storing multiple values with the same key.
 
     Returns a list of all the values associated with the \a key,
     from the most recently inserted to the least recently inserted.
@@ -2103,6 +2103,7 @@ uint qHash(long double key, uint seed) noexcept
 
 /*!
     \fn template <class Key, class T> QHash<Key, T>::iterator &QHash<Key, T>::iterator::operator--()
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     The prefix -- operator (\c{--i}) makes the preceding item
     current and returns an iterator pointing to the new current item.
@@ -2115,6 +2116,7 @@ uint qHash(long double key, uint seed) noexcept
 
 /*!
     \fn template <class Key, class T> QHash<Key, T>::iterator QHash<Key, T>::iterator::operator--(int)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     \overload
 
@@ -2124,6 +2126,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::iterator QHash<Key, T>::iterator::operator+(int j) const
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Returns an iterator to the item at \a j positions forward from
     this iterator. (If \a j is negative, the iterator goes backward.)
@@ -2135,6 +2138,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::iterator QHash<Key, T>::iterator::operator-(int j) const
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Returns an iterator to the item at \a j positions backward from
     this iterator. (If \a j is negative, the iterator goes forward.)
@@ -2145,6 +2149,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::iterator &QHash<Key, T>::iterator::operator+=(int j)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Advances the iterator by \a j items. (If \a j is negative, the
     iterator goes backward.)
@@ -2153,6 +2158,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::iterator &QHash<Key, T>::iterator::operator-=(int j)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Makes the iterator go back by \a j items. (If \a j is negative,
     the iterator goes forward.)
@@ -2296,6 +2302,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator &QHash<Key, T>::const_iterator::operator--()
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     The prefix -- operator (\c{--i}) makes the preceding item
     current and returns an iterator pointing to the new current item.
@@ -2307,6 +2314,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::const_iterator::operator--(int)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     \overload
 
@@ -2316,6 +2324,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::const_iterator::operator+(int j) const
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Returns an iterator to the item at \a j positions forward from
     this iterator. (If \a j is negative, the iterator goes backward.)
@@ -2326,6 +2335,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator QHash<Key, T>::const_iterator::operator-(int j) const
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Returns an iterator to the item at \a j positions backward from
     this iterator. (If \a j is negative, the iterator goes forward.)
@@ -2336,6 +2346,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator &QHash<Key, T>::const_iterator::operator+=(int j)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Advances the iterator by \a j items. (If \a j is negative, the
     iterator goes backward.)
@@ -2346,6 +2357,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::const_iterator &QHash<Key, T>::const_iterator::operator-=(int j)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     Makes the iterator go back by \a j items. (If \a j is negative,
     the iterator goes forward.)
@@ -2440,6 +2452,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::key_iterator &QHash<Key, T>::key_iterator::operator--()
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     The prefix -- operator (\c{--i}) makes the preceding item
     current and returns an iterator pointing to the new current item.
@@ -2451,6 +2464,7 @@ uint qHash(long double key, uint seed) noexcept
 */
 
 /*! \fn template <class Key, class T> QHash<Key, T>::key_iterator QHash<Key, T>::key_iterator::operator--(int)
+    \obsolete This operator is deprecated in order to align with std::unordered_map functionality.
 
     \overload