QDoc: Store declared type in index file

In certain situations, authors may prefer to use `auto` instead of the
actual type of a function as argument QDoc's `\fn`-command. This makes
QDoc output `auto` instead of the full type, which can be used to hide
certain implementation details. QDoc stores this as `declaredReturnType`
on function nodes.

However, the declared type is not written to index files. This means
that modules that read the index file as a dependency always get the
de-sugared type, despite the author's intentions.

This change extends QDoc's index file by adding a new attribute,
`declaredtype`. If present, the value is now written to and read from
.index-files by QDoc.

The change is cherry-picked back to 6.8, where the declared return type
override feature was added.

Pick-to: 6.8
Fixes: QTBUG-139614
Change-Id: Ie73c3db070943aa91e63d92d3e33e72d9579a7ee
Reviewed-by: Topi Reiniö <[email protected]>
(cherry picked from commit d9a706c)
Reviewed-by: Qt Cherry-pick Bot <[email protected]>
(cherry picked from commit d0f5756)

Author: paulwicking

src/qdoc/qdoc/src/qdoc/qdocindexfiles.cpp

@@ -422,6 +422,10 @@ void QDocIndexFiles::readIndexSection(QXmlStreamReader &reader, Node *current,
 
         fn->setReturnType(attributes.value(QLatin1String("type")).toString());
 
+        const auto &declaredTypeAttr = attributes.value(QLatin1String("declaredtype"));
+        if (!declaredTypeAttr.isEmpty())
+            fn->setDeclaredReturnType(declaredTypeAttr.toString());
+
         if (fn->isCppNode()) {
             fn->setVirtualness(attributes.value(QLatin1String("virtual")).toString());
             fn->setConst(attributes.value(QLatin1String("const")) == QLatin1String("true"));
@@ -1268,6 +1272,10 @@ void QDocIndexFiles::generateFunctionSection(QXmlStreamWriter &writer, FunctionN
     if (!return_type.isEmpty())
         writer.writeAttribute("type", return_type);
 
+    const auto &declared_return_type = fn->declaredReturnType();
+    if (declared_return_type.has_value())
+        writer.writeAttribute("declaredtype", declared_return_type.value());
+
     if (fn->isCppNode()) {
         if (!brief.isEmpty())
             writer.writeAttribute("brief", brief);

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/auto_as_return_type/expected/html/auto-as-return-type.index

@@ -12,15 +12,15 @@
                     <parameter type="int" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                 </function>
-                <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
+                <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" declaredtype="auto" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
                     <parameter type="ThisIsMyReallyLongAndComplicatedTemplateName" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                 </function>
-                <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" brief="Returns the number" signature="int number() const"/>
+                <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" declaredtype="auto" brief="Returns the number" signature="int number() const"/>
                 <function name="setNumber" fullname="QDocTests::Numbers::setNumber" href="qdoctests-numbers.html#setNumber" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="void" brief="Sets the number" signature="void setNumber(int number)">
                     <parameter type="int" name="number" default=""/>
                 </function>
-                <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
+                <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" declaredtype="auto" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
                     <parameter type="int" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                 </function>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/auto_as_return_type/expected/webxml/auto-as-return-type.index

@@ -12,15 +12,15 @@
                     <parameter type="int" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                 </function>
-                <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
+                <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" declaredtype="auto" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
                     <parameter type="ThisIsMyReallyLongAndComplicatedTemplateName" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                 </function>
-                <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" brief="Returns the number" signature="int number() const"/>
+                <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" declaredtype="auto" brief="Returns the number" signature="int number() const"/>
                 <function name="setNumber" fullname="QDocTests::Numbers::setNumber" href="qdoctests-numbers.html#setNumber" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="void" brief="Sets the number" signature="void setNumber(int number)">
                     <parameter type="int" name="number" default=""/>
                 </function>
-                <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
+                <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" declaredtype="auto" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
                     <parameter type="int" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                 </function>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/auto_as_return_type/expected/webxml/qdoctests-numbers.webxml

@@ -21,15 +21,15 @@
                     <para>Returns an integer containing the sum of <argument>a</argument> and <argument>b</argument>.</para>
                 </description>
             </function>
-            <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
+            <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" declaredtype="auto" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
                 <parameter type="ThisIsMyReallyLongAndComplicatedTemplateName" name="a" default=""/>
                 <parameter type="int" name="b" default=""/>
                 <description>
                     <brief>Adds two numbers of the same underlying type.</brief>
                     <para>Returns a value containing the sum of <argument>a</argument> and <argument>b</argument>.</para>
                 </description>
             </function>
-            <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" brief="Returns the number" signature="int number() const">
+            <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" declaredtype="auto" brief="Returns the number" signature="int number() const">
                 <description>
                     <brief>Returns the number.</brief>
                     <para>Returns the number, whatever it may be.</para>
@@ -48,7 +48,7 @@
                     </see-also>
                 </description>
             </function>
-            <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
+            <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" declaredtype="auto" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
                 <parameter type="int" name="a" default=""/>
                 <parameter type="int" name="b" default=""/>
                 <description>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/auto_as_return_type/expected/webxml/qdoctests.webxml

@@ -25,15 +25,15 @@
                         <para>Returns an integer containing the sum of <argument>a</argument> and <argument>b</argument>.</para>
                     </description>
                 </function>
-                <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
+                <function name="adder" fullname="QDocTests::Numbers::adder" href="qdoctests-numbers.html#adder" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="ThisIsMyReallyLongAndComplicatedTemplateName" declaredtype="auto" brief="Adds two numbers of the same underlying type" signature="ThisIsMyReallyLongAndComplicatedTemplateName adder(ThisIsMyReallyLongAndComplicatedTemplateName a, int b)">
                     <parameter type="ThisIsMyReallyLongAndComplicatedTemplateName" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                     <description>
                         <brief>Adds two numbers of the same underlying type.</brief>
                         <para>Returns a value containing the sum of <argument>a</argument> and <argument>b</argument>.</para>
                     </description>
                 </function>
-                <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" brief="Returns the number" signature="int number() const">
+                <function name="number" fullname="QDocTests::Numbers::number" href="qdoctests-numbers.html#number" status="active" access="public" location="numbers.h" documented="true" meta="plain" const="true" type="int" declaredtype="auto" brief="Returns the number" signature="int number() const">
                     <description>
                         <brief>Returns the number.</brief>
                         <para>Returns the number, whatever it may be.</para>
@@ -52,7 +52,7 @@
                         </see-also>
                     </description>
                 </function>
-                <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
+                <function name="subtract" fullname="QDocTests::Numbers::subtract" href="qdoctests-numbers.html#subtract" status="active" access="public" location="numbers.h" documented="true" meta="plain" type="int" declaredtype="auto" brief="Subtracts two numbers" signature="int subtract(int a, int b)">
                     <parameter type="int" name="a" default=""/>
                     <parameter type="int" name="b" default=""/>
                     <description>