Create qdoc macros for C++ class docs 1.3: member-swap(), non-standard phrasing

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.8 6.7 6.5 6.2
Change-Id: If007602d7690572fcbb848a8d0235416c908cfd2
Reviewed-by: Topi Reiniö <[email protected]>
Reviewed-by: Ivan Solovev <[email protected]>

23 files changed, 27 insertions, 58 deletions

diff --git a/src/corelib/ipc/qtipccommon.cpp b/src/corelib/ipc/qtipccommon.cpp
index b2ae9172fa5..553f3dd1996 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 63a2a72e6fd..d95de1150cc 100644
--- a/src/corelib/kernel/qpointer.qdoc
+++ b/src/corelib/kernel/qpointer.qdoc
@@ -143,9 +143,7 @@
 /*!
     \fn template <class T> void QPointer<T>::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 e26c8b898da..d44989a050c 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 626fb49a700..e00b7a4571f 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 038e0d61ce4..bf4d7cbe559 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 204d030c7c1..b4cb432e78a 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 6ada4e805b5..d839c5cd950 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 a3afe95b848..fe33ff8e548 100644
--- a/src/corelib/serialization/qjsondocument.cpp
+++ b/src/corelib/serialization/qjsondocument.cpp
@@ -161,8 +161,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 12d175b8e0d..729119d938d 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 09b4682bf71..adc58cc2536 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 8a143de5a65..3f614b41f4d 100644
--- a/src/corelib/text/qregularexpression.cpp
+++ b/src/corelib/text/qregularexpression.cpp
@@ -2637,9 +2637,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 a623dc1c6e5..fd98505282e 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 2f8cf98230c..1be76bd2076 100644
--- a/src/corelib/tools/qshareddata.cpp
+++ b/src/corelib/tools/qshareddata.cpp
@@ -313,8 +313,7 @@ QT_BEGIN_NAMESPACE
  */
 
 /*! \fn template <class T> void QSharedDataPointer<T>::swap(QSharedDataPointer &other)
-  Swap this instance's shared data pointer with the shared
-  data pointer in \a other.
+    \memberswap{shared data pointer}
  */
 
 /*!
@@ -508,8 +507,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*! \fn template <class T> void QExplicitlySharedDataPointer<T>::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 <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)
diff --git a/src/corelib/tools/qtaggedpointer.qdoc b/src/corelib/tools/qtaggedpointer.qdoc
index f910e35b69e..cbd5989a65a 100644
--- a/src/corelib/tools/qtaggedpointer.qdoc
+++ b/src/corelib/tools/qtaggedpointer.qdoc
@@ -142,8 +142,7 @@
 
 /*!
     \fn template <typename T, typename Tag> void QTaggedPointer<T, Tag>::swap(QTaggedPointer<T, Tag> &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 99e60244daf..4b7ad899f99 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 14c9ebe6205..08cec30afa3 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 49c30e5b251..0a5ba30d3a3 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 1f976939668..042014ceab0 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 98689ab0b4c..9f91d4ed4e1 100644
--- a/src/dbus/qdbusmessage.cpp
+++ b/src/dbus/qdbusmessage.cpp
@@ -851,8 +851,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 a97eb25a511..dad8128aa81 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 0045a83beae..3ecd9ca435e 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 fc8c3a2dd67..b9ebfedb639 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 1595ff03651..8f9015630a1 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}
  */
 
 /*!