From 42bc1f9d273a8b2e129683a84f744920ab31fb59 Mon Sep 17 00:00:00 2001
From: Luca Di Sera <luca.disera@qt.io>
Date: Thu, 12 Oct 2023 16:17:52 +0200
Subject: [PATCH] Doc: Add missing return type to
 QPromise::emplaceResult/emplaceResultAt

When QDoc reads an `\fn` command it saves it to a file to parse it with
Clang, with the objective of using the produced AST to perform certain
sanity checks on the documented element.

Generally, `\fn` commands that do not represent correct C++ code are
accepted as long as Clang is still able to build an AST Node that QDoc
can work with, not resulting in any issue in the output documentation.

For example, an `\fn` that doesn't state a return type might be able to
be parsed correctly enough by Clang to produce a sensible Node for the
function that QDoc is interested into.

The documentation for `QPromise::emplaceResult/emplaceResultAt` make
use of this possibility by not stating a return type.

Up to Clang 15 this was not an issue, and a correct-enough AST was
produced when the `\fn` commands for those methods were parsed.

On Clang 16, Clang chokes on the missing return type, being unable to
recognize the function definition and produce an AST that QDoc can work
with.
This has the effect of losing those documented element in the output
documentation.

To avoid the issue, a return type is now added to the relevant `\fn`
commands.

Task-number: QTBUG-111580
Change-Id: I7d41fc52720ff8762bf2cce229969b7250e44754
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 src/corelib/thread/qpromise.qdoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/corelib/thread/qpromise.qdoc b/src/corelib/thread/qpromise.qdoc
index aaef612175..e9c3eb4b7e 100644
--- a/src/corelib/thread/qpromise.qdoc
+++ b/src/corelib/thread/qpromise.qdoc
@@ -106,8 +106,8 @@
 */
 
 /*!
-    \fn template <typename T> template <typename...Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> QPromise<T>::emplaceResultAt(int index, Args&&...args)
-    \fn template <typename T> template <typename...Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> QPromise<T>::emplaceResult(Args&&...args)
+    \fn template <typename T> template <typename...Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise<T>::emplaceResultAt(int index, Args&&...args)
+    \fn template <typename T> template <typename...Args, std::enable_if_t<std::is_constructible_v<T, Args...>, bool> = true> bool QPromise<T>::emplaceResult(Args&&...args)
     \since 6.6
 
     Adds a result constructed from \a args... to the internal result collection