Create qdoc macros for C++ class docs 1.1: member-swap(), traditional 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 the first patch is for
documentation that used the traditional phrasing ("Swaps the X \a
other with this X.").

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

* 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: Ib494bd218334724b3b43796ba6f71fb52b83aa94
Reviewed-by: Ivan Solovev <[email protected]>

46 files changed, 65 insertions, 143 deletions

diff --git a/doc/global/cpp-doc-macros.qdocconf b/doc/global/cpp-doc-macros.qdocconf
new file mode 100644
index 00000000000..ce98d5cae4f
--- /dev/null
+++ b/doc/global/cpp-doc-macros.qdocconf
@@ -0,0 +1,15 @@
+# Macros for documenting repetitive aspects of C++ classes
+
+# Sort groups alphabetically
+
+#
+# Macros for swap()
+#
+
+# \memberswap{what}
+#    what - a prose version of the type of object (e.g. "string", "collator", "pen")
+#    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." \
+    "\n\n"
diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf
index ab24524f919..ba63652566d 100644
--- a/doc/global/macros.qdocconf
+++ b/doc/global/macros.qdocconf
@@ -174,3 +174,4 @@ macro.qtpolicydeprecatedbehavior = "\\note The \\c{OLD} behavior of a policy is
 macro.techpreview = "(Technical preview)\n\n\\meta status {Technical preview}\n\\ingroup tech_preview\n"
 
 include(grid.qdocconf)
+include(cpp-doc-macros.qdocconf)
diff --git a/src/corelib/io/qtemporarydir.cpp b/src/corelib/io/qtemporarydir.cpp
index 751057f5fee..b5e22f6d5d2 100644
--- a/src/corelib/io/qtemporarydir.cpp
+++ b/src/corelib/io/qtemporarydir.cpp
@@ -191,10 +191,7 @@ QTemporaryDir::QTemporaryDir(const QString &templatePath)
 
 /*!
     \fn void QTemporaryDir::swap(QTemporaryDir &other)
-
-    Swaps temporary-dir \a other with this temporary-dir. This operation is
-    very fast and never fails.
-
+    \memberswap{temporary-dir}
     \since 6.4
 */
 
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index 7bd2288b8af..6038639eabf 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -3229,9 +3229,7 @@ QUrl &QUrl::operator =(const QString &url)
 /*!
     \fn void QUrl::swap(QUrl &other)
     \since 4.8
-
-    Swaps URL \a other with this URL. This operation is very
-    fast and never fails.
+    \memberswap{URL}
 */
 
 /*!
diff --git a/src/corelib/kernel/qbasictimer.cpp b/src/corelib/kernel/qbasictimer.cpp
index 00e93eedc70..b7e2f114519 100644
--- a/src/corelib/kernel/qbasictimer.cpp
+++ b/src/corelib/kernel/qbasictimer.cpp
@@ -87,9 +87,7 @@ QT_BEGIN_NAMESPACE
 /*!
     \fn QBasicTimer::swap(QBasicTimer &other)
     \since 5.14
-
-    Swaps the timer \a other with this timer.
-    This operation is very fast and never fails.
+    \memberswap{timer}
 */
 
 /*!
diff --git a/src/corelib/kernel/qdeadlinetimer.cpp b/src/corelib/kernel/qdeadlinetimer.cpp
index f99e68f990b..518fc3f60d5 100644
--- a/src/corelib/kernel/qdeadlinetimer.cpp
+++ b/src/corelib/kernel/qdeadlinetimer.cpp
@@ -729,8 +729,7 @@ QDeadlineTimer operator+(QDeadlineTimer dt, qint64 msecs)
 
 /*!
   \fn void QDeadlineTimer::swap(QDeadlineTimer &other)
-
-  Swaps this deadline timer with the \a other deadline timer.
+    \memberswap{deadline timer}
  */
 
 /*!
diff --git a/src/corelib/kernel/qvariant.cpp b/src/corelib/kernel/qvariant.cpp
index 92a44c462b0..b84cd7e2749 100644
--- a/src/corelib/kernel/qvariant.cpp
+++ b/src/corelib/kernel/qvariant.cpp
@@ -1074,9 +1074,7 @@ QVariant &QVariant::operator=(const QVariant &variant)
 /*!
     \fn void QVariant::swap(QVariant &other)
     \since 4.8
-
-    Swaps variant \a other with this variant. This operation is very
-    fast and never fails.
+    \memberswap{variant}
 */
 
 /*!
diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp
index a0d633076bf..0b3999b10c7 100644
--- a/src/corelib/text/qbytearray.cpp
+++ b/src/corelib/text/qbytearray.cpp
@@ -1397,9 +1397,7 @@ QByteArray &QByteArray::operator=(const char *str)
 
 /*! \fn void QByteArray::swap(QByteArray &other)
     \since 4.8
-
-    Swaps byte array \a other with this byte array. This operation is very
-    fast and never fails.
+    \memberswap{byte array}
 */
 
 /*! \fn qsizetype QByteArray::size() const
diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp
index 01e838f76df..684365f3406 100644
--- a/src/corelib/text/qlocale.cpp
+++ b/src/corelib/text/qlocale.cpp
@@ -1251,9 +1251,7 @@ bool QLocale::equals(const QLocale &other) const noexcept
 /*!
     \fn void QLocale::swap(QLocale &other)
     \since 5.6
-
-    Swaps locale \a other with this locale. This operation is very fast and
-    never fails.
+    \memberswap{locale}
 */
 
 /*!
diff --git a/src/corelib/text/qregularexpression.cpp b/src/corelib/text/qregularexpression.cpp
index e2fd000314a..8a143de5a65 100644
--- a/src/corelib/text/qregularexpression.cpp
+++ b/src/corelib/text/qregularexpression.cpp
@@ -1389,9 +1389,7 @@ QRegularExpression &QRegularExpression::operator=(const QRegularExpression &re)
 
 /*!
     \fn void QRegularExpression::swap(QRegularExpression &other)
-
-    Swaps the regular expression \a other with this regular expression. This
-    operation is very fast and never fails.
+    \memberswap{reglar expression}
 */
 
 /*!
@@ -2160,9 +2158,7 @@ QRegularExpressionMatch &QRegularExpressionMatch::operator=(const QRegularExpres
 
 /*!
     \fn void QRegularExpressionMatch::swap(QRegularExpressionMatch &other)
-
-    Swaps the match result \a other with this match result. This
-    operation is very fast and never fails.
+    \memberswap{match result}
 */
 
 /*!
diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp
index dabfbfa7c38..03e6eb0593a 100644
--- a/src/corelib/text/qstring.cpp
+++ b/src/corelib/text/qstring.cpp
@@ -2596,9 +2596,7 @@ QString::QString(QChar ch)
 
 /*! \fn void QString::swap(QString &other)
     \since 4.8
-
-    Swaps string \a other with this string. This operation is very fast and
-    never fails.
+    \memberswap{string}
 */
 
 /*! \fn void QString::detach()
diff --git a/src/corelib/thread/qpromise.qdoc b/src/corelib/thread/qpromise.qdoc
index e9c3eb4b7e9..31772c28873 100644
--- a/src/corelib/thread/qpromise.qdoc
+++ b/src/corelib/thread/qpromise.qdoc
@@ -289,6 +289,5 @@
 */
 
 /*! \fn template<typename T> void QPromise<T>::swap(QPromise<T> &other) noexcept
-
-    Swaps promise \a other with this promise. This operation is very fast and never fails.
+    \memberswap{promise}
 */
diff --git a/src/corelib/tools/qbitarray.cpp b/src/corelib/tools/qbitarray.cpp
index d5643df0250..46e4af37b0f 100644
--- a/src/corelib/tools/qbitarray.cpp
+++ b/src/corelib/tools/qbitarray.cpp
@@ -496,9 +496,7 @@ quint32 QBitArray::toUInt32(QSysInfo::Endian endianness, bool *ok) const noexcep
 
 /*! \fn void QBitArray::swap(QBitArray &other)
     \since 4.8
-
-    Swaps bit array \a other with this bit array. This operation is very
-    fast and never fails.
+    \memberswap{bit array}
 */
 
 /*! \fn bool QBitArray::operator==(const QBitArray &lhs, const QBitArray &rhs)
diff --git a/src/corelib/tools/qcommandlineoption.cpp b/src/corelib/tools/qcommandlineoption.cpp
index 5d8f089d5b9..7c09d319d6d 100644
--- a/src/corelib/tools/qcommandlineoption.cpp
+++ b/src/corelib/tools/qcommandlineoption.cpp
@@ -197,9 +197,7 @@ QCommandLineOption &QCommandLineOption::operator=(const QCommandLineOption &othe
 
 /*!
     \fn void QCommandLineOption::swap(QCommandLineOption &other)
-
-    Swaps option \a other with this option. This operation is very
-    fast and never fails.
+    \memberswap{option}
 */
 
 /*!
diff --git a/src/corelib/tools/qcontiguouscache.cpp b/src/corelib/tools/qcontiguouscache.cpp
index d28d1e71530..4a3fd73dc1f 100644
--- a/src/corelib/tools/qcontiguouscache.cpp
+++ b/src/corelib/tools/qcontiguouscache.cpp
@@ -164,9 +164,7 @@ void QContiguousCacheData::freeData(QContiguousCacheData *data)
 
 /*! \fn template<typename T> void QContiguousCache<T>::swap(QContiguousCache<T> &other)
     \since 4.8
-
-    Swaps cache \a other with this cache. This operation is very
-    fast and never fails.
+    \memberswap{cache}
 */
 
 /*! \fn template<typename T> bool QContiguousCache<T>::operator==(const QContiguousCache<T> &other) const
diff --git a/src/corelib/tools/qcryptographichash.cpp b/src/corelib/tools/qcryptographichash.cpp
index 2899f7741b2..aefb91abecb 100644
--- a/src/corelib/tools/qcryptographichash.cpp
+++ b/src/corelib/tools/qcryptographichash.cpp
@@ -467,10 +467,7 @@ QCryptographicHash::~QCryptographicHash()
 
 /*!
     \fn void QCryptographicHash::swap(QCryptographicHash &other)
-
-    Swaps cryptographic hash \a other with this cryptographic hash. This
-    operation is very fast and never fails.
-
+    \memberswap{cryptographic hash}
     \since 6.5
 */
 
@@ -1479,10 +1476,7 @@ QMessageAuthenticationCode::~QMessageAuthenticationCode()
 
 /*!
     \fn void QMessageAuthenticationCode::swap(QMessageAuthenticationCode &other)
-
-    Swaps message authentication code \a other with this message authentication
-    code. This operation is very fast and never fails.
-
+    \memberswap{message authentication code}
     \since 6.6
 */
 
diff --git a/src/corelib/tools/qeasingcurve.cpp b/src/corelib/tools/qeasingcurve.cpp
index 06369528e88..3d01855f811 100644
--- a/src/corelib/tools/qeasingcurve.cpp
+++ b/src/corelib/tools/qeasingcurve.cpp
@@ -1147,9 +1147,7 @@ QEasingCurve::~QEasingCurve()
 /*!
     \fn void QEasingCurve::swap(QEasingCurve &other)
     \since 5.0
-
-    Swaps curve \a other with this curve. This operation is very
-    fast and never fails.
+    \memberswap{curve}
 */
 
 /*!
diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index 56245dcd355..6c8aef1c744 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -1795,16 +1795,12 @@ size_t qHash(long double key, size_t seed) noexcept
 
 /*! \fn template <class Key, class T> void QHash<Key, T>::swap(QHash &other)
     \since 4.8
-
-    Swaps hash \a other with this hash. This operation is very
-    fast and never fails.
+    \memberswap{hash}
 */
 
 /*! \fn template <class Key, class T> void QMultiHash<Key, T>::swap(QMultiHash &other)
     \since 4.8
-
-    Swaps hash \a other with this hash. This operation is very
-    fast and never fails.
+    \memberswap{multi-hash}
 */
 
 /*! \fn template <class Key, class T> bool QHash<Key, T>::operator==(const QHash &lhs, const QHash &rhs)
diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc
index 19b10fde4d1..bc5feac7a0f 100644
--- a/src/corelib/tools/qlist.qdoc
+++ b/src/corelib/tools/qlist.qdoc
@@ -342,9 +342,7 @@
 
 /*! \fn template <typename T> void QList<T>::swap(QList<T> &other)
     \since 4.8
-
-    Swaps list \a other with this list. This operation is very fast and
-    never fails.
+    \memberswap{list}
 */
 
 /*! \fn template <typename T> void QList<T>::swapItemsAt(qsizetype i, qsizetype j)
diff --git a/src/corelib/tools/qmap.qdoc b/src/corelib/tools/qmap.qdoc
index 1574fa581e4..7f8414ed969 100644
--- a/src/corelib/tools/qmap.qdoc
+++ b/src/corelib/tools/qmap.qdoc
@@ -172,9 +172,7 @@
 
 /*! \fn template <class Key, class T> void QMap<Key, T>::swap(QMap<Key, T> &other) noexcept
     \since 4.8
-
-    Swaps map \a other with this map. This operation is very
-    fast and never fails.
+    \memberswap{map}
 */
 
 /*! \fn template <class Key, class T> QMap<Key, T>::QMap(std::initializer_list<std::pair<Key,T> > list)
diff --git a/src/corelib/tools/qmultimap.qdoc b/src/corelib/tools/qmultimap.qdoc
index 63f516bee37..8a008d27960 100644
--- a/src/corelib/tools/qmultimap.qdoc
+++ b/src/corelib/tools/qmultimap.qdoc
@@ -218,9 +218,7 @@
 
 /*! \fn template <class Key, class T> void QMultiMap<Key, T>::swap(QMultiMap<Key, T> &other)
     \since 4.8
-
-    Swaps multi map \a other with this multi map. This operation is very
-    fast and never fails.
+    \memberswap{multi map}
 */
 
 /*! \fn template<class Key, class T> bool QMultiMap<Key, T>::operator==(const QMultiMap<Key, T> &lhs, const QMultiMap<Key, T> &rhs)
diff --git a/src/corelib/tools/qqueue.cpp b/src/corelib/tools/qqueue.cpp
index 82095faa3d6..74ab49b3bf9 100644
--- a/src/corelib/tools/qqueue.cpp
+++ b/src/corelib/tools/qqueue.cpp
@@ -43,9 +43,7 @@
 /*!
     \fn template <class T> void QQueue<T>::swap(QQueue<T> &other)
     \since 4.8
-
-    Swaps queue \a other with this queue. This operation is very
-    fast and never fails.
+    \memberswap{queue}
 */
 
 /*!
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
index 19a21a6d32e..d5eac370fae 100644
--- a/src/corelib/tools/qset.qdoc
+++ b/src/corelib/tools/qset.qdoc
@@ -100,9 +100,7 @@
 
 /*!
     \fn template <class T> void QSet<T>::swap(QSet<T> &other)
-
-    Swaps set \a other with this set. This operation is very fast and
-    never fails.
+    \memberswap{set}
 */
 
 /*!
diff --git a/src/corelib/tools/qstack.cpp b/src/corelib/tools/qstack.cpp
index 5255e0e100d..da8123b0584 100644
--- a/src/corelib/tools/qstack.cpp
+++ b/src/corelib/tools/qstack.cpp
@@ -43,9 +43,7 @@
 /*!
     \fn template<class T> void QStack<T>::swap(QStack<T> &other)
     \since 4.8
-
-    Swaps stack \a other with this stack. This operation is very fast and
-    never fails.
+    \memberswap{stack}
 */
 
 /*!
diff --git a/src/gui/image/qbitmap.cpp b/src/gui/image/qbitmap.cpp
index 315c847c919..c9310bef666 100644
--- a/src/gui/image/qbitmap.cpp
+++ b/src/gui/image/qbitmap.cpp
@@ -129,9 +129,7 @@ QBitmap::QBitmap(const QString& fileName, const char *format)
 
 /*!
     \fn void QBitmap::swap(QBitmap &other)
-
-    Swaps bitmap \a other with this bitmap. This operation is very
-    fast and never fails.
+    \memberswap{bitmap}
 */
 
 /*!
diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp
index 31e6ddaaba1..166b435e7aa 100644
--- a/src/gui/image/qicon.cpp
+++ b/src/gui/image/qicon.cpp
@@ -827,9 +827,7 @@ QIcon &QIcon::operator=(const QIcon &other)
 
 /*!
     \fn void QIcon::swap(QIcon &other)
-
-    Swaps icon \a other with this icon. This operation is very
-    fast and never fails.
+    \memberswap{icon}
 */
 
 /*!
diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp
index 0e95978fe0b..ebec640b47d 100644
--- a/src/gui/image/qimage.cpp
+++ b/src/gui/image/qimage.cpp
@@ -1091,9 +1091,7 @@ QImage &QImage::operator=(const QImage &image)
 
 /*!
     \fn void QImage::swap(QImage &other)
-
-    Swaps image \a other with this image. This operation is very
-    fast and never fails.
+    \memberswap{image}
 */
 
 /*!
diff --git a/src/gui/image/qpicture.cpp b/src/gui/image/qpicture.cpp
index 0bc21a3e9f7..9e902d69b82 100644
--- a/src/gui/image/qpicture.cpp
+++ b/src/gui/image/qpicture.cpp
@@ -925,9 +925,7 @@ QPicture& QPicture::operator=(const QPicture &p)
 
 /*!
     \fn void QPicture::swap(QPicture &other)
-
-    Swaps picture \a other with this picture. This operation is very
-    fast and never fails.
+    \memberswap{picture}
 */
 
 /*!
diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp
index a6625fc4716..cbfb5e2d8d4 100644
--- a/src/gui/image/qpixmap.cpp
+++ b/src/gui/image/qpixmap.cpp
@@ -368,9 +368,7 @@ QPixmap &QPixmap::operator=(const QPixmap &pixmap)
 
 /*!
     \fn void QPixmap::swap(QPixmap &other)
-
-    Swaps pixmap \a other with this pixmap. This operation is very
-    fast and never fails.
+    \memberswap{pixmap}
 */
 
 /*!
diff --git a/src/gui/kernel/qcursor.cpp b/src/gui/kernel/qcursor.cpp
index 8e7747559ad..268d0b2f144 100644
--- a/src/gui/kernel/qcursor.cpp
+++ b/src/gui/kernel/qcursor.cpp
@@ -137,8 +137,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
   \fn void QCursor::swap(QCursor &other)
-
-  Swaps this cursor with the \a other cursor.
+    \memberswap{cursor}
 
   \since 5.7
  */
diff --git a/src/gui/kernel/qkeysequence.cpp b/src/gui/kernel/qkeysequence.cpp
index cbdf116ea93..ad9b3527f15 100644
--- a/src/gui/kernel/qkeysequence.cpp
+++ b/src/gui/kernel/qkeysequence.cpp
@@ -1385,9 +1385,7 @@ QKeySequence &QKeySequence::operator=(const QKeySequence &other)
 /*!
     \fn void QKeySequence::swap(QKeySequence &other)
     \since 4.8
-
-    Swaps key sequence \a other with this key sequence. This operation is very
-    fast and never fails.
+    \memberswap{key sequence}
 */
 
 /*!
diff --git a/src/gui/painting/qbrush.cpp b/src/gui/painting/qbrush.cpp
index b0538962332..5a6fbd8232a 100644
--- a/src/gui/painting/qbrush.cpp
+++ b/src/gui/painting/qbrush.cpp
@@ -625,9 +625,7 @@ QBrush &QBrush::operator=(const QBrush &b)
 /*!
     \fn void QBrush::swap(QBrush &other)
     \since 4.8
-
-    Swaps brush \a other with this brush. This operation is very
-    fast and never fails.
+    \memberswap{brush}
 */
 
 /*!
diff --git a/src/gui/painting/qcolorspace.cpp b/src/gui/painting/qcolorspace.cpp
index 0a38b2ec140..e93cf0caebf 100644
--- a/src/gui/painting/qcolorspace.cpp
+++ b/src/gui/painting/qcolorspace.cpp
@@ -783,9 +783,7 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QColorSpacePrivate)
 QColorSpace::QColorSpace(const QColorSpace &colorSpace) noexcept = default;
 
 /*! \fn void QColorSpace::swap(QColorSpace &other)
-
-    Swaps color space \a other with this color space. This operation is very fast and
-    never fails.
+    \memberswap{color space}
 */
 
 /*!
diff --git a/src/gui/painting/qpainterpath.cpp b/src/gui/painting/qpainterpath.cpp
index e55422a672c..d79c85c8f5d 100644
--- a/src/gui/painting/qpainterpath.cpp
+++ b/src/gui/painting/qpainterpath.cpp
@@ -563,9 +563,7 @@ QPainterPath &QPainterPath::operator=(const QPainterPath &other)
 /*!
     \fn void QPainterPath::swap(QPainterPath &other)
     \since 4.8
-
-    Swaps painter path \a other with this painter path. This operation is very
-    fast and never fails.
+    \memberswap{painer path}
 */
 
 /*!
diff --git a/src/gui/painting/qpdfoutputintent.cpp b/src/gui/painting/qpdfoutputintent.cpp
index b960986c8d3..519dab6db28 100644
--- a/src/gui/painting/qpdfoutputintent.cpp
+++ b/src/gui/painting/qpdfoutputintent.cpp
@@ -80,9 +80,7 @@ QPdfOutputIntent::~QPdfOutputIntent() = default;
 
 /*!
     \fn void QPdfOutputIntent::swap(QPdfOutputIntent &other) noexcept
-
-    Swaps the output intent \a other with this output intent. This
-    operation is very fast and never fails.
+    \memberswap{output intent}
 */
 
 /*!
diff --git a/src/gui/painting/qpen.cpp b/src/gui/painting/qpen.cpp
index ce1ad6e129e..fc151763aac 100644
--- a/src/gui/painting/qpen.cpp
+++ b/src/gui/painting/qpen.cpp
@@ -341,9 +341,7 @@ QPen &QPen::operator=(const QPen &p) noexcept
 /*!
     \fn void QPen::swap(QPen &other)
     \since 4.8
-
-    Swaps pen \a other with this pen. This operation is very
-    fast and never fails.
+    \memberswap{pen}
 */
 
 /*!
diff --git a/src/gui/painting/qpolygon.cpp b/src/gui/painting/qpolygon.cpp
index d615245eb48..c9153602074 100644
--- a/src/gui/painting/qpolygon.cpp
+++ b/src/gui/painting/qpolygon.cpp
@@ -623,17 +623,13 @@ QPolygon QPolygonF::toPolygon() const
 /*!
     \fn void QPolygon::swap(QPolygon &other)
     \since 4.8
-
-    Swaps polygon \a other with this polygon. This operation is very
-    fast and never fails.
+    \memberswap{polygon}
 */
 
 /*!
     \fn void QPolygonF::swap(QPolygonF &other)
     \since 4.8
-
-    Swaps polygon \a other with this polygon. This operation is very
-    fast and never fails.
+    \memberswap{polygon}
 */
 
 /*!
diff --git a/src/gui/painting/qregion.cpp b/src/gui/painting/qregion.cpp
index 132abed0f1a..0d39ee05437 100644
--- a/src/gui/painting/qregion.cpp
+++ b/src/gui/painting/qregion.cpp
@@ -296,9 +296,7 @@ void QRegion::exec(const QByteArray &buffer, int ver, QDataStream::ByteOrder byt
 /*!
     \fn void QRegion::swap(QRegion &other)
     \since 4.8
-
-    Swaps region \a other with this region. This operation is very
-    fast and never fails.
+    \memberswap{region}
 */
 
 /*!
diff --git a/src/gui/rhi/qshader.cpp b/src/gui/rhi/qshader.cpp
index d5fb53e7e6a..3a5fa3da0fb 100644
--- a/src/gui/rhi/qshader.cpp
+++ b/src/gui/rhi/qshader.cpp
@@ -332,9 +332,7 @@ QShader::~QShader()
 /*!
     \fn void QShader::swap(QShader &other)
     \since 6.7
-
-    Swaps shader \a other with this shader. This operation is very fast and
-    never fails.
+    \memberswap{shader}
 */
 
 /*!
diff --git a/src/network/access/qhstspolicy.cpp b/src/network/access/qhstspolicy.cpp
index 323e562c3c5..e1afbc02bf5 100644
--- a/src/network/access/qhstspolicy.cpp
+++ b/src/network/access/qhstspolicy.cpp
@@ -198,8 +198,7 @@ bool QHstsPolicy::isExpired() const
 
 /*!
   \fn void QHstsPolicy::swap(QHstsPolicy &other)
-
-  Swaps this policy with the \a other policy.
+    \memberswap{policy}
 */
 
 QT_END_NAMESPACE
diff --git a/src/network/access/qhttp2configuration.cpp b/src/network/access/qhttp2configuration.cpp
index 95a462396d8..72a55451f17 100644
--- a/src/network/access/qhttp2configuration.cpp
+++ b/src/network/access/qhttp2configuration.cpp
@@ -281,7 +281,7 @@ unsigned QHttp2Configuration::maxConcurrentStreams() const
 }
 
 /*!
-    Swaps this configuration with the \a other configuration.
+    \memberswap{configuration}
 */
 void QHttp2Configuration::swap(QHttp2Configuration &other) noexcept
 {
diff --git a/src/network/kernel/qhostinfo.cpp b/src/network/kernel/qhostinfo.cpp
index 16037092733..82c9e08c889 100644
--- a/src/network/kernel/qhostinfo.cpp
+++ b/src/network/kernel/qhostinfo.cpp
@@ -249,10 +249,7 @@ int QHostInfo::lookupHost(const QString &name, const QObject *receiver, const ch
 
 /*!
     \fn void QHostInfo::swap(QHostInfo &other)
-
-    Swaps host-info \a other with this host-info. This operation is
-    very fast and never fails.
-
+    \memberswap{host-info}
     \since 5.10
 */
 
diff --git a/src/opengl/qopenglbuffer.cpp b/src/opengl/qopenglbuffer.cpp
index 64e79750430..34ad5aa82d9 100644
--- a/src/opengl/qopenglbuffer.cpp
+++ b/src/opengl/qopenglbuffer.cpp
@@ -216,9 +216,7 @@ QOpenGLBuffer &QOpenGLBuffer::operator=(const QOpenGLBuffer &other)
 /*!
     \fn QOpenGLBuffer::swap(QOpenGLBuffer &other)
     \since 6.5
-
-    Swaps buffer \a other with this buffer. This operation is very fast and
-    never fails.
+    \memberswap{buffer}
 */
 
 /*!
diff --git a/src/opengl/qopengldebug.cpp b/src/opengl/qopengldebug.cpp
index aa2738bb506..dfc82dcdd66 100644
--- a/src/opengl/qopengldebug.cpp
+++ b/src/opengl/qopengldebug.cpp
@@ -846,10 +846,8 @@ QOpenGLDebugMessage &QOpenGLDebugMessage::operator=(const QOpenGLDebugMessage &d
 */
 
 /*!
-    \fn void QOpenGLDebugMessage::swap(QOpenGLDebugMessage &debugMessage)
-
-    Swaps the message \a debugMessage with this message. This operation is very
-    fast and never fails.
+    \fn void QOpenGLDebugMessage::swap(QOpenGLDebugMessage &other)
+    \memberswap{message]
 */
 
 /*!
diff --git a/src/sql/kernel/qsqlerror.cpp b/src/sql/kernel/qsqlerror.cpp
index a52f209d531..595cc89427e 100644
--- a/src/sql/kernel/qsqlerror.cpp
+++ b/src/sql/kernel/qsqlerror.cpp
@@ -78,9 +78,7 @@ QT_DEFINE_QESDP_SPECIALIZATION_DTOR(QSqlErrorPrivate)
 */
 
 /*! \fn QSqlError::swap(QSqlError &other)
-    Swaps error \a other with this error. This operation is very fast
-    and never fails.
-
+    \memberswap{error}
     \since 5.10
 */
 
diff --git a/src/sql/kernel/qsqlrecord.cpp b/src/sql/kernel/qsqlrecord.cpp
index 3c3b2b33909..6cbf9005ad4 100644
--- a/src/sql/kernel/qsqlrecord.cpp
+++ b/src/sql/kernel/qsqlrecord.cpp
@@ -130,9 +130,7 @@ QSqlRecord::QSqlRecord(const QSqlRecord &other)
 /*!
     \fn void QSqlRecord::swap(QSqlRecord &other)
     \since 6.6
-
-    Swaps SQL record \a other with this SQL record. This operation is very fast
-    and never fails.
+    \memberswap{SQL record}
 */