5627e11379
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>
16 lines
401 B
Plaintext
16 lines
401 B
Plaintext
# 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 this \1 with \\a{other}. This operation is very fast and never fails." \
|
|
"\n\n"
|