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.7 6.5 6.2
Change-Id: If007602d7690572fcbb848a8d0235416c908cfd2
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>
(cherry picked from commit 82058367923ce164024885854c139ee5e0d89949)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/corelib/ipc/qtipccommon.cpp

@@ -424,9 +424,7 @@ void QNativeIpcKey::destroy_internal() noexcept
 
 /*!
     \fn QNativeIpcKey::swap(QNativeIpcKey &other) noexcept
-
+    \memberswap{native IPC key and type}
-    Swaps the native IPC key and type \a other with this object.
-    This operation is very fast and never fails.
 */
 
 /*!

src/corelib/kernel/qpointer.qdoc

@@ -143,9 +143,7 @@
 /*!
     \fn template <class T> void QPointer<T>::swap(QPointer &other)
     \since 5.6
-
+    \memberswap{pointer}
-    Swaps the contents of this QPointer with the contents of \a other.
-    This operation is very fast and never fails.
 */
 
 /*!

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.
+    \memberswap{mime type}
-
-    This operation is very fast and never fails.
 
     The swap() method helps with the implementation of assignment
     operators in an exception-safe way. For more information consult

src/corelib/serialization/qcborarray.cpp

@@ -127,8 +127,7 @@ QCborArray &QCborArray::operator=(const QCborArray &other) noexcept
 
 /*!
     \fn void QCborArray::swap(QCborArray &other)
-
+    \memberswap{array}
-    Swaps the contents of this object and \a other.
  */
 
 /*!

src/corelib/serialization/qcbormap.cpp

@@ -218,8 +218,7 @@ QCborMap &QCborMap::operator=(const QCborMap &other) noexcept
 
 /*!
     \fn void QCborMap::swap(QCborMap &other)
-
+    \memberswap{map}
-    Swaps the contents of this map and \a other.
  */
 
 /*!

src/corelib/serialization/qcborvalue.cpp

@@ -464,8 +464,7 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount =
 
 /*!
     \fn void QCborValue::swap(QCborValue &other)
-
+    \memberswap{value}
-    Swaps the contents of this QCborValue object and \a other.
  */
 
 /*!

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
-
+    \memberswap{array}
-    Swaps the array \a other with this. This operation is very fast and never fails.
 */
 
 /*! \fn QJsonArray &QJsonArray::operator+=(const QJsonValue &value)

src/corelib/serialization/qjsondocument.cpp

@@ -179,8 +179,7 @@ QJsonDocument &QJsonDocument::operator =(const QJsonDocument &other)
 /*!
     \fn void QJsonDocument::swap(QJsonDocument &other)
     \since 5.10
-
+    \memberswap{document}
-    Swaps the document \a other with this. This operation is very fast and never fails.
 */
 
 #ifndef QT_NO_VARIANT

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
-
+    \memberswap{object}
-    Swaps the object \a other with this. This operation is very fast and never fails.
 */
 
 #ifndef QT_NO_VARIANT

src/corelib/serialization/qjsonvalue.cpp

@@ -292,8 +292,7 @@ void QJsonValue::swap(QJsonValue &other) noexcept
 /*!
     \fn void QJsonValue::swap(QJsonValue &other)
     \since 5.10
-
+    \memberswap{value}
-    Swaps the value \a other with this. This operation is very fast and never fails.
 */
 
 /*!

src/corelib/text/qregularexpression.cpp

@@ -2632,9 +2632,7 @@ QRegularExpressionMatchIterator &QRegularExpressionMatchIterator::operator=(cons
 
 /*!
     \fn void QRegularExpressionMatchIterator::swap(QRegularExpressionMatchIterator &other)
-
+    \memberswap{iterator}
-    Swaps the iterator \a other with this iterator object. This operation is
-    very fast and never fails.
 */
 
 /*!

src/corelib/thread/qexception.cpp

@@ -148,9 +148,7 @@ QUnhandledException &QUnhandledException::operator=(const QUnhandledException &o
 /*!
     \fn void QUnhandledException::swap(QUnhandledException &other)
     \since 6.0
-
+    \memberswap{unhandled exception object}
-    Swaps this QUnhandledException with \a other. This function is very fast and
-    never fails.
 */
 
 /*!

src/corelib/tools/qshareddata.cpp

@@ -309,8 +309,7 @@ QT_BEGIN_NAMESPACE
  */
 
 /*! \fn template <class T> void QSharedDataPointer<T>::swap(QSharedDataPointer &other)
-  Swap this instance's shared data pointer with the shared
+    \memberswap{shared data pointer}
-  data pointer in \a other.
  */
 
 /*!
@@ -500,8 +499,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*! \fn template <class T> void QExplicitlySharedDataPointer<T>::swap(QExplicitlySharedDataPointer &other)
-  Swap this instance's explicitly shared data pointer with
+    \memberswap{explicitly-shared data pointer}
-  the explicitly shared data pointer in \a other.
  */
 
 /*! \fn template <class T> bool QExplicitlySharedDataPointer<T>::operator==(const QExplicitlySharedDataPointer<T>& lhs, const QExplicitlySharedDataPointer<T>& rhs)

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
-
+    \memberswap{pointer and tag}
-    Swaps this instance's pointer and tag with the pointer and tag in \a other.
 */
 
 /*!

src/dbus/qdbusargument.cpp

@@ -1364,8 +1364,7 @@ QDBusArgument &operator<<(QDBusArgument &a, const QLineF &line)
 
 /*!
     \fn void QDBusArgument::swap(QDBusArgument &other)
-
+    \memberswap{argument}
-    Swaps this QDBusArgument instance with \a other.
 */
 
 QT_END_NAMESPACE

