From bcdd7c260ba6cc35b66858366970591549dfc50e Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Thu, 6 Feb 2025 08:15:36 +0100 Subject: [PATCH] Long live \constraints! MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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.8 6.5 Change-Id: I18c2f9f734474017264e49165389f8c9c7f34030 Reviewed-by: Kai Köhne Reviewed-by: Paul Wicking Reviewed-by: Volker Hilsheimer (cherry picked from commit b7a67b46e66f161def5bf879f19c66d3fcec1d8b) Reviewed-by: Qt Cherry-pick Bot --- doc/global/macros.qdocconf | 5 +++ src/corelib/global/qcompare.cpp | 56 ++++++++++++-------------- src/corelib/io/qdebug.cpp | 3 +- src/corelib/kernel/qjniarray.qdoc | 10 ++--- src/corelib/kernel/qmath.qdoc | 3 +- src/corelib/kernel/qpermissions.cpp | 8 ++-- src/corelib/kernel/qpointer.qdoc | 6 +-- src/corelib/kernel/qvariant.cpp | 5 +-- src/corelib/text/qanystringview.cpp | 19 ++++----- src/corelib/text/qbytearray.cpp | 7 ++-- src/corelib/text/qbytearrayview.qdoc | 15 +++---- src/corelib/text/qstring.cpp | 8 ++-- src/corelib/text/qstringview.cpp | 12 +++--- src/corelib/text/qutf8stringview.qdoc | 18 ++++----- src/corelib/thread/qfuture.qdoc | 5 +-- src/corelib/thread/qrunnable.cpp | 6 +-- src/corelib/thread/qthreadpool.cpp | 18 ++++----- src/corelib/tools/qlist.qdoc | 14 +++---- src/corelib/tools/qsharedpointer.cpp | 6 +-- src/corelib/tools/qspan.qdoc | 28 ++++++------- src/corelib/tools/qvarlengtharray.qdoc | 12 +++--- 21 files changed, 123 insertions(+), 141 deletions(-) diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf index 76de9d9a52e..d8b8bfc464e 100644 --- a/doc/global/macros.qdocconf +++ b/doc/global/macros.qdocconf @@ -147,6 +147,11 @@ macro.youtube.DocBook = "\n" \ "\n" \ "\n" +# +# C++ constrained function templates +# +macro.constraints = "\\section1 Constraints\n\nParticipates in overload resolution only if " + macro.excludefromcreator = "\\meta tag broken" macro.preliminarycmakecommand = "\\note This command is in technology preview and may change in future releases." 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. */ /*! diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp index 95efa006460..541c7d81fdf 100644 --- a/src/corelib/io/qdebug.cpp +++ b/src/corelib/io/qdebug.cpp @@ -992,8 +992,7 @@ QDebug &QDebug::resetFormat() \since 6.9 Prints the Qt or std ordering value \a t to the \a debug object. - \note This function only participates in overload resolution if \c T - is one of ::_ordering. + \constraints \c T is one of ::_ordering. */ /*! diff --git a/src/corelib/kernel/qjniarray.qdoc b/src/corelib/kernel/qjniarray.qdoc index 2d1c2dd2127..41c4e5e9b8f 100644 --- a/src/corelib/kernel/qjniarray.qdoc +++ b/src/corelib/kernel/qjniarray.qdoc @@ -22,7 +22,7 @@ QJniArray instance that wraps it. //! [forward-iterable-containers] - This function only participates in overload resolution if \c{Container} + \constraints \c{Container} is a container that stores elements of a \l{JNI types}{JNI type} or equivalent C++ type, and provides a forward iterator. @@ -275,7 +275,7 @@ Constructs a QJniArray by copying \a other. Both QJniArray objects will reference the same Java array object. - This constructor only participates in overload resolution if the element + \constraints the element type \c{Other} of \a other is convertible to the element type \c{T} of the QJniArray being constructed. However, no actual conversion takes place. */ @@ -286,7 +286,7 @@ Constructs a QJniArray by moving from \a other. The \a other array becomes \l{QJniArrayBase::isValid}{invalid}. - This constructor only participates in overload resolution if the element + \constraints the element type \c{Other} of \a other is convertible to the element type \c{T} of the QJniArray being constructed. However, no actual conversion takes place. */ @@ -297,7 +297,7 @@ Assigns \a other to this QJniArray, and returns a reference to this. Both QJniArray objects will reference the same Java array object. - This operator only participates in overload resolution if the element + \constraints the element type \c{Other} of \a other is convertible to the element type \c{T} of this QJniArray. However, no actual conversion takes place. */ @@ -308,7 +308,7 @@ Moves \a other into this QJniArray, and returns a reference to this. The \a other array becomes \l{QJniArrayBase::isValid}{invalid}. - This operator only participates in overload resolution if the element + \constraints the element type \c{Other} of \a other is convertible to the element type \c{T} of this QJniArray. However, no actual conversion takes place. */ diff --git a/src/corelib/kernel/qmath.qdoc b/src/corelib/kernel/qmath.qdoc index bc365f26fa6..30dfeb06875 100644 --- a/src/corelib/kernel/qmath.qdoc +++ b/src/corelib/kernel/qmath.qdoc @@ -249,8 +249,7 @@ This function converts the \a degrees in double to radians; the angle is casted to a double before the conversion. - This function participates in overload resolution if and only if - \c Integral is an integral type. + \constraints \c Integral is an integral type. \sa qRadiansToDegrees() */ diff --git a/src/corelib/kernel/qpermissions.cpp b/src/corelib/kernel/qpermissions.cpp index ef22861866e..c5062860ea1 100644 --- a/src/corelib/kernel/qpermissions.cpp +++ b/src/corelib/kernel/qpermissions.cpp @@ -243,8 +243,8 @@ Q_LOGGING_CATEGORY(lcPermissions, "qt.permissions", QtWarningMsg); You do not need to construct this type explicitly, as the type is automatically used when checking or requesting permissions. - This constructor participates in overload resolution only if \c T is one of - the \l{typed permission} classes: + \constraints + \c T is one of the \l{typed permission} classes: \annotatedlist permissions */ @@ -257,8 +257,8 @@ Q_LOGGING_CATEGORY(lcPermissions, "qt.permissions", QtWarningMsg); Use type() for dynamically choosing which typed permission to request. - This function participates in overload resolution only if \c T is one of - the \l{typed permission} classes: + \constraints + \c T is one of the \l{typed permission} classes: \annotatedlist permissions */ diff --git a/src/corelib/kernel/qpointer.qdoc b/src/corelib/kernel/qpointer.qdoc index d95de1150cc..0b570cdef84 100644 --- a/src/corelib/kernel/qpointer.qdoc +++ b/src/corelib/kernel/qpointer.qdoc @@ -125,8 +125,7 @@ Conversion assignment operator. Makes this guarded pointer guard the same object guarded by \a other. - \note This operator participates in overload resolution only if \c{X*} - is convertible to \c{T*}. + \constraints \c{X*} is convertible to \c{T*}. */ /*! @@ -136,8 +135,7 @@ Conversion move-assignment operator. Makes this guarded pointer guard the same object guarded by \a other and resets \a other to nullptr. - \note This operator participates in overload resolution only if \c{X*} - is convertible to \c{T*}. + \constraints \c{X*} is convertible to \c{T*}. */ /*! diff --git a/src/corelib/kernel/qvariant.cpp b/src/corelib/kernel/qvariant.cpp index d1b95be0e63..3cf9058a59d 100644 --- a/src/corelib/kernel/qvariant.cpp +++ b/src/corelib/kernel/qvariant.cpp @@ -559,12 +559,11 @@ QVariant::QVariant(const QVariant &p) value is is initialized with the arguments \c{std::forward(args)...}. - This overload only participates in overload resolution if \c T can be - constructed from \a args. - This constructor is provided for STL/std::any compatibility. \overload + + \constraints \c T can be constructed from \a args. */ /*! diff --git a/src/corelib/text/qanystringview.cpp b/src/corelib/text/qanystringview.cpp index ad992fbfc39..da72e5f18d4 100644 --- a/src/corelib/text/qanystringview.cpp +++ b/src/corelib/text/qanystringview.cpp @@ -145,8 +145,7 @@ QT_BEGIN_NAMESPACE The behavior is undefined if \a len is negative or, when positive, if \a str is \nullptr. - This constructor only participates in overload resolution if \c Char is a compatible - character type. + \constraints \c Char is a compatible character type. \sa isNull(), {Compatible Character Types} */ @@ -165,8 +164,7 @@ QT_BEGIN_NAMESPACE The behavior is undefined if \a last precedes \a first, or \a first is \nullptr and \a last is not. - This constructor only participates in overload resolution if \c Char - is a compatible character type. + \constraints \c Char is a compatible character type. \sa isNull(), {Compatible Character Types} */ @@ -181,9 +179,8 @@ QT_BEGIN_NAMESPACE Passing \nullptr as \a str is safe and results in a null string view. - This constructor only participates in overload resolution if \a - str is not an array and if \c Char is a compatible character - type. + \constraints \a str is not an array and \c Char is a + compatible character type. \sa isNull(), {Compatible Character Types} */ @@ -199,7 +196,7 @@ QT_BEGIN_NAMESPACE \a string must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \a + \constraints \a string is an actual array and \c Char is a compatible character type. @@ -233,13 +230,13 @@ QT_BEGIN_NAMESPACE \c{std::data(str)} must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \c Container is a - container with a compatible character type as \c{value_type}. - The string view will be empty if and only if \c{std::size(str) == 0}. It is unspecified whether this constructor can result in a null string view (\c{std::data(str)} would have to return \nullptr for this). + \constraints \c Container is a + container with a compatible character type as \c{value_type}. + \sa isNull(), isEmpty() */ diff --git a/src/corelib/text/qbytearray.cpp b/src/corelib/text/qbytearray.cpp index 1fc8797374e..38aefde18d0 100644 --- a/src/corelib/text/qbytearray.cpp +++ b/src/corelib/text/qbytearray.cpp @@ -2210,12 +2210,11 @@ QByteArray& QByteArray::append(char ch) This function will only allocate memory if the number of elements in the range exceeds the capacity of this byte array or this byte array is shared. - \note This function overload only participates in overload resolution if - \c InputIterator meets the requirements of a - \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. - \note The behavior is undefined if either argument is an iterator into *this or [\a first, \a last) is not a valid range. + + \constraints \c InputIterator meets the requirements of a + \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. */ QByteArray &QByteArray::assign(QByteArrayView v) diff --git a/src/corelib/text/qbytearrayview.qdoc b/src/corelib/text/qbytearrayview.qdoc index 7d9a455b9fd..108fa0cd59a 100644 --- a/src/corelib/text/qbytearrayview.qdoc +++ b/src/corelib/text/qbytearrayview.qdoc @@ -204,8 +204,7 @@ The behavior is undefined if \a len is negative or, when positive, if \a data is \nullptr. - This constructor only participates in overload resolution if \c Byte is a compatible - byte type. + \constraints \c Byte is a compatible byte type. \sa {Compatible Byte Types} */ @@ -224,8 +223,7 @@ The behavior is undefined if \a last precedes \a first, or \a first is \nullptr and \a last is not. - This constructor only participates in overload resolution if \c Byte is - a compatible byte type. + \constraints \c Byte is a compatible byte type. \sa {Compatible Byte Types} */ @@ -240,8 +238,8 @@ Passing \nullptr as \a data is safe and results in a null byte array view. - This constructor only participates in overload resolution if \a data is not - an array and if \c Byte is a compatible byte type. + \constraints \a data is not an array and \c Byte is a + compatible byte type. \sa {Compatible Byte Types} */ @@ -255,8 +253,7 @@ \a data must remain valid for the lifetime of this byte array view object. - This constructor only participates in overload resolution if \c Byte is a - compatible byte type. + \constraints \c Byte is a compatible byte type. \sa {Compatible Byte Types} */ @@ -304,7 +301,7 @@ The container's data must remain valid for the lifetime of this byte array view object. - This constructor participates in overload resolution if \a c is any contiguous + \constraints \a c is any contiguous container with elements of a compatible byte type. \sa {Compatible Byte Types} diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp index 311418781f8..fe8781bc003 100644 --- a/src/corelib/text/qstring.cpp +++ b/src/corelib/text/qstring.cpp @@ -3376,7 +3376,10 @@ QString &QString::append(QChar ch) resulting string, exceeds the capacity of this string, or if this string is shared. - \note This function overload only participates in overload resolution if + \note The behavior is undefined if either argument is an iterator into *this or + [\a first, \a last) is not a valid range. + + \constraints \c InputIterator meets the requirements of a \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator} and the \c{value_type} of \c InputIterator is one of the following character types: @@ -3391,9 +3394,6 @@ QString &QString::append(QChar ch) \li (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t \li \c char32_t \endlist - - \note The behavior is undefined if either argument is an iterator into *this or - [\a first, \a last) is not a valid range. */ QString &QString::assign(QAnyStringView s) diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index 64d4ffc1f1d..7c37c890719 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -196,7 +196,7 @@ QT_BEGIN_NAMESPACE The behavior is undefined if \a len is negative or, when positive, if \a str is \nullptr. //! [compatible-char-types] - This constructor only participates in overload resolution if \c Char is a compatible + \constraints \c Char is a compatible character type. The compatible character types are: \c QChar, \c ushort, \c char16_t and (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t. //! [compatible-char-types] @@ -265,15 +265,15 @@ QT_BEGIN_NAMESPACE \c{std::data(str)} must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \c Container is a - container with a compatible character type as \c{value_type}. The - compatible character types are: \c QChar, \c ushort, \c char16_t and - (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t. - The string view will be empty if and only if \c{std::size(str) == 0}. It is unspecified whether this constructor can result in a null string view (\c{std::data(str)} would have to return \nullptr for this). + \constraints \c Container is a + container with a compatible character type as \c{value_type}. The + compatible character types are: \c QChar, \c ushort, \c char16_t and + (on platforms, such as Windows, where it is a 16-bit type) \c wchar_t. + \sa isNull(), isEmpty() */ diff --git a/src/corelib/text/qutf8stringview.qdoc b/src/corelib/text/qutf8stringview.qdoc index eba8f72fc15..8bd1c20fc05 100644 --- a/src/corelib/text/qutf8stringview.qdoc +++ b/src/corelib/text/qutf8stringview.qdoc @@ -235,7 +235,7 @@ The behavior is undefined if \a len is negative or, when positive, if \a str is \nullptr. - This constructor only participates in overload resolution if \c Char is a compatible + \constraints \c Char is a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. */ @@ -254,7 +254,7 @@ The behavior is undefined if \a last precedes \a first, or \a first is \nullptr and \a last is not. - This constructor only participates in overload resolution if \c Char is a compatible + \constraints \c Char is a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. */ @@ -269,7 +269,7 @@ Passing \nullptr as \a str is safe and results in a null string view. - This constructor only participates in overload resolution if \a str + \constraints \a str is not an array and if \c Char is a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. @@ -286,7 +286,7 @@ \a string must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \a string + \constraints \a string is an actual array and if \c Char is a compatible character type. The compatible character types are: \c char8_t, \c char, \c{signed char} and \c{unsigned char}. @@ -301,15 +301,15 @@ \c{std::data(str)} must remain valid for the lifetime of this string view object. - This constructor only participates in overload resolution if \c Container is a - container with a compatible character type as \c{value_type}. The - compatible character types are: \c char8_t, \c char, \c{signed char} and - \c{unsigned char}. - The string view will be empty if and only if \c{std::size(str) == 0}. It is unspecified whether this constructor can result in a null string view (\c{std::data(str)} would have to return \nullptr for this). + \constraints \c Container is a + container with a compatible character type as \c{value_type}. The + compatible character types are: \c char8_t, \c char, \c{signed char} and + \c{unsigned char}. + \sa isNull(), isEmpty() */ diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index b278d398821..9faa3d1e49b 100644 --- a/src/corelib/thread/qfuture.qdoc +++ b/src/corelib/thread/qfuture.qdoc @@ -1137,13 +1137,12 @@ results of type \c ContainedType initialized from the values of the \a container. - \note This overload only participates in overload resolution if the - \c Container has input iterators. - \snippet code/src_corelib_thread_qfuture.cpp 32 \dots \snippet code/src_corelib_thread_qfuture.cpp 34 + \constraints the \c Container has input iterators. + \sa QFuture, QtFuture::makeReadyVoidFuture(), QtFuture::makeReadyValueFuture(), QtFuture::makeExceptionalFuture() */ diff --git a/src/corelib/thread/qrunnable.cpp b/src/corelib/thread/qrunnable.cpp index f9d69ed5cbb..a1193007542 100644 --- a/src/corelib/thread/qrunnable.cpp +++ b/src/corelib/thread/qrunnable.cpp @@ -108,11 +108,11 @@ void QRunnable::QGenericRunnable::run() Auto-deletion is enabled by default. - \note This function participates in overload resolution only if \c Callable - is a function or function object which can be called with zero arguments. - \note In Qt versions prior to 6.6, this method took copyable functions only. + \constraints \c Callable + is a function or function object which can be called with zero arguments. + \sa run(), autoDelete() */ diff --git a/src/corelib/thread/qthreadpool.cpp b/src/corelib/thread/qthreadpool.cpp index a975efde607..a0ac3e58759 100644 --- a/src/corelib/thread/qthreadpool.cpp +++ b/src/corelib/thread/qthreadpool.cpp @@ -512,11 +512,11 @@ void QThreadPool::start(QRunnable *runnable, int priority) \a callableToRun is added to a run queue instead. The \a priority argument can be used to control the run queue's order of execution. - \note This function participates in overload resolution only if \c Callable - is a function or function object which can be called with zero arguments. - \note In Qt version prior to 6.6, this function took std::function, and therefore couldn't handle move-only callables. + + \constraints \c Callable + is a function or function object which can be called with zero arguments. */ /*! @@ -558,11 +558,11 @@ bool QThreadPool::tryStart(QRunnable *runnable) does nothing and returns \c false. Otherwise, \a callableToRun is run immediately using one available thread and this function returns \c true. - \note This function participates in overload resolution only if \c Callable - is a function or function object which can be called with zero arguments. - \note In Qt version prior to 6.6, this function took std::function, and therefore couldn't handle move-only callables. + + \constraints \c Callable + is a function or function object which can be called with zero arguments. */ /*! \property QThreadPool::expiryTimeout @@ -820,11 +820,11 @@ void QThreadPool::startOnReservedThread(QRunnable *runnable) Releases a thread previously reserved with reserveThread() and uses it to run \a callableToRun. - \note This function participates in overload resolution only if \c Callable - is a function or function object which can be called with zero arguments. - \note In Qt version prior to 6.6, this function took std::function, and therefore couldn't handle move-only callables. + + \constraints \c Callable + is a function or function object which can be called with zero arguments. */ /*! diff --git a/src/corelib/tools/qlist.qdoc b/src/corelib/tools/qlist.qdoc index 9b540e110c1..b194849203b 100644 --- a/src/corelib/tools/qlist.qdoc +++ b/src/corelib/tools/qlist.qdoc @@ -307,11 +307,11 @@ Constructs a list with the contents in the iterator range [\a first, \a last). - \note This constructor only participates in overload resolution if + The value type of \c InputIterator must be convertible to \c T. + + \constraints \c InputIterator meets the requirements of a \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. - - The value type of \c InputIterator must be convertible to \c T. */ /*! \fn template QList::~QList() @@ -1618,12 +1618,12 @@ This function will only allocate memory if the number of elements in the range exceeds the capacity of this list or this list is shared. - \note This function overload only participates in overload resolution if - \c InputIterator meets the requirements of a - \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. - \note The behavior is undefined if either argument is an iterator into *this. + + \constraints + \c InputIterator meets the requirements of a + \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. */ /*! \fn template QList& QList::assign(std::initializer_list l) diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp index 767b7191a17..ae002b1c141 100644 --- a/src/corelib/tools/qsharedpointer.cpp +++ b/src/corelib/tools/qsharedpointer.cpp @@ -469,8 +469,7 @@ Move-constructs a QSharedPointer instance, making it point at the same object that \a other was pointing to. - This constructor participates in overload resolution only if \c{X*} - implicitly converts to \c{T*}. + \constraints \c{X*} implicitly converts to \c{T*}. \since 5.6 */ @@ -480,8 +479,7 @@ Move-assigns \a other to this QSharedPointer instance. - This assignment operator participates in overload resolution only if \c{X*} - implicitly converts to \c{T*}. + \constraints \c{X*} implicitly converts to \c{T*}. \since 5.6 */ diff --git a/src/corelib/tools/qspan.qdoc b/src/corelib/tools/qspan.qdoc index a2d93cbde68..93f4b83c3a9 100644 --- a/src/corelib/tools/qspan.qdoc +++ b/src/corelib/tools/qspan.qdoc @@ -296,8 +296,7 @@ \c{[first, count)} must be a valid range. - \note This constructor participates in overload resolution only if \c{It} - is \l{span-compatible-iterators}{a compatible iterator}. + \constraints \c{It} is \l{span-compatible-iterators}{a compatible iterator}. */ /*! @@ -308,8 +307,7 @@ \c{[first, last)} must be a valid range. - \note This constructor participates in overload resolution only if \c{It} - is \l{span-compatible-iterators}{a compatible iterator}. + \constraints \c{It} is \l{span-compatible-iterators}{a compatible iterator}. */ /*! @@ -319,14 +317,14 @@ Constructs a QSpan referencing the data in the supplied array \a arr. - \note This constructor participates in overload resolution only if + \note \c{q20::type_identity_t} is a C++17 backport of C++20's + \l{https://en.cppreference.com/w/cpp/types/type_identity}{\c{std::type_identity_t}}. + + \constraints \list \li either \c{N} or \l{extent} are \c{std::dynamic_extent} or otherwise \l{extent} \c{==} \c{N} \li and either \c{S} or \c{const S} are the same as \c{T}. \endlist - - \note \c{q20::type_identity_t} is a C++17 backport of C++20's - \l{https://en.cppreference.com/w/cpp/types/type_identity}{\c{std::type_identity_t}}. */ /*! @@ -334,8 +332,7 @@ Constructs a QSpan referencing the data in the supplied range \a r. - \note This constructor participates in overload resolution only if \c{Range} - is \l{span-compatible-ranges}{a compatible range}. + \constraints \c{Range} is \l{span-compatible-ranges}{a compatible range}. */ /*! @@ -344,7 +341,7 @@ Constructs a QSpan referencing the data in the supplied span \a other. - \note This constructor participates in overload resolution only if + \constraints \list \li either \c{N} or \l{extent} are \c{std::dynamic_extent} or \l{extent} \c{==} \c{N} \li and either \c{S} or \c{const S} are the same as \c{T}. @@ -356,12 +353,12 @@ Constructs a QSpan referencing the data in the supplied initializer list \a il. - \note This constructor participates in overload resolution only if \c{T} is \c{const}-qualified. - \note This constructor is \c{noexcept} only if \c{E} is \c{std::dynamic_extent}. \note If \c{E} is not \c{std::dynamic_extent} and the size of \a il is not \c{E}, the behavior is undefined. + \constraints \c{T} is \c{const}-qualified. + \sa {Const and Mutable Spans} */ @@ -742,11 +739,10 @@ If \c{E} is \c{std::dynamic_extent} then so is \c{E'}. Otherwise, \c{E' = E * sizeof(T)}. - \note This function participates in overload resolution only if - \c{!std::is_const_v}. - \note \c{q20::dynamic_extent} is a C++17 backport of C++20's \l{https://en.cppreference.com/w/cpp/container/span/dynamic_extent}{\c{std::dynamic_extent}}. + \constraints \c{!std::is_const_v}. + \sa as_bytes(), size_bytes(), {Const and Mutable Spans} */ diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc index 85d957b5bb7..3beb623ac56 100644 --- a/src/corelib/tools/qvarlengtharray.qdoc +++ b/src/corelib/tools/qvarlengtharray.qdoc @@ -105,11 +105,11 @@ Constructs an array with the contents in the iterator range [\a first, \a last). - This constructor only participates in overload resolution if + The value type of \c InputIterator must be convertible to \c T. + + \constraints \c InputIterator meets the requirements of an \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. - - The value type of \c InputIterator must be convertible to \c T. */ @@ -1040,11 +1040,11 @@ range [\a first, \a last). This function will only allocate memory if the number of elements in the range exceeds the capacity of the container. - This function overload only participates in overload resolution if + The behavior is undefined if either argument is an iterator into *this. + + \constraints \c InputIterator meets the requirements of an \l {https://en.cppreference.com/w/cpp/named_req/InputIterator} {LegacyInputIterator}. - - The behavior is undefined if either argument is an iterator into *this. */ /*! \fn template QVarLengthArray& QVarLengthArray::assign(std::initializer_list list)