Create qdoc macros for C++ class docs 1.2: member-swap(), simplified 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 second patch is for
documentation that used the simplified phrasing ("Swaps this X with \a
other."), which this patch adopts as the text for \memberswap, too,
because it doesn't repeat the macro argument, making it easier to find a
grammatically-fitting argument than in the traditional phrasing.

This doesn't change the documentation, except as follows:

* standardizes on simpified instead of traditional phrasing for docs
  that already use the \memberswap macro
* adds the "very fast and never fails" blurb, if it was missing
* changes the function's argument name to `other`, as required by
  the macro.

Task-number: QTBUG-129573
Pick-to: 6.8 6.7 6.5 6.2
Change-Id: I1123e783ce0da76c5997ff74007d77504ac5b334
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Ivan Solovev <ivan.solovev@qt.io>

doc/global/cpp-doc-macros.qdocconf

@@ -11,5 +11,5 @@
 #    The function's argument name must be \a other.
 macro.memberswap = \
     "\n\n" \
-    "Swaps \1 \\a{other} with this \1. This operation is very fast and never fails." \
+    "Swaps this \1 with \\a{other}. This operation is very fast and never fails." \
     "\n\n"

src/corelib/io/qdebug.cpp

@@ -556,9 +556,7 @@ void QDebug::putQtOrdering(QtOrderingPrivate::QtOrderingTypeFlag flags, Qt::part
 /*!
     \fn QDebug::swap(QDebug &other)
     \since 5.0
-
-    Swaps this debug stream instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{debug stream instance}
 */
 
 /*!

src/corelib/io/qdir.cpp

@@ -1871,9 +1871,7 @@ QDir &QDir::operator=(const QDir &dir)
 /*!
     \fn void QDir::swap(QDir &other)
     \since 5.0
-
-    Swaps this QDir instance with \a other. This function is very fast
-    and never fails.
+    \memberswap{QDir instance}
 */
 
 /*!

src/corelib/io/qfileinfo.cpp

@@ -490,9 +490,7 @@ QFileInfo &QFileInfo::operator=(const QFileInfo &fileinfo)
 /*!
     \fn void QFileInfo::swap(QFileInfo &other)
     \since 5.0
-
-    Swaps this file info with \a other. This function is very fast and
-    never fails.
+    \memberswap{file info}
 */
 
 /*!

src/corelib/io/qprocess.cpp

@@ -179,9 +179,7 @@ QProcessEnvironment &QProcessEnvironment::operator=(const QProcessEnvironment &o
 /*!
     \fn void QProcessEnvironment::swap(QProcessEnvironment &other)
     \since 5.0
-
-    Swaps this process environment instance with \a other. This
-    function is very fast and never fails.
+    \memberswap{process environment instance}
 */
 
 /*!

src/corelib/io/qstorageinfo.cpp

@@ -122,9 +122,7 @@ QStorageInfo &QStorageInfo::operator=(const QStorageInfo &other)
 
 /*!
     \fn void QStorageInfo::swap(QStorageInfo &other)
-
-    Swaps this volume info with \a other. This function is very fast and
-    never fails.
+    \memberswap{volume info}
 */
 
 /*!

src/corelib/io/qurlquery.cpp

@@ -387,9 +387,7 @@ QUrlQuery &QUrlQuery::operator =(const QUrlQuery &other)
 
 /*!
     \fn void QUrlQuery::swap(QUrlQuery &other)
-
-    Swaps this URL query instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{URL query instance}
 */
 
 /*!

src/corelib/itemmodels/qabstractitemmodel.cpp

@@ -445,9 +445,7 @@ QPersistentModelIndex &QPersistentModelIndex::operator=(const QPersistentModelIn
 /*!
     \fn void QPersistentModelIndex::swap(QPersistentModelIndex &other)
     \since 5.0
-
-    Swaps this persistent modelindex with \a other. This function is
-    very fast and never fails.
+    \memberswap{persistent modelindex}
 */
 
 /*!

src/corelib/itemmodels/qitemselectionmodel.cpp

@@ -119,9 +119,7 @@ private:
 /*!
     \fn QItemSelectionRange::swap(QItemSelectionRange &other)
     \since 5.6
-
-    Swaps this selection range's contents with \a other.
-    This function is very fast and never fails.
+    \memberswap{selection range's contents}
 */
 
 /*!

src/corelib/kernel/qjniarray.qdoc

@@ -60,8 +60,7 @@
 
 /*!
     \fn void QJniArrayBase::swap(QJniArrayBase &other)
-
-    Swaps this array object with \a other. This function is very fast and never fails.
+    \memberswap{array object}
 */
 
 /*!

src/corelib/kernel/qjniobject.cpp

@@ -739,8 +739,7 @@ QJniObject::~QJniObject()
 /*!
     \fn void QJniObject::swap(QJniObject &other)
     \since 6.8
-
-    Swaps this object with \a other. This function is very fast and never fails.
+    \memberswap{object}
 */
 
 

src/corelib/kernel/qmetaobject.cpp

@@ -1799,9 +1799,7 @@ bool QMetaObject::invokeMethodImpl(QObject *object, QtPrivate::QSlotObjectBase *
 /*!
     \fn QMetaObject::Connection::swap(Connection &other)
     \since 5.15
-
-    Swaps this Connection instance with \a other. This operation is very fast
-    and never fails.
+    \memberswap{Connection instance}
 */
 
 /*!

src/corelib/text/qcollator.cpp

@@ -168,9 +168,7 @@ QCollator &QCollator::operator=(const QCollator &other)
 
 /*!
     \fn void QCollator::swap(QCollator &other)
-
-    Swaps this collator with \a other. This function is very fast and
-    never fails.
+    \memberswap{collator}
 */
 
 /*!
@@ -470,8 +468,7 @@ QCollatorSortKey& QCollatorSortKey::operator=(const QCollatorSortKey &other)
 
 /*!
     \fn void QCollatorSortKey::swap(QCollatorSortKey & other)
-
-    Swaps this collator key with \a other.
+    \memberswap{collator key}
 */
 
 /*!

src/corelib/time/qdatetime.cpp

@@ -4061,9 +4061,7 @@ QDateTime &QDateTime::operator=(const QDateTime &other) noexcept
 /*!
     \fn void QDateTime::swap(QDateTime &other)
     \since 5.0
-
-    Swaps this datetime with \a other. This operation is very fast
-    and never fails.
+    \memberswap{datetime}
 */
 
 /*!

src/corelib/time/qtimezone.cpp

@@ -713,9 +713,7 @@ QTimeZone::~QTimeZone()
 
 /*!
     \fn QTimeZone::swap(QTimeZone &other) noexcept
-
-    Swaps this time zone instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{time zone instance}
 */
 
 /*!

src/corelib/tools/qscopedpointer.cpp

@@ -308,7 +308,7 @@ QT_BEGIN_NAMESPACE
     \deprecated [6.2] Use \c std::unique_ptr instead; this function may let a pointer
     escape its scope.
 
-    Swap this pointer with \a other.
+    \memberswap{pointer}.
  */
 
 QT_END_NAMESPACE

src/corelib/tools/qsharedpointer.cpp

@@ -527,9 +527,7 @@
 /*!
     \fn template <class T> void QSharedPointer<T>::swap(QSharedPointer<T> &other);
     \since 5.3
-
-    Swaps this shared pointer instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{shared pointer instance}
 */
 
 /*!
@@ -848,9 +846,7 @@
 /*!
     \fn template <class T> void QWeakPointer<T>::swap(QWeakPointer<T> &other)
     \since 5.4
-
-    Swaps this weak pointer instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{weak pointer instance}
 */
 
 /*!

src/dbus/qdbuspendingcall.cpp

@@ -278,9 +278,7 @@ QDBusPendingCall &QDBusPendingCall::operator=(const QDBusPendingCall &other)
 /*!
     \fn void QDBusPendingCall::swap(QDBusPendingCall &other)
     \since 5.0
-
-    Swaps this pending call instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{pending call instance}
 */
 
 /*!

src/dbus/qdbusunixfiledescriptor.cpp

@@ -159,9 +159,7 @@ QDBusUnixFileDescriptor::~QDBusUnixFileDescriptor()
 /*!
     \fn void QDBusUnixFileDescriptor::swap(QDBusUnixFileDescriptor &other)
     \since 5.0
-
-    Swaps this file descriptor instance with \a other. This function
-    is very fast and never fails.
+    \memberswap{file descriptor instance}
 */
 
 /*!

src/gui/kernel/qpalette.cpp

@@ -715,9 +715,7 @@ QPalette &QPalette::operator=(const QPalette &p)
 /*!
     \fn void QPalette::swap(QPalette &other)
     \since 5.0
-
-    Swaps this palette instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{palette instance}
 */
 
 /*!

src/gui/painting/qpagelayout.cpp

@@ -369,9 +369,7 @@ QPageLayout &QPageLayout::operator=(const QPageLayout &other)
 
 /*!
     \fn void QPageLayout::swap(QPageLayout &other)
-
-    Swaps this page layout with \a other. This function is very fast and
-    never fails.
+    \memberswap{page layout}
 */
 
 /*!

src/gui/painting/qpagesize.cpp

@@ -1207,9 +1207,7 @@ QPageSize &QPageSize::operator=(const QPageSize &other)
 
 /*!
     \fn void QPageSize::swap(QPageSize &other)
-
-    Swaps this QPageSize with \a other. This function is very fast and
-    never fails.
+    \memberswap{QPageSize}
 */
 
 /*!

src/gui/text/qfont.cpp

@@ -803,9 +803,7 @@ QFont &QFont::operator=(const QFont &font)
 /*!
     \fn void QFont::swap(QFont &other)
     \since 5.0
-
-    Swaps this font instance with \a other. This function is very fast
-    and never fails.
+    \memberswap{font instance}
 */
 
 /*!
@@ -3096,9 +3094,7 @@ QFontInfo &QFontInfo::operator=(const QFontInfo &fi)
 /*!
     \fn void QFontInfo::swap(QFontInfo &other)
     \since 5.0
-
-    Swaps this font info instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{font info instance}
 */
 
 /*!

src/gui/text/qfontmetrics.cpp

@@ -195,9 +195,7 @@ QFontMetrics &QFontMetrics::operator=(const QFontMetrics &fm)
 /*!
     \fn void QFontMetrics::swap(QFontMetrics &other)
     \since 5.0
-
-    Swaps this font metrics instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{font metrics instance}
 */
 
 /*!
@@ -1038,9 +1036,7 @@ QFontMetricsF &QFontMetricsF::operator=(const QFontMetrics &other)
 /*!
     \fn void QFontMetricsF::swap(QFontMetricsF &other)
     \since 5.0
-
-    Swaps this font metrics instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{font metrics instance}
 */
 
 

src/gui/text/qglyphrun.cpp

@@ -117,9 +117,7 @@ QGlyphRun &QGlyphRun::operator=(const QGlyphRun &other)
 /*!
     \fn void QGlyphRun::swap(QGlyphRun &other)
     \since 5.0
-
-    Swaps this glyph run instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{glyph run instance}
 */
 
 /*!

src/gui/text/qrawfont.cpp

@@ -171,9 +171,7 @@ QRawFont &QRawFont::operator=(const QRawFont &other)
 /*!
   \fn void QRawFont::swap(QRawFont &other)
   \since 5.0
-
-  Swaps this raw font with \a other. This function is very fast and
-  never fails.
+    \memberswap{raw font}
 */
 
 /*!

src/gui/text/qstatictext.cpp

@@ -195,9 +195,7 @@ QStaticText &QStaticText::operator=(const QStaticText &other)
 /*!
     \fn void QStaticText::swap(QStaticText &other)
     \since 5.0
-
-    Swaps this static text instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{static text instance}
 */
 
 /*!

src/gui/text/qtextcursor.cpp

@@ -1083,9 +1083,7 @@ QTextCursor &QTextCursor::operator=(const QTextCursor &cursor)
 /*!
     \fn void QTextCursor::swap(QTextCursor &other)
     \since 5.0
-
-    Swaps this text cursor instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{text cursor instance}
 */
 
 /*!

src/gui/text/qtextformat.cpp

@@ -912,9 +912,7 @@ QTextFormat &QTextFormat::operator=(const QTextFormat &rhs)
 /*!
     \fn void QTextFormat::swap(QTextFormat &other)
     \since 5.0
-
-    Swaps this text format with \a other. This function is very fast
-    and never fails.
+    \memberswap{text format}
 */
 
 /*!

src/network/access/qabstractnetworkcache.cpp

@@ -117,9 +117,7 @@ QNetworkCacheMetaData &QNetworkCacheMetaData::operator=(const QNetworkCacheMetaD
 /*!
     \fn void QNetworkCacheMetaData::swap(QNetworkCacheMetaData &other)
     \since 5.0
-
-    Swaps this metadata instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{metadata instance}
  */
 
 /*!

src/network/access/qhttp1configuration.cpp

@@ -107,9 +107,7 @@ qsizetype QHttp1Configuration::numberOfConnectionsPerHost() const
 
 /*!
     \fn void QHttp1Configuration::swap(QHttp1Configuration &other)
-
-    Swaps this HTTP/1 configuration with \a other. This operation is very fast
-    and never fails.
+    \memberswap{HTTP/1 configuration}
 */
 
 /*!

src/network/access/qhttpheaders.cpp

@@ -959,9 +959,7 @@ QHttpHeaders &QHttpHeaders::operator=(const QHttpHeaders &other)
 
 /*!
     \fn void QHttpHeaders::swap(QHttpHeaders &other)
-
-    Swaps this QHttpHeaders with \a other. This function is very fast and
-    never fails.
+    \memberswap{QHttpHeaders}
 */
 
 #ifndef QT_NO_DEBUG_STREAM

src/network/access/qhttpmultipart.cpp

@@ -90,9 +90,7 @@ QHttpPart &QHttpPart::operator=(const QHttpPart &other)
 /*!
     \fn void QHttpPart::swap(QHttpPart &other)
     \since 5.0
-
-    Swaps this HTTP part with \a other. This function is very fast and
-    never fails.
+    \memberswap{HTTP part}
 */
 
 /*!

src/network/access/qnetworkcookie.cpp

@@ -119,9 +119,7 @@ QNetworkCookie &QNetworkCookie::operator=(const QNetworkCookie &other)
 /*!
     \fn void QNetworkCookie::swap(QNetworkCookie &other)
     \since 5.0
-
-    Swaps this cookie with \a other. This function is very fast and
-    never fails.
+    \memberswap{cookie}
 */
 
 /*!

src/network/access/qnetworkrequest.cpp

@@ -591,9 +591,7 @@ QNetworkRequest &QNetworkRequest::operator=(const QNetworkRequest &other)
 /*!
     \fn void QNetworkRequest::swap(QNetworkRequest &other)
     \since 5.0
-
-    Swaps this network request with \a other. This function is very
-    fast and never fails.
+    \memberswap{network request}
 */
 
 /*!

src/network/access/qnetworkrequestfactory.cpp

@@ -115,9 +115,7 @@ QNetworkRequestFactory &QNetworkRequestFactory::operator=(const QNetworkRequestF
 
 /*!
     \fn void QNetworkRequestFactory::swap(QNetworkRequestFactory &other)
-
-    Swaps this factory with \a other. This operation is
-    very fast and never fails.
+    \memberswap{factory}
  */
 
 /*!

src/network/kernel/qdnslookup.cpp

@@ -882,11 +882,10 @@ QDnsDomainNameRecord &QDnsDomainNameRecord::operator=(const QDnsDomainNameRecord
     d = other.d;
     return *this;
 }
+
 /*!
     \fn void QDnsDomainNameRecord::swap(QDnsDomainNameRecord &other)
-
-    Swaps this domain-name record instance with \a other. This
-    function is very fast and never fails.
+    \memberswap{domain-name record instance}
 */
 
 /*!
@@ -967,11 +966,10 @@ QDnsHostAddressRecord &QDnsHostAddressRecord::operator=(const QDnsHostAddressRec
     d = other.d;
     return *this;
 }
+
 /*!
     \fn void QDnsHostAddressRecord::swap(QDnsHostAddressRecord &other)
-
-    Swaps this host address record instance with \a other. This
-    function is very fast and never fails.
+    \memberswap{host address record instance}
 */
 
 /*!
@@ -1065,9 +1063,7 @@ QDnsMailExchangeRecord &QDnsMailExchangeRecord::operator=(const QDnsMailExchange
 }
 /*!
     \fn void QDnsMailExchangeRecord::swap(QDnsMailExchangeRecord &other)
-
-    Swaps this mail exchange record with \a other. This function is
-    very fast and never fails.
+    \memberswap{mail exchange record}
 */
 
 /*!
@@ -1186,9 +1182,7 @@ QDnsServiceRecord &QDnsServiceRecord::operator=(const QDnsServiceRecord &other)
 }
 /*!
     \fn void QDnsServiceRecord::swap(QDnsServiceRecord &other)
-
-    Swaps this service record instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{service record instance}
 */
 
 /*!
@@ -1273,9 +1267,7 @@ QDnsTextRecord &QDnsTextRecord::operator=(const QDnsTextRecord &other)
 }
 /*!
     \fn void QDnsTextRecord::swap(QDnsTextRecord &other)
-
-    Swaps this text record instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{text record instance}
 */
 
 /*!

src/network/kernel/qhostaddress.cpp

@@ -505,9 +505,7 @@ QHostAddress &QHostAddress::operator=(SpecialAddress address)
 /*!
     \fn void QHostAddress::swap(QHostAddress &other)
     \since 5.6
-
-    Swaps this host address with \a other. This operation is very fast
-    and never fails.
+    \memberswap{host address}
 */
 
 /*!

src/network/kernel/qnetworkinterface.cpp

@@ -190,9 +190,7 @@ QNetworkAddressEntry &QNetworkAddressEntry::operator=(const QNetworkAddressEntry
 /*!
     \fn void QNetworkAddressEntry::swap(QNetworkAddressEntry &other)
     \since 5.0
-
-    Swaps this network address entry instance with \a other. This
-    function is very fast and never fails.
+    \memberswap{network address entry instance}
 */
 
 /*!
@@ -632,9 +630,7 @@ QNetworkInterface &QNetworkInterface::operator=(const QNetworkInterface &other)
 /*!
     \fn void QNetworkInterface::swap(QNetworkInterface &other)
     \since 5.0
-
-    Swaps this network interface instance with \a other. This function
-    is very fast and never fails.
+    \memberswap{network interface instance}
 */
 
 /*!

src/network/kernel/qnetworkproxy.cpp

@@ -538,9 +538,7 @@ QNetworkProxy &QNetworkProxy::operator=(const QNetworkProxy &other)
 /*!
     \fn void QNetworkProxy::swap(QNetworkProxy &other)
     \since 5.0
-
-    Swaps this network proxy instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{network proxy instance}
 */
 
 /*!
@@ -1161,9 +1159,7 @@ QNetworkProxyQuery &QNetworkProxyQuery::operator=(const QNetworkProxyQuery &othe
 /*!
     \fn void QNetworkProxyQuery::swap(QNetworkProxyQuery &other)
     \since 5.0
-
-    Swaps this network proxy query instance with \a other. This
-    function is very fast and never fails.
+    \memberswap{network proxy query instance}
 */
 
 /*!

src/network/ssl/qocspresponse.cpp

@@ -126,8 +126,7 @@ QOcspResponse &QOcspResponse::operator=(QOcspResponse &&) noexcept = default;
 /*!
     \fn void QOcspResponse::swap(QOcspResponse &other)
     \since 5.13
-
-    Swaps this response with \a other.
+    \memberswap{response}
 */
 
 /*!

src/network/ssl/qsslcertificate.cpp

@@ -232,9 +232,7 @@ QSslCertificate &QSslCertificate::operator=(const QSslCertificate &other)
 /*!
     \fn void QSslCertificate::swap(QSslCertificate &other)
     \since 5.0
-
-    Swaps this certificate instance with \a other. This function is
-    very fast and never fails.
+    \memberswap{certificate instance}
 */
 
 /*!

src/network/ssl/qsslcertificateextension.cpp

@@ -130,9 +130,7 @@ QSslCertificateExtension &QSslCertificateExtension::operator=(const QSslCertific
 
 /*!
     \fn void QSslCertificateExtension::swap(QSslCertificateExtension &other)
-
-    Swaps this certificate extension instance with \a other. This
-    function is very fast and never fails.
+    \memberswap{certificate extension instance}
 */
 
 /*!

src/network/ssl/qsslcipher.cpp

@@ -117,9 +117,7 @@ QSslCipher &QSslCipher::operator=(const QSslCipher &other)
 /*!
     \fn void QSslCipher::swap(QSslCipher &other)
     \since 5.0
-
-    Swaps this cipher instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{cipher instance}
 */
 
 /*!

src/network/ssl/qsslconfiguration.cpp

@@ -152,9 +152,7 @@ QSslConfiguration &QSslConfiguration::operator=(const QSslConfiguration &other)
 /*!
     \fn void QSslConfiguration::swap(QSslConfiguration &other)
     \since 5.0
-
-    Swaps this SSL configuration instance with \a other. This function
-    is very fast and never fails.
+    \memberswap{SSL configuration instance}
 */
 
 /*!

src/network/ssl/qssldiffiehellmanparameters.cpp

@@ -171,9 +171,7 @@ QSslDiffieHellmanParameters &QSslDiffieHellmanParameters::operator=(const QSslDi
 
 /*!
     \fn void QSslDiffieHellmanParameters::swap(QSslDiffieHellmanParameters &other)
-
-    Swaps this QSslDiffieHellmanParameters with \a other. This function is very fast and
-    never fails.
+    \memberswap{QSslDiffieHellmanParameters}
 */
 
 /*!

src/network/ssl/qsslerror.cpp

@@ -158,9 +158,7 @@ QSslError &QSslError::operator=(const QSslError &other)
 /*!
     \fn void QSslError::swap(QSslError &other)
     \since 5.0
-
-    Swaps this error instance with \a other. This function is very
-    fast and never fails.
+    \memberswap{error instance}
 */
 
 /*!

src/network/ssl/qsslkey_p.cpp

@@ -214,9 +214,7 @@ QSslKey &QSslKey::operator=(const QSslKey &other)
 /*!
     \fn void QSslKey::swap(QSslKey &other)
     \since 5.0
-
-    Swaps this ssl key with \a other. This function is very fast and
-    never fails.
+    \memberswap{ssl key}
 */
 
 /*!

src/sql/kernel/qsqlfield.cpp

@@ -114,9 +114,7 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QSqlFieldPrivate)
 /*!
     \fn void QSqlField::swap(QSqlField &other)
     \since 6.6
-
-    Swaps this field with \a other. This function is very fast and
-    never fails.
+    \memberswap{field}
 */
 
 /*!