src/dbus/qdbusconnection.cpp

@@ -1008,8 +1008,7 @@ QByteArray QDBusConnection::localMachineId()
 
 /*!
     \fn void QDBusConnection::swap(QDBusConnection &other)
-
+    \memberswap{connection}
-    Swaps this QDBusConnection instance with \a other.
 */
 
 QT_END_NAMESPACE

src/dbus/qdbuserror.cpp

@@ -314,8 +314,7 @@ QDebug operator<<(QDebug dbg, const QDBusError &msg)
 
 /*!
     \fn void QDBusError::swap(QDBusError &other)
-
+    \memberswap{error}
-    Swaps this QDBusError instance with \a other.
 */
 
 QT_END_NAMESPACE

src/dbus/qdbusextratypes.cpp

@@ -216,20 +216,17 @@ QDBusObjectPath::operator QVariant() const { return QVariant::fromValue(*this);
 
 /*!
     \fn void QDBusObjectPath::swap(QDBusObjectPath &other)
-
+    \memberswap{object path}
-    Swaps this QDBusObjectPath instance with \a other.
 */
 
 /*!
     \fn void QDBusSignature::swap(QDBusSignature &other)
-
+    \memberswap{signature}
-    Swaps this QDBusSignature instance with \a other.
 */
 
 /*!
     \fn void QDBusVariant::swap(QDBusVariant &other)
-
+    \memberswap{variant}
-    Swaps this QDBusVariant instance with \a other.
 */
 
 QT_END_NAMESPACE

src/dbus/qdbusmessage.cpp

@@ -848,8 +848,7 @@ QDebug operator<<(QDebug dbg, const QDBusMessage &msg)
 
 /*!
     \fn void QDBusMessage::swap(QDBusMessage &other)
-
+    \memberswap{message}
-    Swaps this QDBusMessage instance with \a other.
 */
 
 QT_END_NAMESPACE

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}
 */
 
 

src/network/ssl/qsslpresharedkeyauthenticator.cpp

@@ -113,10 +113,8 @@ QSslPreSharedKeyAuthenticator &QSslPreSharedKeyAuthenticator::operator=(const QS
 */
 
 /*!
-    \fn void QSslPreSharedKeyAuthenticator::swap(QSslPreSharedKeyAuthenticator &authenticator)
+    \fn void QSslPreSharedKeyAuthenticator::swap(QSslPreSharedKeyAuthenticator &other)
-
+    \memberswap{authenticator}
-    Swaps the QSslPreSharedKeyAuthenticator object \a authenticator with this object.
-    This operation is very fast and never fails.
 */
 
 /*!

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
+    \memberswap{query}
-    fast and never fails.
 */
 
 /*!

src/sql/models/qsqlrelationaltablemodel.cpp

@@ -67,8 +67,7 @@ using SqlrTm = QSqlRelationalTableModelSql;
 
 /*!
   \fn void QSqlRelation::swap(QSqlRelation &other)
-
+    \memberswap{relation}
-  Swaps \c this with \a other.
  */
 
 /*!