Fix docs for comparison/debug/data stream operators of Qt containers

Because of the constraints on comparison, debug and data stream
operators, the return types for them look weird in docs. Conditionally
use the actual return types, in case if Q_CLANG_QDOC is defined.

Also add the docs of debug stream operators for types for which they
were misssing.

Task-number: QTBUG-97247
Pick-to: 6.2
Change-Id: I57f2c52bd3af805c7eeebb602c47de1e95ee09bd
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

8 files changed, 161 insertions, 0 deletions

diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp
index 1889a4c3a2..a7ce66ad14 100644
--- a/src/corelib/io/qdebug.cpp
+++ b/src/corelib/io/qdebug.cpp
@@ -856,6 +856,14 @@ QDebug &QDebug::resetFormat()
 */
 
 /*!
+    \fn template <class Key, class T> QDebug operator<<(QDebug debug, const QMultiMap<Key, T> &map)
+    \relates QDebug
+
+    Writes the contents of \a map to \a debug. Both \c Key and
+    \c T need to support streaming into QDebug.
+*/
+
+/*!
     \fn template <typename Key, typename T, typename Compare, typename Alloc> QDebug operator<<(QDebug debug, const std::map<Key, T, Compare, Alloc> &map)
     \relates QDebug
     \since 5.7
@@ -882,6 +890,14 @@ QDebug &QDebug::resetFormat()
 */
 
 /*!
+    \fn template <class Key, class T> QDebug operator<<(QDebug debug, const QMultiHash<Key, T> &hash)
+    \relates QDebug
+
+    Writes the contents of \a hash to \a debug. Both \c Key and
+    \c T need to support streaming into QDebug.
+*/
+
+/*!
     \fn template <class T1, class T2> QDebug operator<<(QDebug debug, const QPair<T1, T2> &pair)
     \relates QDebug
 
@@ -890,6 +906,22 @@ QDebug &QDebug::resetFormat()
 */
 
 /*!
+    \fn template <class T1, class T2> QDebug operator<<(QDebug debug, const std::pair<T1, T2> &pair)
+    \relates QDebug
+
+    Writes the contents of \a pair to \a debug. Both \c T1 and
+    \c T2 need to support streaming into QDebug.
+*/
+
+/*!
+    \fn template <typename T> QDebug operator<<(QDebug debug, const QContiguousCache<T> &cache)
+    \relates QDebug
+
+    Writes the contents of \a cache to \a debug. \c T needs to
+    support streaming into QDebug.
+*/
+
+/*!
     \fn template<typename T> QDebug operator<<(QDebug debug, const QFlags<T> &flags)
     \relates QDebug
     \since 4.7
diff --git a/src/corelib/io/qdebug.h b/src/corelib/io/qdebug.h
index 1c72c43ec3..2b6522daa1 100644
--- a/src/corelib/io/qdebug.h
+++ b/src/corelib/io/qdebug.h
@@ -248,6 +248,8 @@ template<typename Container, typename ...T>
 using QDebugIfHasDebugStreamContainer =
     std::enable_if_t<std::conjunction_v<QTypeTraits::has_ostream_operator_container<QDebug, Container, T>...>, QDebug>;
 
+#ifndef Q_CLANG_QDOC
+
 template<typename T>
 inline QDebugIfHasDebugStreamContainer<QList<T>, T> operator<<(QDebug debug, const QList<T> &vec)
 {
@@ -336,6 +338,51 @@ inline QDebugIfHasDebugStream<T> operator<<(QDebug debug, const QContiguousCache
     return debug;
 }
 
+#else
+template <class T>
+QDebug operator<<(QDebug debug, const QList<T> &list);
+
+template <class T, qsizetype P>
+QDebug operator<<(QDebug debug, const QVarLengthArray<T, P> &array);
+
+template <typename T, typename Alloc>
+QDebug operator<<(QDebug debug, const std::vector<T, Alloc> &vec);
+
+template <typename T, typename Alloc>
+QDebug operator<<(QDebug debug, const std::list<T, Alloc> &vec);
+
+template <typename Key, typename T, typename Compare, typename Alloc>
+QDebug operator<<(QDebug debug, const std::map<Key, T, Compare, Alloc> &map);
+
+template <typename Key, typename T, typename Compare, typename Alloc>
+QDebug operator<<(QDebug debug, const std::multimap<Key, T, Compare, Alloc> &map);
+
+template <class Key, class T>
+QDebug operator<<(QDebug debug, const QMap<Key, T> &map);
+
+template <class Key, class T>
+QDebug operator<<(QDebug debug, const QMultiMap(<Key, T> &map);
+
+template <class Key, class T>
+QDebug operator<<(QDebug debug, const QHash<Key, T> &hash);
+
+template <class Key, class T>
+QDebug operator<<(QDebug debug, const QMultiHash<Key, T> &hash);
+
+template <typename T>
+QDebug operator<<(QDebug debug, const QSet<T> &set);
+
+template <class T1, class T2>
+QDebug operator<<(QDebug debug, const QPair<T1, T2> &pair);
+
+template <class T1, class T2>
+QDebug operator<<(QDebug debug, const std::pair<T1, T2> &pair);
+
+template <typename T>
+QDebug operator<<(QDebug debug, const QContiguousCache<T> &cache);
+
+#endif // Q_CLANG_QDOC
+
 template <class T>
 inline QDebug operator<<(QDebug debug, const QSharedPointer<T> &ptr)
 {
diff --git a/src/corelib/serialization/qdatastream.h b/src/corelib/serialization/qdatastream.h
index 24b5d82606..a21cf4ebbf 100644
--- a/src/corelib/serialization/qdatastream.h
+++ b/src/corelib/serialization/qdatastream.h
@@ -434,6 +434,8 @@ typename std::enable_if_t<std::is_enum<T>::value, QDataStream &>
 operator>>(QDataStream &s, T &t)
 { return s >> reinterpret_cast<typename std::underlying_type<T>::type &>(t); }
 
+#ifndef Q_CLANG_QDOC
+
 template<typename T>
 inline QDataStreamIfHasIStreamOperatorsContainer<QList<T>, T> operator>>(QDataStream &s, QList<T> &v)
 {
@@ -523,6 +525,52 @@ inline QDataStreamIfHasOStreamOperators<T1, T2> operator<<(QDataStream& s, const
 }
 #endif
 
+#else
+
+template <class T>
+QDataStream &operator>>(QDataStream &s, QList<T> &l);
+
+template <class T>
+QDataStream &operator<<(QDataStream &s, const QList<T> &l);
+
+template <class T>
+QDataStream &operator>>(QDataStream &s, QSet<T> &set);
+
+template <class T>
+QDataStream &operator<<(QDataStream &s, const QSet<T> &set);
+
+template <class Key, class T>
+QDataStream &operator>>(QDataStream &s, QHash<Key, T> &hash);
+
+template <class Key, class T>
+QDataStream &operator<<(QDataStream &s, const QHash<Key, T> &hash);
+
+template <class Key, class T>
+QDataStream &operator>>(QDataStream &s, QMultiHash<Key, T> &hash);
+
+template <class Key, class T>
+QDataStream &operator<<(QDataStream &s, const QMultiHash<Key, T> &hash);
+
+template <class Key, class T>
+QDataStream &operator>>(QDataStream &s, QMap<Key, T> &map);
+
+template <class Key, class T>
+QDataStream &operator<<(QDataStream &s, const QMap<Key, T> &map);
+
+template <class Key, class T>
+QDataStream &operator>>(QDataStream &s, QMultiMap<Key, T> &map);
+
+template <class Key, class T>
+QDataStream &operator<<(QDataStream &s, const QMultiMap<Key, T> &map);
+
+template <class T1, class T2>
+QDataStream &operator>>(QDataStream& s, std::pair<T1, T2> &p);
+
+template <class T1, class T2>
+QDataStream &operator<<(QDataStream& s, const std::pair<T1, T2> &p);
+
+#endif // Q_CLANG_QDOC
+
 inline QDataStream &operator>>(QDataStream &s, QKeyCombination &combination)
 {
     int combined;
diff --git a/src/corelib/tools/qcontiguouscache.h b/src/corelib/tools/qcontiguouscache.h
index f0f5ac5dcb..62ebfa0658 100644
--- a/src/corelib/tools/qcontiguouscache.h
+++ b/src/corelib/tools/qcontiguouscache.h
@@ -99,6 +99,7 @@ public:
     QT_MOVE_ASSIGNMENT_OPERATOR_IMPL_VIA_PURE_SWAP(QContiguousCache)
     inline void swap(QContiguousCache<T> &other) noexcept { qSwap(d, other.d); }
 
+#ifndef Q_CLANG_QDOC
     template <typename U = T>
     QTypeTraits::compare_eq_result<U> operator==(const QContiguousCache<T> &other) const
     {
@@ -117,6 +118,10 @@ public:
     template <typename U = T>
     QTypeTraits::compare_eq_result<U> operator!=(const QContiguousCache<T> &other) const
     { return !(*this == other); }
+#else
+    bool operator==(const QContiguousCache &other) const;
+    bool operator!=(const QContiguousCache &other) const;
+#endif // Q_CLANG_QDOC
 
     inline qsizetype capacity() const {return d->alloc; }
     inline qsizetype count() const { return d->count; }
diff --git a/src/corelib/tools/qhash.h b/src/corelib/tools/qhash.h
index a738865a17..fb4b3f3198 100644
--- a/src/corelib/tools/qhash.h
+++ b/src/corelib/tools/qhash.h
@@ -830,6 +830,7 @@ public:
 #endif
     void swap(QHash &other) noexcept { qSwap(d, other.d); }
 
+#ifndef Q_CLANG_QDOC
     template <typename U = T>
     QTypeTraits::compare_eq_result_container<QHash, U> operator==(const QHash &other) const noexcept
     {
@@ -849,6 +850,10 @@ public:
     template <typename U = T>
     QTypeTraits::compare_eq_result_container<QHash, U> operator!=(const QHash &other) const noexcept
     { return !(*this == other); }
+#else
+    bool operator==(const QHash &other) const;
+    bool operator!=(const QHash &other) const;
+#endif // Q_CLANG_QDOC
 
     inline qsizetype size() const noexcept { return d ? qsizetype(d->size) : 0; }
     inline bool isEmpty() const noexcept { return !d || d->size == 0; }
diff --git a/src/corelib/tools/qlist.h b/src/corelib/tools/qlist.h
index 0b33fc1d7b..9b2a56a66a 100644
--- a/src/corelib/tools/qlist.h
+++ b/src/corelib/tools/qlist.h
@@ -356,6 +356,7 @@ public:
 
     void swap(QList<T> &other) noexcept { qSwap(d, other.d); }
 
+#ifndef Q_CLANG_QDOC
     template <typename U = T>
     QTypeTraits::compare_eq_result_container<QList, U> operator==(const QList &other) const
     {
@@ -404,6 +405,14 @@ public:
     {
         return !(*this < other);
     }
+#else
+    bool operator==(const QList &other) const;
+    bool operator!=(const QList &other) const;
+    bool operator<(const QList &other) const;
+    bool operator>(const QList &other) const;
+    bool operator<=(const QList &other) const;
+    bool operator>=(const QList &other) const;
+#endif // Q_CLANG_QDOC
 
     qsizetype size() const noexcept { return d->size; }
     qsizetype count() const noexcept { return size(); }
diff --git a/src/corelib/tools/qmap.h b/src/corelib/tools/qmap.h
index b2053127fe..7fd6e4d705 100644
--- a/src/corelib/tools/qmap.h
+++ b/src/corelib/tools/qmap.h
@@ -276,6 +276,7 @@ public:
         return {};
     }
 
+#ifndef Q_CLANG_QDOC
     template <typename AKey = Key, typename AT = T> friend
     QTypeTraits::compare_eq_result_container<QMap, AKey, AT> operator==(const QMap &lhs, const QMap &rhs)
     {
@@ -293,6 +294,10 @@ public:
         return !(lhs == rhs);
     }
     // TODO: add the other comparison operators; std::map has them.
+#else
+    friend bool operator==(const QMap &lhs, const QMap &rhs);
+    friend bool operator!=(const QMap &lhs, const QMap &rhs);
+#endif // Q_CLANG_QDOC
 
     size_type size() const { return d ? size_type(d->m.size()) : size_type(0); }
 
@@ -904,6 +909,7 @@ public:
         return {};
     }
 
+#ifndef Q_CLANG_QDOC
     template <typename AKey = Key, typename AT = T> friend
     QTypeTraits::compare_eq_result_container<QMultiMap, AKey, AT> operator==(const QMultiMap &lhs, const QMultiMap &rhs)
     {
@@ -921,6 +927,10 @@ public:
         return !(lhs == rhs);
     }
     // TODO: add the other comparison operators; std::multimap has them.
+#else
+    friend bool operator==(const QMultiMap &lhs, const QMultiMap &rhs);
+    friend bool operator!=(const QMultiMap &lhs, const QMultiMap &rhs);
+#endif // Q_CLANG_QDOC
 
     size_type size() const { return d ? size_type(d->m.size()) : size_type(0); }
 
diff --git a/src/corelib/tools/qset.h b/src/corelib/tools/qset.h
index 9aecbff5bc..299851bf8d 100644
--- a/src/corelib/tools/qset.h
+++ b/src/corelib/tools/qset.h
@@ -71,12 +71,17 @@ public:
 
     inline void swap(QSet<T> &other) noexcept { q_hash.swap(other.q_hash); }
 
+#ifndef Q_CLANG_QDOC
     template <typename U = T>
     QTypeTraits::compare_eq_result_container<QSet, U> operator==(const QSet<T> &other) const
     { return q_hash == other.q_hash; }
     template <typename U = T>
     QTypeTraits::compare_eq_result_container<QSet, U> operator!=(const QSet<T> &other) const
     { return q_hash != other.q_hash; }
+#else
+    bool operator==(const QSet &other) const;
+    bool operator!=(const QSet &other) const;
+#endif
 
     inline qsizetype size() const { return q_hash.size(); }