QMap/MultiMap/Hash/MultiHash: synchronize documentation

Synchronize the documentation of the four container classes:
 - document the return type of insert() and replace()
 - don't reference QMultiHash/Map from QHash/Map except in the details
   paragraph

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

src/corelib/tools/qhash.cpp

@@ -2019,7 +2019,7 @@ size_t qHash(long double key, size_t seed) noexcept
     Returns \c true if the hash contains an item with the \a key;
     otherwise returns \c false.
 
-    \sa count(), QMultiHash::contains()
+    \sa count()
 */
 
 /*! \fn template <class Key, class T> T QHash<Key, T>::value(const Key &key) const
@@ -2330,6 +2330,8 @@ size_t qHash(long double key, size_t seed) noexcept
 
     If there is already an item with the \a key, that item's value
     is replaced with \a value.
+
+    Returns an iterator pointing to the new/updated element.
 */
 
 /*!
@@ -2969,6 +2971,8 @@ size_t qHash(long double key, size_t seed) noexcept
     If there are multiple items with the \a key, the most
     recently inserted item's value is replaced with \a value.
 
+    Returns an iterator pointing to the new/updated element.
+
     \sa insert()
 */
 
@@ -2981,6 +2985,8 @@ size_t qHash(long double key, size_t seed) noexcept
     different from replace(), which overwrites the value of an
     existing item.)
 
+    Returns an iterator pointing to the new element.
+
     \sa replace()
 */
 

src/corelib/tools/qmap.qdoc

@@ -390,7 +390,7 @@
     use that entails can be avoided by iterating from \l keyBegin() to
     \l keyEnd().
 
-    \sa QMultiMap::uniqueKeys(), values(), key()
+    \sa values(), key()
 */
 
 /*! \fn template <class Key, class T> QList<Key> QMap<Key, T>::keys(const T &value) const
@@ -730,7 +730,7 @@
     If there is already an item with the key \a key, that item's value
     is replaced with \a value.
 
-    \sa QMultiMap::insert()
+    Returns an iterator pointing to the new/updated element.
 */
 
 /*! \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
@@ -756,7 +756,7 @@
     \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
     crash but there is also a risk that it will silently corrupt both the map and the \a pos map.
 
-    \sa QMultiMap::insert()
+    Returns an iterator pointing to the new/updated element.
 */
 
 /*! \fn template <class Key, class T> void QMap<Key, T>::insert(const QMap<Key, T> &map)
@@ -766,8 +766,6 @@
 
     If a key is common to both maps, its value will be replaced with
     the value stored in \a map.
-
-    \sa QMultiMap::insert()
 */
 
 /*! \fn template <class Key, class T> void QMap<Key, T>::insert(QMap<Key, T> &&map)

src/corelib/tools/qmultimap.qdoc

@@ -817,6 +817,8 @@
     different from replace(), which overwrites the value of an
     existing item.)
 
+    Returns an iterator pointing to the new element.
+
     \sa replace()
 */
 
@@ -839,6 +841,8 @@
     is faster than inserting in sorted order with constEnd(), since constEnd() - 1 (which is needed
     to check if the hint is valid) needs \l{logarithmic time}.
 
+    Returns an iterator pointing to the new element.
+
     \b {Note:} Be careful with the hint. Providing an iterator from an older shared instance might
     crash but there is also a risk that it will silently corrupt both the multi map and the \a pos multi map.
 */
@@ -886,6 +890,8 @@
     If there are multiple items with the key \a key, the most
     recently inserted item's value is replaced with \a value.
 
+    Returns an iterator pointing to the new/updated element.
+
     \sa insert()
 */