diff options
| author | Marc Mutz <marc.mutz@qt.io> | 2025-02-06 08:15:36 +0100 |
|---|---|---|
| committer | Topi Reinio <topi.reinio@qt.io> | 2025-02-28 13:51:18 +0000 |
| commit | b7a67b46e66f161def5bf879f19c66d3fcec1d8b (patch) | |
| tree | feb68ba2f835a8aeced04ad3563230db49ecb011 /src/corelib/global/qcompare.cpp | |
| parent | 6f89357f59b507c0dcdc177bc1ecfbbc94d6fed3 (diff) | |
Long live \constraints!
We have divergence in the way we document function, operator and
constructor constraints. About half use \note, while the other
doesn't. Some say "if and only if" while others say just "participates
only if".
So add a qdoc macro, \constraints, to semantically mark up these
constraints. It expands to a section titled `Constraints`, and
uses a predefined sentence (prefix) for constraints.
Documentation for constraints is moved to the end of the comment
blocks to separate them from the rest of the text.
Apply them to all the standard-ish constraint documentation blocks
(grepped for "participate"). I didn't look for other, one-off, ways
documentation authors may have documented constraints, but I'm also
not aware of any.
Re-wrap lines only if the result fits into a single line.
As a drive-by, drop additional "if"s, as in "only if X and -if- Y" to
make the texts work with the `Constraints` section.
Fixes: QTBUG-106871
Pick-to: 6.9 6.8 6.5
Change-Id: I18c2f9f734474017264e49165389f8c9c7f34030
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Diffstat (limited to 'src/corelib/global/qcompare.cpp')
| -rw-r--r-- | src/corelib/global/qcompare.cpp | 56 |
1 files changed, 26 insertions, 30 deletions
diff --git a/src/corelib/global/qcompare.cpp b/src/corelib/global/qcompare.cpp index bac725fe6a2..5609ecad896 100644 --- a/src/corelib/global/qcompare.cpp +++ b/src/corelib/global/qcompare.cpp @@ -1287,9 +1287,6 @@ CHECK(strong, equivalent); Implements three-way comparison of integral types. - \note This function participates in overload resolution only if both - \c LeftInt and \c RightInt are built-in integral types. - Returns \c {lhs <=> rhs}, provided \c LeftInt and \c RightInt are built-in integral types. Unlike \c {operator<=>()}, this function template is also available in C++17. See @@ -1315,6 +1312,9 @@ CHECK(strong, equivalent); Returns an instance of \l Qt::strong_ordering that represents the relation between \a lhs and \a rhs. + + \constraints both + \c LeftInt and \c RightInt are built-in integral types. */ /*! @@ -1325,9 +1325,6 @@ CHECK(strong, equivalent); Implements three-way comparison of floating point types. - \note This function participates in overload resolution only if both - \c LeftFloat and \c RightFloat are built-in floating-point types. - Returns \c {lhs <=> rhs}, provided \c LeftFloat and \c RightFloat are built-in floating-point types. Unlike \c {operator<=>()}, this function template is also available in C++17. See @@ -1354,6 +1351,9 @@ CHECK(strong, equivalent); Returns an instance of \l Qt::partial_ordering that represents the relation between \a lhs and \a rhs. If \a lhs or \a rhs is not a number (NaN), \l Qt::partial_ordering::unordered is returned. + + \constraints both + \c LeftFloat and \c RightFloat are built-in floating-point types. */ /*! @@ -1364,16 +1364,16 @@ CHECK(strong, equivalent); Implements three-way comparison of integral and floating point types. - \note This function participates in overload resolution only if \c IntType - is a built-in integral type and \c FloatType is a built-in floating-point - type. - This function converts \a lhs to \c FloatType and calls the overload for floating-point types. Returns an instance of \l Qt::partial_ordering that represents the relation between \a lhs and \a rhs. If \a rhs is not a number (NaN), \l Qt::partial_ordering::unordered is returned. + + \constraints \c IntType + is a built-in integral type and \c FloatType is a built-in floating-point + type. */ /*! @@ -1384,16 +1384,16 @@ CHECK(strong, equivalent); Implements three-way comparison of floating point and integral types. - \note This function participates in overload resolution only if \c FloatType - is a built-in floating-point type and \c IntType is a built-in integral - type. - This function converts \a rhs to \c FloatType and calls the overload for floating-point types. Returns an instance of \l Qt::partial_ordering that represents the relation between \a lhs and \a rhs. If \a lhs is not a number (NaN), \l Qt::partial_ordering::unordered is returned. + + \constraints \c FloatType + is a built-in floating-point type and \c IntType is a built-in integral + type. */ #if QT_DEPRECATED_SINCE(6, 8) @@ -1407,12 +1407,12 @@ CHECK(strong, equivalent); Implements three-way comparison of pointers. - \note This function participates in overload resolution if \c LeftType and - \c RightType are the same type, or base and derived types. It is also used - to compare any pointer to \c {std::nullptr_t}. - Returns an instance of \l Qt::strong_ordering that represents the relation between \a lhs and \a rhs. + + \constraints \c LeftType and + \c RightType are the same type, or base and derived types. It is also used + to compare any pointer to \c {std::nullptr_t}. */ #endif // QT_DEPRECATED_SINCE(6, 8) @@ -1424,14 +1424,13 @@ CHECK(strong, equivalent); Implements three-way comparison of enum types. - \note This function participates in overload resolution only if \c Enum - is an enum type. - This function converts \c Enum to its underlying type and calls the overload for integral types. Returns an instance of \l Qt::strong_ordering that represents the relation between \a lhs and \a rhs. + + \constraints \c Enum is an enum type. */ /*! @@ -1445,11 +1444,10 @@ CHECK(strong, equivalent); \l {https://en.cppreference.com/w/cpp/language/operator_comparison#Pointer_total_order} {strict total order over pointers} when doing the comparison. - \note This function participates in overload resolution if \c T and \c U - are the same type, or base and derived types. - Returns an instance of \l Qt::strong_ordering that represents the relation between \a lhs and \a rhs. + + \constraints \c T and \c U are the same type, or base and derived types. */ /*! @@ -1463,11 +1461,10 @@ CHECK(strong, equivalent); \l {https://en.cppreference.com/w/cpp/language/operator_comparison#Pointer_total_order} {strict total order over pointers} when doing the comparison. - \note This function participates in overload resolution if \c T and \c U - are the same type, or base and derived types. - Returns an instance of \l Qt::strong_ordering that represents the relation between \a lhs and \a rhs. + + \constraints \c T and \c U are the same type, or base and derived types. */ /*! @@ -1481,11 +1478,10 @@ CHECK(strong, equivalent); \l {https://en.cppreference.com/w/cpp/language/operator_comparison#Pointer_total_order} {strict total order over pointers} when doing the comparison. - \note This function participates in overload resolution if \c T and \c U - are the same type, or base and derived types. - Returns an instance of \l Qt::strong_ordering that represents the relation between \a lhs and \a rhs. + + \constraints \c T and \c U are the same type, or base and derived types. */ /*! |