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