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>

1 files changed, 19 insertions, 16 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;
     }
 };