From b8c9a4c3d12c4f3ec8c00cf8ffb70a454bd0645d Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Wed, 2 Oct 2024 18:46:01 +0200 Subject: [PATCH] Create qdoc macros for C++ class docs 1.3: member-swap(), non-standard phrasing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We have some patterns for how to document certain functions, but we also vary the sentences a lot, and you have to look up one documentation piece and copy it, essentially. If we ever want to change them, we end up with shotgun surgery. So apply DRY to the documentation and start a collection of macros to help with repetitive C++ class documentation tasks. The first macro is for member-swap(), and this third patch is for documentation that used a non-standard phrasing for documenting member-swap(). By using the macro, the documentation automatically conforms to what the documentation team picks as the \memberswap expansion going forward. As a drive-by, fix doc block indentation to the Qt standard of 4 spaces (only in changed lines), and add a few blank lines where they were missing before. Fixes: QTBUG-129573 Pick-to: 6.7 6.5 6.2 Change-Id: If007602d7690572fcbb848a8d0235416c908cfd2 Reviewed-by: Topi Reiniö Reviewed-by: Ivan Solovev (cherry picked from commit 82058367923ce164024885854c139ee5e0d89949) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/ipc/qtipccommon.cpp | 4 +--- src/corelib/kernel/qpointer.qdoc | 4 +--- src/corelib/mimetypes/qmimetype.cpp | 4 +--- src/corelib/serialization/qcborarray.cpp | 3 +-- src/corelib/serialization/qcbormap.cpp | 3 +-- src/corelib/serialization/qcborvalue.cpp | 3 +-- src/corelib/serialization/qjsonarray.cpp | 3 +-- src/corelib/serialization/qjsondocument.cpp | 3 +-- src/corelib/serialization/qjsonobject.cpp | 3 +-- src/corelib/serialization/qjsonvalue.cpp | 3 +-- src/corelib/text/qregularexpression.cpp | 4 +--- src/corelib/thread/qexception.cpp | 4 +--- src/corelib/tools/qshareddata.cpp | 6 ++---- src/corelib/tools/qtaggedpointer.qdoc | 3 +-- src/dbus/qdbusargument.cpp | 3 +-- src/dbus/qdbusconnection.cpp | 3 +-- src/dbus/qdbuserror.cpp | 3 +-- src/dbus/qdbusextratypes.cpp | 9 +++------ src/dbus/qdbusmessage.cpp | 3 +-- src/network/kernel/qnetworkdatagram.cpp | 2 +- src/network/ssl/qsslpresharedkeyauthenticator.cpp | 6 ++---- src/sql/kernel/qsqlquery.cpp | 3 +-- src/sql/models/qsqlrelationaltablemodel.cpp | 3 +-- 23 files changed, 27 insertions(+), 58 deletions(-) diff --git a/src/corelib/ipc/qtipccommon.cpp b/src/corelib/ipc/qtipccommon.cpp index b2ae9172fa..553f3dd199 100644 --- a/src/corelib/ipc/qtipccommon.cpp +++ b/src/corelib/ipc/qtipccommon.cpp @@ -424,9 +424,7 @@ void QNativeIpcKey::destroy_internal() noexcept /*! \fn QNativeIpcKey::swap(QNativeIpcKey &other) noexcept - - Swaps the native IPC key and type \a other with this object. - This operation is very fast and never fails. + \memberswap{native IPC key and type} */ /*! diff --git a/src/corelib/kernel/qpointer.qdoc b/src/corelib/kernel/qpointer.qdoc index 63a2a72e6f..d95de1150c 100644 --- a/src/corelib/kernel/qpointer.qdoc +++ b/src/corelib/kernel/qpointer.qdoc @@ -143,9 +143,7 @@ /*! \fn template void QPointer::swap(QPointer &other) \since 5.6 - - Swaps the contents of this QPointer with the contents of \a other. - This operation is very fast and never fails. + \memberswap{pointer} */ /*! diff --git a/src/corelib/mimetypes/qmimetype.cpp b/src/corelib/mimetypes/qmimetype.cpp index e26c8b898d..d44989a050 100644 --- a/src/corelib/mimetypes/qmimetype.cpp +++ b/src/corelib/mimetypes/qmimetype.cpp @@ -93,9 +93,7 @@ QMimeType::QMimeType(const QMimeTypePrivate &dd) : /*! \fn void QMimeType::swap(QMimeType &other); - Swaps QMimeType \a other with this QMimeType object. - - This operation is very fast and never fails. + \memberswap{mime type} The swap() method helps with the implementation of assignment operators in an exception-safe way. For more information consult diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp index 626fb49a70..e00b7a4571 100644 --- a/src/corelib/serialization/qcborarray.cpp +++ b/src/corelib/serialization/qcborarray.cpp @@ -127,8 +127,7 @@ QCborArray &QCborArray::operator=(const QCborArray &other) noexcept /*! \fn void QCborArray::swap(QCborArray &other) - - Swaps the contents of this object and \a other. + \memberswap{array} */ /*! diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp index 038e0d61ce..bf4d7cbe55 100644 --- a/src/corelib/serialization/qcbormap.cpp +++ b/src/corelib/serialization/qcbormap.cpp @@ -218,8 +218,7 @@ QCborMap &QCborMap::operator=(const QCborMap &other) noexcept /*! \fn void QCborMap::swap(QCborMap &other) - - Swaps the contents of this map and \a other. + \memberswap{map} */ /*! diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp index 830cf00ea3..ab3b509886 100644 --- a/src/corelib/serialization/qcborvalue.cpp +++ b/src/corelib/serialization/qcborvalue.cpp @@ -464,8 +464,7 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount = /*! \fn void QCborValue::swap(QCborValue &other) - - Swaps the contents of this QCborValue object and \a other. + \memberswap{value} */ /*! diff --git a/src/corelib/serialization/qjsonarray.cpp b/src/corelib/serialization/qjsonarray.cpp index 6ada4e805b..d839c5cd95 100644 --- a/src/corelib/serialization/qjsonarray.cpp +++ b/src/corelib/serialization/qjsonarray.cpp @@ -171,8 +171,7 @@ QJsonArray &QJsonArray::operator =(const QJsonArray &other) noexcept = default; /*! \fn void QJsonArray::swap(QJsonArray &other) \since 5.10 - - Swaps the array \a other with this. This operation is very fast and never fails. + \memberswap{array} */ /*! \fn QJsonArray &QJsonArray::operator+=(const QJsonValue &value) diff --git a/src/corelib/serialization/qjsondocument.cpp b/src/corelib/serialization/qjsondocument.cpp index e2528f18dc..0a8ef55e8a 100644 --- a/src/corelib/serialization/qjsondocument.cpp +++ b/src/corelib/serialization/qjsondocument.cpp @@ -179,8 +179,7 @@ QJsonDocument &QJsonDocument::operator =(const QJsonDocument &other) /*! \fn void QJsonDocument::swap(QJsonDocument &other) \since 5.10 - - Swaps the document \a other with this. This operation is very fast and never fails. + \memberswap{document} */ #ifndef QT_NO_VARIANT diff --git a/src/corelib/serialization/qjsonobject.cpp b/src/corelib/serialization/qjsonobject.cpp index 12d175b8e0..729119d938 100644 --- a/src/corelib/serialization/qjsonobject.cpp +++ b/src/corelib/serialization/qjsonobject.cpp @@ -156,8 +156,7 @@ QJsonObject &QJsonObject::operator =(const QJsonObject &other) noexcept = defaul /*! \fn void QJsonObject::swap(QJsonObject &other) \since 5.10 - - Swaps the object \a other with this. This operation is very fast and never fails. + \memberswap{object} */ #ifndef QT_NO_VARIANT diff --git a/src/corelib/serialization/qjsonvalue.cpp b/src/corelib/serialization/qjsonvalue.cpp index 09b4682bf7..adc58cc253 100644 --- a/src/corelib/serialization/qjsonvalue.cpp +++ b/src/corelib/serialization/qjsonvalue.cpp @@ -292,8 +292,7 @@ void QJsonValue::swap(QJsonValue &other) noexcept /*! \fn void QJsonValue::swap(QJsonValue &other) \since 5.10 - - Swaps the value \a other with this. This operation is very fast and never fails. + \memberswap{value} */ /*! diff --git a/src/corelib/text/qregularexpression.cpp b/src/corelib/text/qregularexpression.cpp index da928c0571..a4c7198d00 100644 --- a/src/corelib/text/qregularexpression.cpp +++ b/src/corelib/text/qregularexpression.cpp @@ -2632,9 +2632,7 @@ QRegularExpressionMatchIterator &QRegularExpressionMatchIterator::operator=(cons /*! \fn void QRegularExpressionMatchIterator::swap(QRegularExpressionMatchIterator &other) - - Swaps the iterator \a other with this iterator object. This operation is - very fast and never fails. + \memberswap{iterator} */ /*! diff --git a/src/corelib/thread/qexception.cpp b/src/corelib/thread/qexception.cpp index a623dc1c6e..fd98505282 100644 --- a/src/corelib/thread/qexception.cpp +++ b/src/corelib/thread/qexception.cpp @@ -148,9 +148,7 @@ QUnhandledException &QUnhandledException::operator=(const QUnhandledException &o /*! \fn void QUnhandledException::swap(QUnhandledException &other) \since 6.0 - - Swaps this QUnhandledException with \a other. This function is very fast and - never fails. + \memberswap{unhandled exception object} */ /*! diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp index 3d3e0c782a..f46824970c 100644 --- a/src/corelib/tools/qshareddata.cpp +++ b/src/corelib/tools/qshareddata.cpp @@ -309,8 +309,7 @@ QT_BEGIN_NAMESPACE */ /*! \fn template void QSharedDataPointer::swap(QSharedDataPointer &other) - Swap this instance's shared data pointer with the shared - data pointer in \a other. + \memberswap{shared data pointer} */ /*! @@ -500,8 +499,7 @@ QT_BEGIN_NAMESPACE */ /*! \fn template void QExplicitlySharedDataPointer::swap(QExplicitlySharedDataPointer &other) - Swap this instance's explicitly shared data pointer with - the explicitly shared data pointer in \a other. + \memberswap{explicitly-shared data pointer} */ /*! \fn template bool QExplicitlySharedDataPointer::operator==(const QExplicitlySharedDataPointer& lhs, const QExplicitlySharedDataPointer& rhs) diff --git a/src/corelib/tools/qtaggedpointer.qdoc b/src/corelib/tools/qtaggedpointer.qdoc index f910e35b69..cbd5989a65 100644 --- a/src/corelib/tools/qtaggedpointer.qdoc +++ b/src/corelib/tools/qtaggedpointer.qdoc @@ -142,8 +142,7 @@ /*! \fn template void QTaggedPointer::swap(QTaggedPointer &other) noexcept - - Swaps this instance's pointer and tag with the pointer and tag in \a other. + \memberswap{pointer and tag} */ /*! diff --git a/src/dbus/qdbusargument.cpp b/src/dbus/qdbusargument.cpp index 99e60244da..4b7ad899f9 100644 --- a/src/dbus/qdbusargument.cpp +++ b/src/dbus/qdbusargument.cpp @@ -1364,8 +1364,7 @@ QDBusArgument &operator<<(QDBusArgument &a, const QLineF &line) /*! \fn void QDBusArgument::swap(QDBusArgument &other) - - Swaps this QDBusArgument instance with \a other. + \memberswap{argument} */ QT_END_NAMESPACE diff --git a/src/dbus/qdbusconnection.cpp b/src/dbus/qdbusconnection.cpp index 14c9ebe620..08cec30afa 100644 --- a/src/dbus/qdbusconnection.cpp +++ b/src/dbus/qdbusconnection.cpp @@ -1008,8 +1008,7 @@ QByteArray QDBusConnection::localMachineId() /*! \fn void QDBusConnection::swap(QDBusConnection &other) - - Swaps this QDBusConnection instance with \a other. + \memberswap{connection} */ QT_END_NAMESPACE diff --git a/src/dbus/qdbuserror.cpp b/src/dbus/qdbuserror.cpp index 49c30e5b25..0a5ba30d3a 100644 --- a/src/dbus/qdbuserror.cpp +++ b/src/dbus/qdbuserror.cpp @@ -314,8 +314,7 @@ QDebug operator<<(QDebug dbg, const QDBusError &msg) /*! \fn void QDBusError::swap(QDBusError &other) - - Swaps this QDBusError instance with \a other. + \memberswap{error} */ QT_END_NAMESPACE diff --git a/src/dbus/qdbusextratypes.cpp b/src/dbus/qdbusextratypes.cpp index 1f97693966..042014ceab 100644 --- a/src/dbus/qdbusextratypes.cpp +++ b/src/dbus/qdbusextratypes.cpp @@ -216,20 +216,17 @@ QDBusObjectPath::operator QVariant() const { return QVariant::fromValue(*this); /*! \fn void QDBusObjectPath::swap(QDBusObjectPath &other) - - Swaps this QDBusObjectPath instance with \a other. + \memberswap{object path} */ /*! \fn void QDBusSignature::swap(QDBusSignature &other) - - Swaps this QDBusSignature instance with \a other. + \memberswap{signature} */ /*! \fn void QDBusVariant::swap(QDBusVariant &other) - - Swaps this QDBusVariant instance with \a other. + \memberswap{variant} */ QT_END_NAMESPACE diff --git a/src/dbus/qdbusmessage.cpp b/src/dbus/qdbusmessage.cpp index b89ab6a398..8d70c9dfcc 100644 --- a/src/dbus/qdbusmessage.cpp +++ b/src/dbus/qdbusmessage.cpp @@ -848,8 +848,7 @@ QDebug operator<<(QDebug dbg, const QDBusMessage &msg) /*! \fn void QDBusMessage::swap(QDBusMessage &other) - - Swaps this QDBusMessage instance with \a other. + \memberswap{message} */ QT_END_NAMESPACE diff --git a/src/network/kernel/qnetworkdatagram.cpp b/src/network/kernel/qnetworkdatagram.cpp index a97eb25a51..dad8128aa8 100644 --- a/src/network/kernel/qnetworkdatagram.cpp +++ b/src/network/kernel/qnetworkdatagram.cpp @@ -486,7 +486,7 @@ void QNetworkDatagram::destroy(QNetworkDatagramPrivate *d) } /*! \fn void QNetworkDatagram::swap(QNetworkDatagram &other) - Swaps this instance with \a other. + \memberswap{datagram} */ diff --git a/src/network/ssl/qsslpresharedkeyauthenticator.cpp b/src/network/ssl/qsslpresharedkeyauthenticator.cpp index 0045a83bea..3ecd9ca435 100644 --- a/src/network/ssl/qsslpresharedkeyauthenticator.cpp +++ b/src/network/ssl/qsslpresharedkeyauthenticator.cpp @@ -113,10 +113,8 @@ QSslPreSharedKeyAuthenticator &QSslPreSharedKeyAuthenticator::operator=(const QS */ /*! - \fn void QSslPreSharedKeyAuthenticator::swap(QSslPreSharedKeyAuthenticator &authenticator) - - Swaps the QSslPreSharedKeyAuthenticator object \a authenticator with this object. - This operation is very fast and never fails. + \fn void QSslPreSharedKeyAuthenticator::swap(QSslPreSharedKeyAuthenticator &other) + \memberswap{authenticator} */ /*! diff --git a/src/sql/kernel/qsqlquery.cpp b/src/sql/kernel/qsqlquery.cpp index b1ec8bde93..34f419e92f 100644 --- a/src/sql/kernel/qsqlquery.cpp +++ b/src/sql/kernel/qsqlquery.cpp @@ -263,8 +263,7 @@ QSqlQuery& QSqlQuery::operator=(const QSqlQuery& other) /*! \fn void QSqlQuery::swap(QSqlQuery &other) noexcept \since 6.2 - Swaps \a other to this object. This operation is very - fast and never fails. + \memberswap{query} */ /*! diff --git a/src/sql/models/qsqlrelationaltablemodel.cpp b/src/sql/models/qsqlrelationaltablemodel.cpp index 57cb6921d0..a4f9732765 100644 --- a/src/sql/models/qsqlrelationaltablemodel.cpp +++ b/src/sql/models/qsqlrelationaltablemodel.cpp @@ -67,8 +67,7 @@ using SqlrTm = QSqlRelationalTableModelSql; /*! \fn void QSqlRelation::swap(QSqlRelation &other) - - Swaps \c this with \a other. + \memberswap{relation} */ /*!