Create qdoc macros for C++ class docs 2.1: qHash()

Add a family of qdoc macros to document the various qHash() overloads
we have.

This patch does not change the \relates of the qHash() functions, they
remain as inconsistent as they have been. Created QTBUG-129815 to
clean things up. Since this author expects the \relates to change in
the future, there are different \qhash commands, and all except
\qhashbuiltin take the class name as an argument, for use in a
centrally-choreographed fix for QTBUG-129815.

As drive-by's, fix:
- missing documentation about Key having to support qHash() in the
  associative Qt containers
- drop noexcept and default arguments from \fn lines that needed to
  have their argument names changed
- move the QStringView overload from qhash.cpp to qstringview.cpp
  (as it \relates to the former)

Fixes: QTBUG-129574
Pick-to: 6.8 6.5
Change-Id: I8e8c2edc27422cbe5823f56baf3a24d7f7050836
Reviewed-by: Ivan Solovev <[email protected]>
Reviewed-by: Jaishree Vyas <[email protected]>

42 files changed, 170 insertions, 286 deletions

diff --git a/doc/global/cpp-doc-macros.qdocconf b/doc/global/cpp-doc-macros.qdocconf
index 5de60c20de5..d254ee817fe 100644
--- a/doc/global/cpp-doc-macros.qdocconf
+++ b/doc/global/cpp-doc-macros.qdocconf
@@ -13,3 +13,58 @@ macro.memberswap = \
     "\n\n" \
     "Swaps this \1 with \\a{other}. This operation is very fast and never fails." \
     "\n\n"
+
+#
+# Macros for qHash()
+#
+
+macro.implqhashT = \
+    "\n\n" \
+    "Type \\c{\1} must be supported by qHash()." \
+    "\n\n"
+
+macro.implqhashTS = \
+    "\n\n" \
+    "Types \\c{\1} and \\c{\2} must be supported by qHash()." \
+    "\n\n"
+
+# \qhash{QClass} - generates qHash() doc for (hidden-friend) qHash() overloads
+# \qhashT{QClass}{T}
+# \qhashTS{QClass}{T}{S}
+#   QClass - the class being hashed (without decoration such as \c const, \c{&} or \c{<T>})
+#   T      - the first template argument's name, if any
+#   S      - the second template argument's name, if any
+#   The function's argument names must be \a key and \a seed, resp.
+macro.qhash = \
+    "\n\n" \
+    "Returns the hash value for \\a key, using \\a seed to seed the calculation." \
+    "\\omit \1 \\endomit" \
+    "\n\n"
+macro.qhashT = "\\qhash{\1}\\implqhashT{\2}"
+macro.qhashTS = "\\qhash{\1}\\implqhashTS{\2}{\3}"
+
+# \qhashold{QClass} - generates qHash() docs for (non-hidden-friend) qHash() overloads
+#                     of class type. These should eventually go away
+# \qhasholdT{QClass}{T}
+# \qhasholdTS{QClass}{T}{S}
+#   QClass - the class being hashed (used for \relates)
+#   T      - the first template argument's name, if any
+#   S      - the second template argument's name, if any
+#   The function's argument names must be \a key and \a seed, resp.
+macro.qhashold = \
+    "\n\n" \
+    "\\relates \1" \
+    "\\qhash{\1}"
+macro.qhasholdT = "\\qhashold{\1}\\implqhashT{\2}"
+macro.qhasholdTS = "\\qhashold{\1}\\implqhashTS{\2}{\3}"
+
+# \qhashbuiltin (no arguments)
+# \qhashbuiltinT{T}
+# \qhashbuiltinTS{T}{S}
+#   For language-provided (built-in) types
+#   T      - the first template argument's name, if any
+#   S      - the second template argument's name, if any
+#   The function's argument names must be \a key and \a seed, resp.
+macro.qhashbuiltin = "\\qhashold{QHash}"
+macro.qhashbuiltinT = "\\qhashbuiltin\\implqhashT{\1}"
+macro.qhashbuiltinTS = "\\qhashbuiltin\\implqhashTS{\1}{\2}"
diff --git a/src/corelib/global/qflags.qdoc b/src/corelib/global/qflags.qdoc
index 29d6784cae6..64337bd2f60 100644
--- a/src/corelib/global/qflags.qdoc
+++ b/src/corelib/global/qflags.qdoc
@@ -424,12 +424,9 @@
 */
 
 /*!
-    \fn template <typename Enum> size_t qHash(QFlags<Enum> flags, size_t seed = 0) noexcept
+    \fn template <typename Enum> size_t qHash(QFlags<Enum> key, size_t seed)
     \since 6.2
-    \relates QFlags
-
-    Calculates the hash for the flags \a flags, using \a seed
-    to seed the calculation.
+    \qhashold{QFlags}
 */
 
 /*!
diff --git a/src/corelib/global/qfloat16.cpp b/src/corelib/global/qfloat16.cpp
index f6f782e364a..d22c4f48b3f 100644
--- a/src/corelib/global/qfloat16.cpp
+++ b/src/corelib/global/qfloat16.cpp
@@ -375,9 +375,7 @@ Q_CORE_EXPORT void qFloatFromFloat16(float *out, const qfloat16 *in, qsizetype l
 /*!
     \fn size_t qfloat16::qHash(qfloat16 key, size_t seed)
     \since 6.5.3
-
-    Returns the hash value for the \a key, using \a seed to seed the
-    calculation.
+    \qhash{qfloat16}
 
     \note In Qt versions before 6.5, this operation was provided by the
     qHash(float) overload. In Qt versions 6.5.0 to 6.5.2, this functionality
diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 2793fdce4c3..e3ad9b6195a 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -3570,9 +3570,7 @@
 
 /*!
   \fn size_t qHash(QKeyCombination key, size_t seed = 0) noexcept
-  \relates QKeyCombination
-
-  Returns the hash value for the \a key, using \a seed to seed the calculation.
+  \qhashold{QKeyCombination}
 */
 
 #ifndef QT_NO_DEBUG_STREAM
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index 6038639eabf..d206df7c6c4 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -3616,10 +3616,8 @@ QList<QUrl> QUrl::fromStringList(const QStringList &urls, ParsingMode mode)
 */
 
 /*!
-    Returns the hash value for the \a url. If specified, \a seed is used to
-    initialize the hash.
-
-    \relates QHash
+    \fn size_t qHash(const QUrl &key, size_t seed)
+    \qhashold{QHash}
     \since 5.0
 */
 size_t qHash(const QUrl &url, size_t seed) noexcept
