qiurui
/
qtbase
mirror of https://github.com/qt/qtbase.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
qtbase/doc/global/cpp-doc-macros.qdocconf

16 lines
401 B
Plaintext
Raw Normal View History

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 <ivan.solovev@qt.io>
2024-10-02 16:46:01 +00:00
# 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" \
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>
2024-10-02 16:46:01 +00:00
"Swaps this \1 with \\a{other}. This operation is very fast and never fails." \
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 <ivan.solovev@qt.io>
2024-10-02 16:46:01 +00:00
"\n\n"