AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fix qdoc warnings for QMap/QMultiMap

Browse Source 
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>
This commit is contained in:
Volker Hilsheimer 2020-09-26 16:19:58 +02:00
parent 752665cd9c
commit f518f01be6
3 changed files with 79 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
src/corelib/tools/qmap.h
View File

@ -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;
}
};

45
src/corelib/tools/qmap.qdoc
View File

@ -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

80
src/corelib/tools/qmultimap.qdoc
View File

@ -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