Fix qdoc warnings for QMap/QMultiMap

These containers have most of their operators as non-members,
except those declared as hidden friends in the iterator classes,
which will be fixed in qdoc.

QMultiMap doesn't have an operator[] (which might be unintentional).

Deprecate QMultiMap::insert/insertMulti APIs, as the documentation
suggests that those are just compatibility overloads.

Add documentation for the rvalue-overload of QMap/QMultiMap::insert.
Note that this overload does not exist for QHash/QMultiHash. Also,
it seems from the implementation that the moved-from map is not reset
to the empty map if it did share data with another copy.

Not addressed: QMap and QMultiMap have the special 5 implicitly
generated by the compiler, so these functions are not declared
anywhere, which results in qdoc warnings. qdoc could generate the
documentation automatically, if it can know that those members exist.

Change-Id: I0608b57c8c3793fedd304a4c7b10e607a24ad5f6
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

3 files changed, 79 insertions, 81 deletions

diff --git a/src/corelib/tools/qmap.h b/src/corelib/tools/qmap.h
index d09fa361a0..24d82fa22d 100644
--- a/src/corelib/tools/qmap.h
+++ b/src/corelib/tools/qmap.h
@@ -1316,33 +1316,24 @@ public:
         return iterator(d->m.insert(detachedPos, {key, value}));
     }
 
-    // CHANGE: provide insertMulti for compatibility
+#if QT_DEPRECATED_SINCE(6, 0)
+    QT_DEPRECATED_VERSION_X_6_0("Use insert() instead")
     iterator insertMulti(const Key &key, const T &value)
     {
         return insert(key, value);
     }
-
+    QT_DEPRECATED_VERSION_X_6_0("Use insert() instead")
     iterator insertMulti(const_iterator pos, const Key &key, const T &value)
     {
         return insert(pos, key, value);
     }
 
+    QT_DEPRECATED_VERSION_X_6_0("Use unite() instead")
     void insert(const QMultiMap<Key, T> &map)
     {
-        if (map.isEmpty())
-            return;
-
-        detach();
-
-        auto copy = map.d->m;
-#ifdef __cpp_lib_node_extract
-        copy.merge(std::move(d->m));
-#else
-        copy.insert(std::make_move_iterator(d->m.begin()),
-                    std::make_move_iterator(d->m.end()));
-#endif
-        d->m = std::move(copy);
+        unite(map);
     }
+#endif
 
     void insert(QMultiMap<Key, T> &&map)
     {
@@ -1402,7 +1393,19 @@ public:
 
     QMultiMap &unite(const QMultiMap &other)
     {
-        insert(other);
+        if (other.isEmpty())
+            return *this;
+
+        detach();
+
+        auto copy = other.d->m;
+#ifdef __cpp_lib_node_extract
+        copy.merge(std::move(d->m));
+#else
+        copy.insert(std::make_move_iterator(d->m.begin()),
+                    std::make_move_iterator(d->m.end()));
+#endif
+        d->m = std::move(copy);
         return *this;
     }
 };
diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc
index 1857a05a13..b2ec6e15e4 100644
--- a/src/corelib/tools/qmap.qdoc
+++ b/src/corelib/tools/qmap.qdoc
@@ -781,6 +781,17 @@
     \sa QMultiMap::insert()
 */
 
+/*! \fn template <class Key, class T> void QMap<Key, T>::insert(QMap<Key, T> &&map)
+    \since 5.15
+
+    Moves all the items from \a map into this map.
+
+    If a key is common to both maps, its value will be replaced with
+    the value stored in \a map.
+
+    If \a map is shared, then the items will be copied instead.
+*/
+
 /*! \typedef QMap::Iterator
 
     Qt-style synonym for QMap<Key, T>::iterator.
@@ -943,7 +954,7 @@
 
     There is no direct way of changing an item's key through an
     iterator, although it can be done by calling QMap::erase()
-    followed by QMap::insert() or QMap::insertMulti().
+    followed by QMap::insert().
 
     \sa value()
 */
