From 8a8bf1b84e9a096993b892873eb62c735149f320 Mon Sep 17 00:00:00 2001
From: Sona Kurazyan <sona.kurazyan@qt.io>
Date: Fri, 8 Oct 2021 18:06:49 +0200
Subject: [PATCH] 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>
---
 src/corelib/io/qdebug.cpp               | 32 +++++++++++++++++
 src/corelib/io/qdebug.h                 | 47 ++++++++++++++++++++++++
 src/corelib/serialization/qdatastream.h | 48 +++++++++++++++++++++++++
 src/corelib/tools/qcontiguouscache.h    |  5 +++
 src/corelib/tools/qhash.h               |  5 +++
 src/corelib/tools/qlist.h               |  9 +++++
 src/corelib/tools/qmap.h                | 10 ++++++
 src/corelib/tools/qset.h                |  5 +++
 8 files changed, 161 insertions(+)

diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp
index 1889a4c3a24..a7ce66ad148 100644
--- a/src/corelib/io/qdebug.cpp
+++ b/src/corelib/io/qdebug.cpp
@@ -855,6 +855,14 @@ QDebug &QDebug::resetFormat()
     \c T need to support streaming into QDebug.
 */
 
+/*!
+    \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
@@ -881,6 +889,14 @@ QDebug &QDebug::resetFormat()
     \c T need to support streaming into QDebug.
 */
 
+/*!
+    \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
@@ -889,6 +905,22 @@ QDebug &QDebug::resetFormat()
     \c T2 need to support streaming into QDebug.
 */
 
+/*!
+    \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
diff --git a/src/corelib/io/qdebug.h b/src/corelib/io/qdebug.h
index 1c72c43ec36..2b6522daa16 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 24b5d826060..a21cf4ebbfb 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 f0f5ac5dcbe..62ebfa0658c 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 a738865a175..fb4b3f3198e 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 0b33fc1d7b1..9b2a56a66a0 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 b2053127fef..7fd6e4d705f 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 9aecbff5bce..299851bf8d6 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(); }