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
-
+    \memberswap{debug stream instance}
-    Swaps this debug stream instance with \a other. This function is
-    very fast and never fails.
 */
 
 /*!

src/corelib/io/qdir.cpp

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

src/corelib/io/qfileinfo.cpp

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

src/corelib/io/qprocess.cpp

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

src/corelib/io/qstorageinfo.cpp

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

src/corelib/io/qurlquery.cpp

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

src/corelib/itemmodels/qabstractitemmodel.cpp

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

src/corelib/itemmodels/qitemselectionmodel.cpp

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

src/corelib/kernel/qjniarray.qdoc

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

src/corelib/kernel/qjniobject.cpp

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

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
-
+    \memberswap{Connection instance}
-    Swaps this Connection instance with \a other. This operation is very fast
-    and never fails.
 */
 
 /*!

src/corelib/text/qcollator.cpp

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

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

src/corelib/time/qtimezone.cpp

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

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

src/dbus/qdbuspendingcall.cpp

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

src/dbus/qdbusunixfiledescriptor.cpp

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

src/gui/kernel/qpalette.cpp

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

src/gui/painting/qpagelayout.cpp

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

src/gui/painting/qpagesize.cpp

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

src/gui/text/qfont.cpp

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

src/gui/text/qfontmetrics.cpp

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

src/gui/text/qglyphrun.cpp

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

src/gui/text/qrawfont.cpp

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

src/gui/text/qstatictext.cpp

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

src/gui/text/qtextcursor.cpp

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

src/gui/text/qtextformat.cpp

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

src/network/access/qabstractnetworkcache.cpp

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

src/network/access/qhttp1configuration.cpp

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

src/network/access/qhttpheaders.cpp

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

src/network/access/qnetworkcookie.cpp

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

src/network/access/qnetworkrequest.cpp

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

src/network/access/qnetworkrequestfactory.cpp

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

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

src/network/kernel/qhostaddress.cpp

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

src/network/kernel/qnetworkinterface.cpp

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

src/network/kernel/qnetworkproxy.cpp

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

src/network/ssl/qocspresponse.cpp

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

src/network/ssl/qsslcertificate.cpp

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

src/network/ssl/qsslcertificateextension.cpp

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

src/network/ssl/qsslcipher.cpp

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

src/network/ssl/qsslconfiguration.cpp

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

src/network/ssl/qssldiffiehellmanparameters.cpp

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

src/network/ssl/qsslerror.cpp

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

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
-
+    \memberswap{ssl key}
-    Swaps this ssl key with \a other. This function is very fast and
-    never fails.
 */
 
 /*!

src/sql/kernel/qsqlfield.cpp

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