From 600cf294a2c04f0963c7025c8032fe72cc9cacb8 Mon Sep 17 00:00:00 2001 From: Luca Di Sera Date: Fri, 3 Nov 2023 15:36:22 +0100 Subject: [PATCH] Doc: Fix template information for QFuture members MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When QDoc parses a project, it parses the source code to extract the user-provided documentation and perform sanity checkings based on the code itself on it. When QDoc parses an "\fn" command as part of this process, it tries to understand, based on its intermediate representation built on the information extracted from the code-base, which "documentable element" the "\fn" refers to. When QDoc performs this "matching" process, it takes into consideration only a certain amount of information. For example, no checking is performed over the template declaration of a callable. Due to some upcoming documentation, where two callables are indistinguishable to the current process, as they differ only in their template declaration, QDoc will start to take into consideration the template declaration of a callable when matching. This implies that an "\fn" command should now provide information parity, with regards to template declaration for callables, with the code-base so that QDoc can perform the match correctly. The documentation for some of the members of `QFuture` is not in sync with the intended target template declaration. Hence, add the missing information to the relevant "\fn" commands. Task-number: QTBUG-118080 Change-Id: I142124e02c9264c8c1b82bb8130162ee89c0f3a5 Reviewed-by: Topi Reiniö --- src/corelib/thread/qfuture.qdoc | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index 2535d621ca..2822b96824 100644 --- a/src/corelib/thread/qfuture.qdoc +++ b/src/corelib/thread/qfuture.qdoc @@ -390,7 +390,7 @@ computations), i.e. until isFinished() returns \c true. */ -/*! \fn template T QFuture::result() const +/*! \fn template template> T QFuture::result() const Returns the first result in the future. If the result is not immediately available, this function will block and wait for the result to become @@ -405,7 +405,7 @@ \sa resultAt(), results(), takeResult() */ -/*! \fn template T QFuture::resultAt(int index) const +/*! \fn template template> T QFuture::resultAt(int index) const Returns the result at \a index in the future. If the result is not immediately available, this function will block and wait for the result to @@ -417,7 +417,7 @@ \sa result(), results(), takeResult(), resultCount() */ -/*! \fn template bool QFuture::isResultReadyAt(int index) const +/*! \fn template template> bool QFuture::isResultReadyAt(int index) const Returns \c true if the result at \a index is immediately available; otherwise returns \c false. @@ -428,7 +428,7 @@ \sa resultAt(), resultCount(), takeResult() */ -/*! \fn template QList QFuture::results() const +/*! \fn template template> QList QFuture::results() const Returns all results from the future. If the results are not immediately available, this function will block and wait for them to become available. Note that @@ -444,7 +444,7 @@ */ #if 0 -/*! \fn template std::vector QFuture::takeResults() +/*! \fn template template> std::vector QFuture::takeResults() If isValid() returns \c false, calling this function leads to undefined behavior. takeResults() takes all results from the QFuture object and invalidates it @@ -463,7 +463,7 @@ */ #endif -/*! \fn template std::vector QFuture::takeResult() +/*! \fn template template> std::vector QFuture::takeResult() \since 6.0 @@ -498,7 +498,7 @@ \sa takeResult(), result(), results(), resultAt() */ -/*! \fn template QFuture::const_iterator QFuture::begin() const +/*! \fn template template> QFuture::const_iterator QFuture::begin() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first result in the future. @@ -506,7 +506,7 @@ \sa constBegin(), end() */ -/*! \fn template QFuture::const_iterator QFuture::end() const +/*! \fn template template> QFuture::const_iterator QFuture::end() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary result after the last result in the future. @@ -514,7 +514,7 @@ \sa begin(), constEnd() */ -/*! \fn template QFuture::const_iterator QFuture::constBegin() const +/*! \fn template template> QFuture::const_iterator QFuture::constBegin() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the first result in the future. @@ -522,7 +522,7 @@ \sa begin(), constEnd() */ -/*! \fn template QFuture::const_iterator QFuture::constEnd() const +/*! \fn template template> QFuture::const_iterator QFuture::constEnd() const Returns a const \l{STL-style iterators}{STL-style iterator} pointing to the imaginary result after the last result in the future. @@ -936,7 +936,7 @@ \sa QtFuture::whenAny() */ -/*! \fn template static QFuture> QtFuture::connect(Sender *sender, Signal signal) +/*! \fn template> static QFuture> QtFuture::connect(Sender *sender, Signal signal) Creates and returns a QFuture which will become available when the \a sender emits the \a signal. If the \a signal takes no arguments, a QFuture is returned. If @@ -975,7 +975,7 @@ \sa QFuture, QFuture::then() */ -/*! \fn template static QFuture> QtFuture::makeReadyFuture(T &&value) +/*! \fn template> static QFuture> QtFuture::makeReadyFuture(T &&value) \since 6.1 \overload @@ -1319,7 +1319,7 @@ \sa onFailed(), onCanceled() */ -/*! \fn template template QFuture QFuture::onFailed(Function &&handler) +/*! \fn template template::HasExtraArgs>> QFuture QFuture::onFailed(Function &&handler) \since 6.0 @@ -1362,7 +1362,7 @@ \sa then(), onCanceled() */ -/*! \fn template template QFuture QFuture::onFailed(QObject *context, Function &&handler) +/*! \fn template template::HasExtraArgs>> QFuture QFuture::onFailed(QObject *context, Function &&handler) \since 6.1 \overload @@ -1390,7 +1390,7 @@ \sa then(), onCanceled() */ -/*! \fn template template QFuture QFuture::onCanceled(Function &&handler) +/*! \fn template template>> QFuture QFuture::onCanceled(Function &&handler) \since 6.0 @@ -1435,7 +1435,7 @@ \sa then(), onFailed() */ -/*! \fn template template QFuture QFuture::onCanceled(QObject *context, Function &&handler) +/*! \fn template template>> QFuture QFuture::onCanceled(QObject *context, Function &&handler) \since 6.1 \overload