From cc138604d6b72d104b3a53634422a5e3e5ebcb85 Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Wed, 9 Oct 2024 12:43:20 +0200 Subject: [PATCH] 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.5 Change-Id: I8e8c2edc27422cbe5823f56baf3a24d7f7050836 Reviewed-by: Ivan Solovev Reviewed-by: Jaishree Vyas (cherry picked from commit 906aa1533f2267b091615d21c2d31e1742f0a520) --- doc/global/cpp-doc-macros.qdocconf | 55 +++++++ src/corelib/global/qflags.qdoc | 7 +- src/corelib/global/qfloat16.cpp | 4 +- src/corelib/global/qnamespace.qdoc | 4 +- src/corelib/io/qurl.cpp | 6 +- src/corelib/io/qurlquery.cpp | 5 +- src/corelib/ipc/qtipccommon.cpp | 5 +- src/corelib/itemmodels/qabstractitemmodel.cpp | 7 +- src/corelib/kernel/qmetatype.cpp | 7 +- src/corelib/mimetypes/qmimetype.cpp | 5 +- src/corelib/plugin/quuid.cpp | 4 +- src/corelib/text/qbytearray.cpp | 5 +- src/corelib/text/qlocale.cpp | 5 +- src/corelib/text/qstringview.cpp | 6 + src/corelib/time/qdatetime.cpp | 12 +- src/corelib/tools/qhash.cpp | 139 +++++------------- src/corelib/tools/qlist.qdoc | 7 +- src/corelib/tools/qmap.qdoc | 5 +- src/corelib/tools/qpoint.cpp | 6 +- src/corelib/tools/qset.qdoc | 4 +- src/corelib/tools/qsharedpointer.cpp | 5 +- src/corelib/tools/qtaggedpointer.qdoc | 4 +- src/corelib/tools/qtyperevision.cpp | 5 +- src/corelib/tools/qvarlengtharray.qdoc | 5 +- src/corelib/tools/qversionnumber.cpp | 5 +- src/gui/image/qpixmapcache.cpp | 3 +- src/gui/kernel/qkeysequence.cpp | 5 +- src/gui/kernel/qpointingdevice.cpp | 4 +- src/gui/painting/qtransform.cpp | 5 +- src/gui/rhi/qrhi.cpp | 40 ++--- src/gui/rhi/qshader.cpp | 15 +- src/gui/text/qfont.cpp | 9 +- src/gui/text/qrawfont.cpp | 6 +- src/gui/vulkan/qvulkaninstance.cpp | 10 +- src/network/access/qhttp1configuration.cpp | 3 +- src/network/kernel/qhostaddress.cpp | 3 +- src/network/ssl/qocspresponse.cpp | 5 +- src/network/ssl/qsslcertificate.cpp | 3 +- .../ssl/qssldiffiehellmanparameters.cpp | 6 +- src/network/ssl/qsslellipticcurve.cpp | 7 +- src/network/ssl/qsslerror.cpp | 3 +- src/widgets/kernel/qsizepolicy.cpp | 4 +- 42 files changed, 169 insertions(+), 284 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 - 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 dd3b1e4c9b0..c3baad4cb90 100644 --- a/src/corelib/global/qflags.qdoc +++ b/src/corelib/global/qflags.qdoc @@ -398,12 +398,9 @@ */ /*! - \fn template size_t qHash(QFlags flags, size_t seed = 0) noexcept + \fn template size_t qHash(QFlags 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 231087350e7..5fca8cf3950 100644 --- a/src/corelib/global/qnamespace.qdoc +++ b/src/corelib/global/qnamespace.qdoc @@ -3567,9 +3567,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 5706327a5c5..a390f1df96d 100644 --- a/src/corelib/io/qurl.cpp +++ b/src/corelib/io/qurl.cpp @@ -3616,10 +3616,8 @@ QList 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 1b44dbf7b8e..7b6e2818c7a 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 52e8157536f..99963cdd38d 100644 --- a/src/corelib/itemmodels/qabstractitemmodel.cpp +++ b/src/corelib/itemmodels/qabstractitemmodel.cpp @@ -4153,12 +4153,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 1c2665e53c0..7dd51f14288 100644 --- a/src/corelib/kernel/qmetatype.cpp +++ b/src/corelib/kernel/qmetatype.cpp @@ -3274,11 +3274,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 5cbae60ac8c..a12ce10accc 100644 --- a/src/corelib/plugin/quuid.cpp +++ b/src/corelib/plugin/quuid.cpp @@ -996,9 +996,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 bb175aeabe0..b43a2479e57 100644 --- a/src/corelib/text/qbytearray.cpp +++ b/src/corelib/text/qbytearray.cpp @@ -5123,10 +5123,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 bfca8a83485..d7fb3a8d6ba 100644 --- a/src/corelib/text/qlocale.cpp +++ b/src/corelib/text/qlocale.cpp @@ -1196,10 +1196,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 0381e2bec5e..908c53079a0 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -162,6 +162,12 @@ QT_BEGIN_NAMESPACE \sa reverse_iterator, const_iterator */ +/*! + \fn size_t qHash(QStringView key, size_t seed) + \since 5.10 + \qhashold{QStringView} +*/ + /*! \fn QStringView::QStringView() diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp index b41edc97456..0bf86c99be0 100644 --- a/src/corelib/time/qdatetime.cpp +++ b/src/corelib/time/qdatetime.cpp @@ -6288,10 +6288,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) { @@ -6303,10 +6301,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 { @@ -6314,10 +6310,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 9654a6712b0..4bbfa6bbefb 100644 --- a/src/corelib/tools/qhash.cpp +++ b/src/corelib/tools/qhash.cpp @@ -1098,11 +1098,7 @@ uint qt_hash(QStringView key, uint chained) noexcept /*! \fn template size_t qHash(const std::pair &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} */ /*! @@ -1244,141 +1240,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 { @@ -1393,10 +1352,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 { @@ -1412,66 +1370,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 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 bool qHashEquals(const T &a, const T &b) @@ -3867,21 +3802,13 @@ size_t qHash(long double key, size_t seed) noexcept /*! \fn template size_t qHash(const QHash &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 size_t qHash(const QMultiHash &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 qsizetype erase_if(QHash &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 size_t qHash(const QList &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 qsizetype QList::size() const diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc index f3af9122327..fdea0736eb4 100644 --- a/src/corelib/tools/qmap.qdoc +++ b/src/corelib/tools/qmap.qdoc @@ -1391,8 +1391,5 @@ /*! \fn template size_t QMap::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 817d675591b..e5d081bf40a 100644 --- a/src/corelib/tools/qset.qdoc +++ b/src/corelib/tools/qset.qdoc @@ -868,11 +868,9 @@ /*! \fn template size_t qHash(const QSet &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 a9b75c649c7..47634c2e74d 100644 --- a/src/corelib/tools/qsharedpointer.cpp +++ b/src/corelib/tools/qsharedpointer.cpp @@ -974,10 +974,7 @@ /*! \fn template qHash(const QSharedPointer &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 qHash(QTaggedPointer 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 size_t qHash(const QVarLengthArray &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 template qsizetype QVarLengthArray::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 ffc089129fb..f18020fa00e 100644 --- a/src/gui/image/qpixmapcache.cpp +++ b/src/gui/image/qpixmapcache.cpp @@ -220,8 +220,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 cf8cd774b74..6c4f104411a 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 d5dd08c5878..6f6cc8a4ea7 100644 --- a/src/gui/painting/qtransform.cpp +++ b/src/gui/painting/qtransform.cpp @@ -784,10 +784,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 5a6bdc9e31c..7275dfe742c 100644 --- a/src/gui/rhi/qrhi.cpp +++ b/src/gui/rhi/qrhi.cpp @@ -1223,9 +1223,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 @@ -1344,9 +1343,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 @@ -1438,9 +1436,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 @@ -1591,9 +1588,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 @@ -1830,9 +1826,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 @@ -2074,9 +2069,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 @@ -2220,9 +2214,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 @@ -6274,9 +6267,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 bbd53249fa1..37f577c9ba7 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 a1b41c0d51e..9c1621a7bd6 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} */ /*!