@@ -977,21 +988,21 @@
 */
 
 /*!
-    \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator==(const iterator &other) const
-    \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator==(const const_iterator &other) const
+    \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
+    \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
 
-    Returns \c true if \a other points to the same item as this
-    iterator; otherwise returns \c false.
+    Returns \c true if \a lhs points to the same item as the \a rhs iterator;
+    otherwise returns \c false.
 
     \sa operator!=()
 */
 
 /*!
-    \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator!=(const iterator &other) const
-    \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator!=(const const_iterator &other) const
+    \fn template <class Key, class T> bool QMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
+    \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
 
-    Returns \c true if \a other points to a different item than this
-    iterator; otherwise returns \c false.
+    Returns \c true if \a lhs points to a different item than the \a rhs iterator;
+    otherwise returns \c false.
 
     \sa operator==()
 */
@@ -1150,22 +1161,6 @@
     \sa value()
 */
 
-/*! \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator==(const const_iterator &other) const
-
-    Returns \c true if \a other points to the same item as this
-    iterator; otherwise returns \c false.
-
-    \sa operator!=()
-*/
-
-/*! \fn template <class Key, class T> bool QMap<Key, T>::const_iterator::operator!=(const const_iterator &other) const
-
-    Returns \c true if \a other points to a different item than this
-    iterator; otherwise returns \c false.
-
-    \sa operator==()
-*/
-
 /*! \fn template <class Key, class T> QMap<Key, T>::const_iterator &QMap<Key, T>::const_iterator::operator++()
 
     The prefix ++ operator (\c{++i}) advances the iterator to the
diff --git a/src/corelib/tools/qmultimap.qdoc b/src/corelib/tools/qmultimap.qdoc
index 01b2f17c73..8b3337e59b 100644
--- a/src/corelib/tools/qmultimap.qdoc
+++ b/src/corelib/tools/qmultimap.qdoc
@@ -259,9 +259,10 @@
     fast and never fails.
 */
 
-/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::operator==(const QMultiMap<Key, T> &other) const
+/*! \fn template<class Key, class T> bool operator==(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
+    \relates QMultiMap
 
-    Returns \c true if \a other is equal to this multi map; otherwise returns
+    Returns \c true if \a lhs is equal to \a rhs; otherwise returns
     false.
 
     Two multi maps are considered equal if they contain the same (key,
@@ -273,9 +274,10 @@
     \sa operator!=()
 */
 
-/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::operator!=(const QMultiMap<Key, T> &other) const
+/*! \fn template<class Key, class T> bool operator!=(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
+    \relates QMultiMap
 
-    Returns \c true if \a other is not equal to this multi map; otherwise
+    Returns \c true if \a lhs is not equal to \a rhs; otherwise
     returns \c false.
 
     Two multi maps are considered equal if they contain the same (key,
@@ -411,7 +413,7 @@
     items for \a key in the multi map, the value of the most recently
     inserted one is returned.
 
-    \sa key(), values(), contains(), operator[]()
+    \sa key(), values(), contains()
 */
 
 /*! \fn template <class Key, class T> QList<Key> QMultiMap<Key, T>::keys() const
@@ -819,7 +821,7 @@
     \sa replace()
 */
 
-/*! \fn [qmultimap-insert-pos] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
+/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(const_iterator pos, const Key &key, const T &value)
     \overload
     \since 5.1
     Inserts a new item with the key \a key and value \a value and with hint \a pos
@@ -842,21 +844,35 @@
     crash but there is also a risk that it will silently corrupt both the multi map and the \a pos multi map.
 */
 
+#if QT_DEPRECATED_SINCE(6, 0)
 /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const Key &key, const T &value)
+    \obsolete Use insert() instead.
 
-    Same as insert().
+    Inserts a new item with the key \a key and a value of \a value, and returns an iterator pointing to the new item.
 */
 
 /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insertMulti(const_iterator pos, const Key &key, const T &value)
+    \obsolete Use insert() instead.
     \overload
 
