From 8615884728c186980ddc1e7e8a862423b035ac4d Mon Sep 17 00:00:00 2001
From: Christian Ehrlicher <ch.ehrlicher@gmx.de>
Date: Tue, 3 Oct 2023 20:31:38 +0200
Subject: 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      | 8 +++++++-
 src/corelib/tools/qmap.qdoc      | 8 +++-----
 src/corelib/tools/qmultimap.qdoc | 6 ++++++
 3 files changed, 16 insertions(+), 6 deletions(-)

(limited to 'src/corelib/tools')

diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index f90c351118..f4ea075b0d 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/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()
 */
 
diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc
index bbf20ef02b..b9d0bd2361 100644
--- a/src/corelib/tools/qmap.qdoc
+++ b/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)
diff --git a/src/corelib/tools/qmultimap.qdoc b/src/corelib/tools/qmultimap.qdoc
index 5bc4af0940..6373b2748d 100644
--- a/src/corelib/tools/qmultimap.qdoc
+++ b/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()
 */
 
-- 
cgit v1.2.3