diff --git a/src/corelib/io/qurlquery.cpp b/src/corelib/io/qurlquery.cpp
index bbd9a64cad5..70303273045 100644
--- a/src/corelib/io/qurlquery.cpp
+++ b/src/corelib/io/qurlquery.cpp
@@ -423,10 +423,7 @@ bool comparesEqual(const QUrlQuery &lhs, const QUrlQuery &rhs)
 
 /*!
     \since 5.6
-    \relates QUrlQuery
-
-    Returns the hash value for \a key,
-    using \a seed to seed the calculation.
+    \qhashold{QUrlQuery}
 */
 size_t qHash(const QUrlQuery &key, size_t seed) noexcept
 {
diff --git a/src/corelib/ipc/qtipccommon.cpp b/src/corelib/ipc/qtipccommon.cpp
index 2b71456bdc1..3d9a7281a00 100644
--- a/src/corelib/ipc/qtipccommon.cpp
+++ b/src/corelib/ipc/qtipccommon.cpp
@@ -497,9 +497,8 @@ void QNativeIpcKey::setNativeKey_internal(const QString &)
 }
 
 /*!
-    \fn size_t QNativeIpcKey::qHash(const QNativeIpcKey &ipcKey, size_t seed) noexcept
-
-    Returns the hash value for \a ipcKey, using \a seed to seed the calculation.
+    \fn size_t QNativeIpcKey::qHash(const QNativeIpcKey &key, size_t seed)
+    \qhash{QNativeIpcKey}
 */
 size_t qHash(const QNativeIpcKey &ipcKey, size_t seed) noexcept
 {
diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp
index 1b72c917fea..c298b0ca041 100644
--- a/src/corelib/itemmodels/qabstractitemmodel.cpp
+++ b/src/corelib/itemmodels/qabstractitemmodel.cpp
@@ -4156,12 +4156,9 @@ bool QAbstractListModel::dropMimeData(const QMimeData *data, Qt::DropAction acti
 */
 
 /*!
-    \fn size_t qHash(const QPersistentModelIndex &index, size_t seed = 0)
+    \fn size_t qHash(const QPersistentModelIndex &key, size_t seed)
     \since 5.0
-    \relates QPersistentModelIndex
-
-    Returns a hash of the QPersistentModelIndex \a index, using \a seed to
-    seed the calculation.
+    \qhashold{QPersistentModelIndex}
 */
 
 
diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index 417f3bbc14c..045f1e80d4a 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -3277,11 +3277,10 @@ static const QtPrivate::QMetaTypeInterface *interfaceForType(int typeId)
 QMetaType::QMetaType(int typeId) : QMetaType(interfaceForType(typeId)) {}
 
 
-/*! \fn size_t qHash(QMetaType type, size_t seed = 0)
-    \relates QMetaType
+/*!
+    \fn size_t qHash(QMetaType key, size_t seed)
+    \qhashold{QMetaType}
     \since 6.4
-
-    Returns the hash value for the \a type, using \a seed to seed the calculation.
 */
 
 namespace QtPrivate {
diff --git a/src/corelib/mimetypes/qmimetype.cpp b/src/corelib/mimetypes/qmimetype.cpp
index d44989a050c..31622a21e73 100644
--- a/src/corelib/mimetypes/qmimetype.cpp
+++ b/src/corelib/mimetypes/qmimetype.cpp
@@ -123,10 +123,7 @@ bool comparesEqual(const QMimeType &lhs, const QMimeType &rhs) noexcept
 
 /*!
     \since 5.6
-    \relates QMimeType
-
-    Returns the hash value for \a key, using
-    \a seed to seed the calculation.
+    \qhashold{QMimeType}
  */
 size_t qHash(const QMimeType &key, size_t seed) noexcept
 {
diff --git a/src/corelib/plugin/quuid.cpp b/src/corelib/plugin/quuid.cpp
index 0b7349372a5..0b1615c6499 100644
--- a/src/corelib/plugin/quuid.cpp
+++ b/src/corelib/plugin/quuid.cpp
@@ -970,9 +970,9 @@ QDebug operator<<(QDebug dbg, const QUuid &id)
 #endif
 
 /*!
+    \fn size_t qHash(const QUuid &key, size_t seed)
     \since 5.0
-    \relates QUuid
-    Returns a hash of the UUID \a uuid, using \a seed to seed the calculation.
+    \qhashold{QUuid}
 */
 size_t qHash(const QUuid &uuid, size_t seed) noexcept
 {
diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index 0b3999b10c7..496d6eca7fc 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -5134,10 +5134,7 @@ emscripten::val QByteArray::toEcmaUint8Array()
 */
 
 /*!
-    \relates QByteArray::FromBase64Result
-
-    Returns the hash value for \a key, using
-    \a seed to seed the calculation.
+    \qhashold{QByteArray::FromBase64Result}
 */
 size_t qHash(const QByteArray::FromBase64Result &key, size_t seed) noexcept
 {
diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp
index 48996eaacbb..e0af809c0b6 100644
--- a/src/corelib/text/qlocale.cpp
+++ b/src/corelib/text/qlocale.cpp
@@ -1266,10 +1266,7 @@ bool QLocale::equals(const QLocale &other) const noexcept
 
 /*!
     \since 5.6
-    \relates QLocale
-
-    Returns the hash value for \a key, using
-    \a seed to seed the calculation.
+    \qhashold{QLocale}
 */
 size_t qHash(const QLocale &key, size_t seed) noexcept
 {
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp
index ad6d618bc59..1510c31bca5 100644
--- a/src/corelib/text/qstringview.cpp
+++ b/src/corelib/text/qstringview.cpp
@@ -163,6 +163,12 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \fn size_t qHash(QStringView key, size_t seed)
+    \since 5.10
+    \qhashold{QStringView}
+*/
+
+/*!
     \fn QStringView::QStringView()
 
     Constructs a null string view.
diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp
index e9a0bd07f84..0ec01da2be2 100644
--- a/src/corelib/time/qdatetime.cpp
+++ b/src/corelib/time/qdatetime.cpp
@@ -6273,10 +6273,8 @@ QDebug operator<<(QDebug dbg, const QDateTime &date)
 #endif // debug_stream && datestring
 
 /*! \fn size_t qHash(const QDateTime &key, size_t seed = 0)
-    \relates QHash
+    \qhashold{QHash}
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
 */
 size_t qHash(const QDateTime &key, size_t seed)
 {
@@ -6288,10 +6286,8 @@ size_t qHash(const QDateTime &key, size_t seed)
 }
 
 /*! \fn size_t qHash(QDate key, size_t seed = 0)
-    \relates QHash
+    \qhashold{QHash}
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
 */
 size_t qHash(QDate key, size_t seed) noexcept
 {
@@ -6299,10 +6295,8 @@ size_t qHash(QDate key, size_t seed) noexcept
 }
 
 /*! \fn size_t qHash(QTime key, size_t seed = 0)
-    \relates QHash
+    \qhashold{QHash}
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
 */
 size_t qHash(QTime key, size_t seed) noexcept
 {
diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index 6c8aef1c744..6035276ca0a 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -1101,11 +1101,7 @@ uint qt_hash(QStringView key, uint chained) noexcept
 /*!
     \fn template <typename T1, typename T2> size_t qHash(const std::pair<T1, T2> &key, size_t seed = 0)
     \since 5.7
-    \relates QHash
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
-
-    Types \c T1 and \c T2 must be supported by qHash().
+    \qhashbuiltinTS{T1}{T2}
 */
 
 /*!
@@ -1248,10 +1244,9 @@ uint qt_hash(QStringView key, uint chained) noexcept
 
 /*!
     \fn template <typname T, std::enable_if_t<std::is_same_v<T, bool>, bool> = true> size_t qHash(T key, size_t seed)
-    \relates QHash
     \since 6.9
 
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 
     \note This is qHash(bool), constrained to accept only arguments of type bool,
     not arguments of types that merely convert to bool.
@@ -1261,141 +1256,104 @@ uint qt_hash(QStringView key, uint chained) noexcept
 */
 
 /*! \fn size_t qHash(char key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(uchar key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(signed char key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(ushort key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(short key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(uint key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(int key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(ulong key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(long key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(quint64 key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(qint64 key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(quint128 key, size_t seed = 0)
-    \relates QHash
     \since 6.8
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 
     \note This function is only available on platforms that support a native
     128-bit integer type.
 */
 
 /*! \fn size_t qHash(qint128 key, size_t seed = 0)
-    \relates QHash
     \since 6.8
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 
     \note This function is only available on platforms that support a native
     128-bit integer type.
  */
 
 /*! \fn size_t qHash(char8_t key, size_t seed = 0)
-    \relates QHash
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(char16_t key, size_t seed = 0)
-    \relates QHash
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(char32_t key, size_t seed = 0)
-    \relates QHash
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(wchar_t key, size_t seed = 0)
-    \relates QHash
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(float key, size_t seed = 0) noexcept
-    \relates QHash
     \since 5.3
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
-/*! \relates QHash
+/*!
     \since 5.3
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 size_t qHash(double key, size_t seed) noexcept
 {
@@ -1410,10 +1368,9 @@ size_t qHash(double key, size_t seed) noexcept
     }
 }
 
-/*! \relates QHash
+/*!
     \since 5.3
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 size_t qHash(long double key, size_t seed) noexcept
 {
@@ -1429,66 +1386,43 @@ size_t qHash(long double key, size_t seed) noexcept
 }
 
 /*! \fn size_t qHash(const QChar key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QHash}
 */
 
 /*! \fn size_t qHash(const QByteArray &key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QHash}
 */
 
 /*! \fn size_t qHash(const QByteArrayView &key, size_t seed = 0)
-    \relates QHash
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QHash}
 */
 
 /*! \fn size_t qHash(const QBitArray &key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QHash}
 */
 
 /*! \fn size_t qHash(const QString &key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
-*/
-
-/*! \fn size_t qHash(QStringView key, size_t seed = 0)
-    \relates QStringView
-    \since 5.10
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QHash}
 */
 
 /*! \fn size_t qHash(QLatin1StringView key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QHash}
 */
 
 /*! \fn template <class T> size_t qHash(const T *key, size_t seed = 0)
-    \relates QHash
     \since 5.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn size_t qHash(std::nullptr_t key, size_t seed = 0)
-    \relates QHash
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashbuiltin
 */
 
 /*! \fn template<typename T> bool qHashEquals(const T &a, const T &b)
@@ -3914,21 +3848,13 @@ size_t qHash(long double key, size_t seed) noexcept
 /*!
     \fn template <class Key, class T> size_t qHash(const QHash<Key, T> &key, size_t seed = 0)
     \since 5.8
-    \relates QHash
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
-
-    Type \c T must be supported by qHash().
+    \qhasholdTS{QHash}{Key}{T}
 */
 
 /*!
     \fn template <class Key, class T> size_t qHash(const QMultiHash<Key, T> &key, size_t seed = 0)
     \since 5.8
-    \relates QMultiHash
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
-
-    Type \c T must be supported by qHash().
+    \qhasholdTS{QMultiHash}{Key}{T}
 */
 
 /*! \fn template <typename Key, typename T, typename Predicate> qsizetype erase_if(QHash<Key, T> &hash, Predicate pred)
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc
index bc5feac7a0f..026918694ba 100644
--- a/src/corelib/tools/qlist.qdoc
+++ b/src/corelib/tools/qlist.qdoc
@@ -429,12 +429,7 @@
 /*!
     \fn template <typename T> size_t qHash(const QList<T> &key, size_t seed = 0)
     \since 5.6
-    \relates QList
-
-    Returns the hash value for \a key,
-    using \a seed to seed the calculation.
-
-    This function requires qHash() to be overloaded for the value type \c T.
+    \qhasholdT{QList}{T}
 */
 
 /*! \fn template <typename T> qsizetype QList<T>::size() const
diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc
index 7f8414ed969..98439b2415c 100644
--- a/src/corelib/tools/qmap.qdoc
+++ b/src/corelib/tools/qmap.qdoc
@@ -1392,8 +1392,5 @@
 /*!
     \fn template <class Key, class T> size_t QMap<Key, T>::qHash(const QMap &key, size_t seed) noexcept
     \since 6.8
-
-    Returns the hash value for \a key, using \a seed to seed the calculation.
-
-    Types \c Key and \c T must be supported by qHash().
+    \qhashTS{QMap}{Key}{T}
 */
diff --git a/src/corelib/tools/qpoint.cpp b/src/corelib/tools/qpoint.cpp
index 775a3544699..7c9a677520d 100644
--- a/src/corelib/tools/qpoint.cpp
+++ b/src/corelib/tools/qpoint.cpp
@@ -450,12 +450,8 @@ QDebug operator<<(QDebug dbg, const QPointF &p)
 #endif
 
 /*!
-    \fn size_t qHash(QPoint key, size_t seed = 0)
-    \relates QHash
+    \qhashold{QHash}
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the
-    calculation.
 */
 size_t qHash(QPoint key, size_t seed) noexcept
 {
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
index d5eac370fae..2e71693bc75 100644
--- a/src/corelib/tools/qset.qdoc
+++ b/src/corelib/tools/qset.qdoc
@@ -869,11 +869,9 @@
 
 /*!
     \fn template <class T> size_t qHash(const QSet<T> &key, size_t seed = 0)
-    \relates QHash
+    \qhasholdT{QHash}{T}
     \since 5.5
 
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
-
     The hash value is independent of the order of elements in \a key, that is, sets
     that contain the same elements hash to the same value.
 */
diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp
index b1d6e80d1ae..e19ccca0069 100644
--- a/src/corelib/tools/qsharedpointer.cpp
+++ b/src/corelib/tools/qsharedpointer.cpp
@@ -980,10 +980,7 @@
 
 /*!
     \fn template <class T> qHash(const QSharedPointer<T> &key, size_t seed)
-    \relates QSharedPointer
-
-    Returns the hash value for \a key, using \a seed to seed the calculation.
-
+    \qhashold{QSharedPointer}
     \since 5.0
 */
 
diff --git a/src/corelib/tools/qtaggedpointer.qdoc b/src/corelib/tools/qtaggedpointer.qdoc
index cbd5989a65a..86155187b99 100644
--- a/src/corelib/tools/qtaggedpointer.qdoc
+++ b/src/corelib/tools/qtaggedpointer.qdoc
@@ -187,7 +187,5 @@
 
 /*!
     \fn template <typename T, typename Tag> qHash(QTaggedPointer<T, Tag> key, std::size_t seed = 0)
-    \relates QTaggedPointer
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhashold{QTaggedPointer}
 */
diff --git a/src/corelib/tools/qtyperevision.cpp b/src/corelib/tools/qtyperevision.cpp
index 6426236288a..df65a9c7571 100644
--- a/src/corelib/tools/qtyperevision.cpp
+++ b/src/corelib/tools/qtyperevision.cpp
@@ -203,11 +203,8 @@ QDebug operator<<(QDebug debug, const QTypeRevision &revision)
 #endif
 
 /*!
-    \relates QHash
+    \qhashold{QHash}
     \since 6.0
-
-    Returns the hash value for the \a key, using \a seed to seed the
-    calculation.
 */
 size_t qHash(const QTypeRevision &key, size_t seed)
 {
diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc
index b17aedc5335..0715f519448 100644
--- a/src/corelib/tools/qvarlengtharray.qdoc
+++ b/src/corelib/tools/qvarlengtharray.qdoc
@@ -950,11 +950,8 @@
 
 /*!
     \fn template <typename T, qsizetype Prealloc> size_t qHash(const QVarLengthArray<T, Prealloc> &key, size_t seed = 0)
-    \relates QVarLengthArray
+    \qhasholdT{QVarLengthArray}{T}
     \since 5.14
-
-    Returns the hash value for \a key, using \a seed to seed the
-    calculation.
 */
 
 /*! \fn template <typename T, qsizetype Prealloc> template <typename AT = T> qsizetype QVarLengthArray<T, Prealloc>::removeAll(const AT &t)
diff --git a/src/corelib/tools/qversionnumber.cpp b/src/corelib/tools/qversionnumber.cpp
index af95875b44b..57cfc1767f1 100644
--- a/src/corelib/tools/qversionnumber.cpp
+++ b/src/corelib/tools/qversionnumber.cpp
@@ -571,11 +571,8 @@ QDebug operator<<(QDebug debug, const QVersionNumber &version)
 #endif
 
 /*!
-    \relates QHash
+    \qhashold{QHash}
     \since 5.6
-
-    Returns the hash value for the \a key, using \a seed to seed the
-    calculation.
 */
 size_t qHash(const QVersionNumber &key, size_t seed)
 {
diff --git a/src/gui/image/qpixmapcache.cpp b/src/gui/image/qpixmapcache.cpp
index c5f0adeb386..ecb4a7421d6 100644
--- a/src/gui/image/qpixmapcache.cpp
+++ b/src/gui/image/qpixmapcache.cpp
@@ -221,8 +221,7 @@ QT_END_INCLUDE_NAMESPACE
 /*!
     \fn size_t QPixmapCache::Key::qHash(const Key &key, size_t seed)
     \since 6.6
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhash{QPixmapCache::Key}
 */
 size_t QPixmapCache::Key::hash(size_t seed) const noexcept
 {
diff --git a/src/gui/kernel/qkeysequence.cpp b/src/gui/kernel/qkeysequence.cpp
index ad9b3527f15..7e78ac5b08d 100644
--- a/src/gui/kernel/qkeysequence.cpp
+++ b/src/gui/kernel/qkeysequence.cpp
@@ -1410,10 +1410,7 @@ bool QKeySequence::operator==(const QKeySequence &other) const
 
 /*!
     \since 5.6
-    \relates QKeySequence
-
-    Calculates the hash value of \a key, using
-    \a seed to seed the calculation.
+    \qhashold{QKeySequence}
 */
 size_t qHash(const QKeySequence &key, size_t seed) noexcept
 {
diff --git a/src/gui/kernel/qpointingdevice.cpp b/src/gui/kernel/qpointingdevice.cpp
index 859d3e293ee..1f15b610570 100644
--- a/src/gui/kernel/qpointingdevice.cpp
+++ b/src/gui/kernel/qpointingdevice.cpp
@@ -810,10 +810,8 @@ qint64 QPointingDeviceUniqueId::numericId() const noexcept
 */
 
 /*!
-    \relates QPointingDeviceUniqueId
+    \qhashold{QPointingDeviceUniqueId}
     \since 5.8
-
-    Returns the hash value for \a key, using \a seed to seed the calculation.
 */
 size_t qHash(QPointingDeviceUniqueId key, size_t seed) noexcept
 {
diff --git a/src/gui/painting/qtransform.cpp b/src/gui/painting/qtransform.cpp
index f8b0336bc22..c0e2bf6e2fe 100644
--- a/src/gui/painting/qtransform.cpp
+++ b/src/gui/painting/qtransform.cpp
@@ -780,10 +780,7 @@ bool QTransform::operator==(const QTransform &o) const
 
 /*!
     \since 5.6
-    \relates QTransform
-
-    Returns the hash value for \a key, using
-    \a seed to seed the calculation.
+    \qhashold{QTransform}
 */
 size_t qHash(const QTransform &key, size_t seed) noexcept
 {
diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index 78ff8ed2725..c32f0629033 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -1267,9 +1267,8 @@ QRhiDepthStencilClearValue::QRhiDepthStencilClearValue(float d, quint32 s)
 */
 
 /*!
-    \fn size_t QRhiDepthStencilClearValue::qHash(const QRhiDepthStencilClearValue &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiDepthStencilClearValue::qHash(const QRhiDepthStencilClearValue &key, size_t seed)
+    \qhash{QRhiDepthStencilClearValue}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -1388,9 +1387,8 @@ QRhiViewport::QRhiViewport(float x, float y, float w, float h, float minDepth, f
 */
 
 /*!
-    \fn size_t QRhiViewport::qHash(const QRhiViewport &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiViewport::qHash(const QRhiViewport &key, size_t seed)
+    \qhash{QRhiViewport}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -1482,9 +1480,8 @@ QRhiScissor::QRhiScissor(int x, int y, int w, int h)
 */
 
 /*!
-    \fn size_t QRhiScissor::qHash(const QRhiScissor &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiScissor::qHash(const QRhiScissor &key, size_t seed)
+    \qhash{QRhiScissor}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -1635,9 +1632,8 @@ QRhiVertexInputBinding::QRhiVertexInputBinding(quint32 stride, Classification cl
 */
 
 /*!
-    \fn size_t QRhiVertexInputBinding::qHash(const QRhiVertexInputBinding &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiVertexInputBinding::qHash(const QRhiVertexInputBinding &key, size_t seed)
+    \qhash{QRhiVertexInputBinding}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -1874,9 +1870,8 @@ QRhiVertexInputAttribute::QRhiVertexInputAttribute(int binding, int location, Fo
 */
 
 /*!
-    \fn size_t QRhiVertexInputAttribute::qHash(const QRhiVertexInputAttribute &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiVertexInputAttribute::qHash(const QRhiVertexInputAttribute &key, size_t seed)
+    \qhash{QRhiVertexInputAttribute}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -2118,9 +2113,8 @@ quint32 QRhiImplementation::byteSizePerVertexForVertexInputFormat(QRhiVertexInpu
 */
 
 /*!
-    \fn size_t QRhiVertexInputLayout::qHash(const QRhiVertexInputLayout &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiVertexInputLayout::qHash(const QRhiVertexInputLayout &key, size_t seed)
+    \qhash{QRhiVertexInputLayout}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -2264,9 +2258,8 @@ QRhiShaderStage::QRhiShaderStage(Type type, const QShader &shader, QShader::Vari
 */
 
 /*!
-    \fn size_t QRhiShaderStage::qHash(const QRhiShaderStage &v, size_t seed = 0) noexcept
-
-    \return the hash value for \a v, using \a seed to seed the calculation.
+    \fn size_t QRhiShaderStage::qHash(const QRhiShaderStage &key, size_t seed)
+    \qhash{QRhiShaderStage}
  */
 
 #ifndef QT_NO_DEBUG_STREAM
@@ -6498,9 +6491,8 @@ bool operator!=(const QRhiShaderResourceBinding &a, const QRhiShaderResourceBind
 }
 
 /*!
-    \return the hash value for \a b, using \a seed to seed the calculation.
-
-    \relates QRhiShaderResourceBinding
+    \fn size_t qHash(const QRhiShaderResourceBinding &key, size_t seed)
+    \qhashold{QRhiShaderResourceBinding}
  */
 size_t qHash(const QRhiShaderResourceBinding &b, size_t seed) noexcept
 {
diff --git a/src/gui/rhi/qshader.cpp b/src/gui/rhi/qshader.cpp
index 3a5fa3da0fb..7f5c9f1a08c 100644
--- a/src/gui/rhi/qshader.cpp
+++ b/src/gui/rhi/qshader.cpp
@@ -794,9 +794,8 @@ bool operator==(const QShader &lhs, const QShader &rhs) noexcept
  */
 
 /*!
-    Returns the hash value for \a s, using \a seed to seed the calculation.
-
-    \relates QShader
+    \fn size_t qHash(const QShader &key, size_t seed)
+    \qhashold{QShader}
  */
 size_t qHash(const QShader &s, size_t seed) noexcept
 {
@@ -901,9 +900,8 @@ bool operator<(const QShaderKey &lhs, const QShaderKey &rhs) noexcept
  */
 
 /*!
-    Returns the hash value for \a k, using \a seed to seed the calculation.
-
-    \relates QShaderKey
+    \fn size_t qHash(const QShaderKey &key, size_t seed)
+    \qhashold{QShaderKey}
  */
 size_t qHash(const QShaderKey &k, size_t seed) noexcept
 {
@@ -934,9 +932,8 @@ bool operator==(const QShaderCode &lhs, const QShaderCode &rhs) noexcept
  */
 
 /*!
-    Returns the hash value for \a k, using \a seed to seed the calculation.
-
-    \relates QShaderCode
+    \fn size_t qHash(const QShaderCode &key, size_t seed)
+    \qhashold{QShaderCode}
  */
 size_t qHash(const QShaderCode &k, size_t seed) noexcept
 {
diff --git a/src/gui/text/qfont.cpp b/src/gui/text/qfont.cpp
index b45e93f37b2..3ae427a98bb 100644
--- a/src/gui/text/qfont.cpp
+++ b/src/gui/text/qfont.cpp
@@ -2183,10 +2183,8 @@ QString QFont::toString() const
 }
 
 /*!
-    Returns the hash value for \a font. If specified, \a seed is used
-    to initialize the hash.
-
-    \relates QFont
+    \fn size_t qHash(const QFont &key, size_t seed)
+    \qhashold{QFont}
     \since 5.3
 */
 size_t qHash(const QFont &font, size_t seed) noexcept
@@ -2342,8 +2340,7 @@ void QFont::cacheStatistics()
 
 /*!
     \fn size_t QFont::Tag::qHash(QFont::Tag key, size_t seed) noexcept
-
-    Returns the hash value for \a key, using \a seed to seed the calculation.
+    \qhash{QFont::Tag}
 */
 
 /*!
diff --git a/src/gui/text/qrawfont.cpp b/src/gui/text/qrawfont.cpp
index 14481e10554..c2650999932 100644
--- a/src/gui/text/qrawfont.cpp
+++ b/src/gui/text/qrawfont.cpp
@@ -279,10 +279,8 @@ bool QRawFont::operator==(const QRawFont &other) const
 }
 
 /*!
-    Returns the hash value for \a font. If specified, \a seed is used
-    to initialize the hash.
-
-    \relates QRawFont
+    \fn size_t qHash(const QRawFont &key, size_t seed)
+    \qhashold{QRawFont}
     \since 5.8
 */
 size_t qHash(const QRawFont &font, size_t seed) noexcept
diff --git a/src/gui/vulkan/qvulkaninstance.cpp b/src/gui/vulkan/qvulkaninstance.cpp
index 6d3020d62df..99864e54695 100644
--- a/src/gui/vulkan/qvulkaninstance.cpp
+++ b/src/gui/vulkan/qvulkaninstance.cpp
@@ -301,10 +301,7 @@ QVulkanInstance::~QVulkanInstance()
 /*!
     \fn size_t qHash(const QVulkanLayer &key, size_t seed = 0)
     \since 5.10
-    \relates QVulkanLayer
-
-    Returns the hash value for the \a key, using \a seed to seed the
-    calculation.
+    \qhashold{QVulkanLayer}
 */
 
 /*!
@@ -345,10 +342,7 @@ QVulkanInstance::~QVulkanInstance()
 /*!
     \fn size_t qHash(const QVulkanExtension &key, size_t seed = 0)
     \since 5.10
-    \relates QVulkanExtension
-
-    Returns the hash value for the \a key, using \a seed to seed the
-    calculation.
+    \qhashold{QVulkanExtension}
 */
 
 /*!
diff --git a/src/network/access/qhttp1configuration.cpp b/src/network/access/qhttp1configuration.cpp
index 1cf48e698ca..ace4abf8e87 100644
--- a/src/network/access/qhttp1configuration.cpp
+++ b/src/network/access/qhttp1configuration.cpp
@@ -129,8 +129,7 @@ qsizetype QHttp1Configuration::numberOfConnectionsPerHost() const
 /*!
     \fn size_t QHttp1Configuration::qHash(const QHttp1Configuration &key, size_t seed)
     \since 6.5
-
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
+    \qhash{QHttp1Configuration}
 */
 
 /*!
diff --git a/src/network/kernel/qhostaddress.cpp b/src/network/kernel/qhostaddress.cpp
index f1a65549321..3b79b618de1 100644
--- a/src/network/kernel/qhostaddress.cpp
+++ b/src/network/kernel/qhostaddress.cpp
@@ -1257,8 +1257,7 @@ QDebug operator<<(QDebug d, const QHostAddress &address)
 
 /*!
     \since 5.0
-    \relates QHostAddress
-    Returns a hash of the host address \a key, using \a seed to seed the calculation.
+    \qhashold{QHostAddress}
 */
 size_t qHash(const QHostAddress &key, size_t seed) noexcept
 {
diff --git a/src/network/ssl/qocspresponse.cpp b/src/network/ssl/qocspresponse.cpp
index ac450426e97..19bc34898dd 100644
--- a/src/network/ssl/qocspresponse.cpp
+++ b/src/network/ssl/qocspresponse.cpp
@@ -200,10 +200,9 @@ bool QOcspResponse::isEqual(const QOcspResponse &other) const
 }
 
 /*!
-    Returns the hash value for the \a response, using \a seed to seed the calculation.
-
+    \fn size_t qHash(const QOcspResponse &key, size_t seed)
     \since 5.13
-    \relates QHash
+    \qhashold{QHash}
 */
 size_t qHash(const QOcspResponse &response, size_t seed) noexcept
 {
diff --git a/src/network/ssl/qsslcertificate.cpp b/src/network/ssl/qsslcertificate.cpp
index 285cd3bbbe5..e163ffa443d 100644
--- a/src/network/ssl/qsslcertificate.cpp
+++ b/src/network/ssl/qsslcertificate.cpp
@@ -971,9 +971,8 @@ QString QSslCertificate::subjectDisplayName() const
 }
 
 /*!
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
     \since 5.4
-    \relates QHash
+    \qhashold{QHash}
 */
 size_t qHash(const QSslCertificate &key, size_t seed) noexcept
 {
diff --git a/src/network/ssl/qssldiffiehellmanparameters.cpp b/src/network/ssl/qssldiffiehellmanparameters.cpp
index b0a56936e28..5e5cb3f8955 100644
--- a/src/network/ssl/qssldiffiehellmanparameters.cpp
+++ b/src/network/ssl/qssldiffiehellmanparameters.cpp
@@ -305,11 +305,9 @@ QDebug operator<<(QDebug debug, const QSslDiffieHellmanParameters &dhparam)
 #endif
 
 /*!
+    \fn size_t qHash(const QSslDiffieHellmanParameters &key, size_t seed)
     \since 5.8
-    \relates QSslDiffieHellmanParameters
-
-    Returns an hash value for \a dhparam, using \a seed to seed
-    the calculation.
+    \qhashold{QSslDiffieHellmanParameters}
 */
 size_t qHash(const QSslDiffieHellmanParameters &dhparam, size_t seed) noexcept
 {
diff --git a/src/network/ssl/qsslellipticcurve.cpp b/src/network/ssl/qsslellipticcurve.cpp
index 77aa66f3ccd..ffe1839e57e 100644
--- a/src/network/ssl/qsslellipticcurve.cpp
+++ b/src/network/ssl/qsslellipticcurve.cpp
@@ -160,12 +160,9 @@ bool QSslEllipticCurve::isTlsNamedCurve() const noexcept
 */
 
 /*!
-    \fn size_t qHash(QSslEllipticCurve curve, size_t seed = 0)
+    \fn size_t qHash(QSslEllipticCurve key, size_t seed)
     \since 5.5
-    \relates QHash
-
-    Returns an hash value for the curve \a curve, using \a seed to seed
-    the calculation.
+    \qhashold{QHash}
 */
 
 #ifndef QT_NO_DEBUG_STREAM
diff --git a/src/network/ssl/qsslerror.cpp b/src/network/ssl/qsslerror.cpp
index 1df893604a7..6f17873fd5f 100644
--- a/src/network/ssl/qsslerror.cpp
+++ b/src/network/ssl/qsslerror.cpp
@@ -327,9 +327,8 @@ QSslCertificate QSslError::certificate() const
 }
 
 /*!
-    Returns the hash value for the \a key, using \a seed to seed the calculation.
     \since 5.4
-    \relates QHash
+    \qhashold{QHash}
 */
 size_t qHash(const QSslError &key, size_t seed) noexcept
 {
diff --git a/src/widgets/kernel/qsizepolicy.cpp b/src/widgets/kernel/qsizepolicy.cpp
index b883c1ed6f0..e93e3bc89ad 100644
--- a/src/widgets/kernel/qsizepolicy.cpp
+++ b/src/widgets/kernel/qsizepolicy.cpp
@@ -283,9 +283,7 @@ void QSizePolicy::setControlType(ControlType type) noexcept
 /*!
     \fn size_t QSizePolicy::qHash(QSizePolicy key, size_t seed = 0)
     \since 5.6
-
-    Returns the hash value for \a key, using
-    \a seed to seed the calculation.
+    \qhash{QSizePolicy}
 */
 
 /*!