-    Same as insert().
+    Inserts a new item with the key \a key and value \a value and with hint \a pos
+    suggesting where to do the insert.
 */
 
 /*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(const QMultiMap<Key, T> &map)
     \since 5.15
+    \obsolete Use unite() instead.
 
-    Same as unite().
+    Inserts all the items in \a map into this map.
+*/
+#endif
+
+/*! \fn template <class Key, class T> void QMultiMap<Key, T>::insert(QMultiMap<Key, T> &&map)
+    \since 5.15
+
+    Moves all the items from \a map into this map.
+
+    If \a map is shared, then the items will be copied instead.
 */
 
 /*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::replace(const Key &key, const T &value)
@@ -924,25 +940,25 @@
 */
 
 /*!
-    \fn [qmultimap-unite] template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
+    \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
 
     Inserts all the items in the \a other map into this map. If a
     key is common to both maps, the resulting map will contain the
     key multiple times.
 */
 
-/*! \fn template <class Key, class T> QMultiMap &QMultiMap<Key, T>::operator+=(const QMultiMap &other)
+/*! \fn template <class Key, class T> QMultiMap<Key, T> operator+=(QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
 
-    Inserts all the items in the \a other map into this map and
-    returns a reference to this map.
+    Inserts all the items in the \a rhs map into the \a lhs map and
+    returns the resulting map.
 
     \sa insert(), operator+()
 */
 
-/*! \fn template <class Key, class T> QMultiMap QMultiMap<Key, T>::operator+(const QMultiMap &other) const
+/*! \fn template <class Key, class T> QMultiMap<Key, T> operator+(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
 
-    Returns a map that contains all the items in this map in
-    addition to all the items in \a other. If a key is common to both
+    Returns a map that contains all the items in the \a lhs map in
+    addition to all the items in \a rhs. If a key is common to both
     maps, the resulting map will contain the key multiple times.
 
     \sa operator+=()
@@ -1094,21 +1110,21 @@
 */
 
 /*!
-    \fn template <class Key, class T> bool QMultiMap<Key, T>::iterator::operator==(const iterator &other) const
-    \fn template <class Key, class T> bool QMultiMap<Key, T>::iterator::operator==(const const_iterator &other) const
+    \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator==(const iterator &lhs, const iterator &rhs)
+    \fn template<class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator==(const const_iterator &lhs, const const_iterator &rhs)
 
-    Returns \c true if \a other points to the same item as this
-    iterator; otherwise returns \c false.
+    Returns \c true if \a lhs points to the same item as the \a rhs iterator;
+    otherwise returns \c false.
 
     \sa operator!=()
 */
 
 /*!
-    \fn template <class Key, class T> bool QMultiMap<Key, T>::iterator::operator!=(const iterator &other) const
-    \fn template <class Key, class T> bool QMultiMap<Key, T>::iterator::operator!=(const const_iterator &other) const
+    \fn template<class Key, class T> bool QMultiMap<Key, T>::iterator::operator!=(const iterator &lhs, const iterator &rhs)
+    \fn template<class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator!=(const const_iterator &lhs, const const_iterator &rhs)
 
-    Returns \c true if \a other points to a different item than this
-    iterator; otherwise returns \c false.
+    Returns \c true if \a lhs points to a different item than the \a rhs iterator;
+    otherwise returns \c false.
 
     \sa operator==()
 */
@@ -1269,22 +1285,6 @@
     \sa value()
 */
 
-/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator==(const const_iterator &other) const
-
-    Returns \c true if \a other points to the same item as this
-    iterator; otherwise returns \c false.
-
-    \sa operator!=()
-*/
-
-/*! \fn template <class Key, class T> bool QMultiMap<Key, T>::const_iterator::operator!=(const const_iterator &other) const
-
-    Returns \c true if \a other points to a different item than this
-    iterator; otherwise returns \c false.
-
-    \sa operator==()
-*/
-
 /*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator &QMultiMap<Key, T>::const_iterator::operator++()
 
     The prefix ++ operator (\c{++i}) advances the iterator to the