qdoc: Write \target and \keyword elements to index for all node typesHEADdev

Since the introduction of QDocIndexFiles::writeFunctionSection(), QDoc
inadvertently lost the ability to link to custom targets defined within
a \fn topic.

Reintroduce that ability by extracting the relevant logic into a helper
function and calling it also in writeFunctionSection(). This way,
targets and keywords are handled for all node types.

Pick-to: 6.5 6.7
Fixes: QTBUG-125969
Change-Id: Ifce07cf25ceb1250a33150641f04fb2736495004
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

5 files changed, 57 insertions, 48 deletions

diff --git a/src/qdoc/qdoc/src/qdoc/qdocindexfiles.cpp b/src/qdoc/qdoc/src/qdoc/qdocindexfiles.cpp
index db6852c23..74d27ed3c 100644
--- a/src/qdoc/qdoc/src/qdoc/qdocindexfiles.cpp
+++ b/src/qdoc/qdoc/src/qdoc/qdocindexfiles.cpp
@@ -753,6 +753,38 @@ bool QDocIndexFiles::adoptRelatedNode(Aggregate *adoptiveParent, int index)
 }
 
 /*!
+    Write canonicalized versions of \\target and \\keyword identifiers
+    that appear in the documentation of \a node into the index using
+    \a writer, so that they can be used as link targets in external
+    documentation sets.
+*/
+void QDocIndexFiles::writeTargets(QXmlStreamWriter &writer, Node *node)
+{
+    if (node->doc().hasTargets()) {
+        for (const Atom *target : std::as_const(node->doc().targets())) {
+            const QString &title = target->string();
+            const QString &name{Utilities::asAsciiPrintable(title)};
+            writer.writeStartElement("target");
+            writer.writeAttribute("name", node->isExternalPage() ? title : name);
+            if (name != title)
+                writer.writeAttribute("title", title);
+            writer.writeEndElement(); // target
+        }
+    }
+    if (node->doc().hasKeywords()) {
+        for (const Atom *keyword : std::as_const(node->doc().keywords())) {
+            const QString &title = keyword->string();
+            const QString &name{Utilities::asAsciiPrintable(title)};
+            writer.writeStartElement("keyword");
+            writer.writeAttribute("name", name);
+            if (name != title)
+                writer.writeAttribute("title", title);
+            writer.writeEndElement(); // keyword
+        }
+    }
+}
+
+/*!
   Generate the index section with the given \a writer for the \a node
   specified, returning true if an element was written, and returning
   false if an element is not written.
@@ -1073,48 +1105,7 @@ bool QDocIndexFiles::generateIndexSection(QXmlStreamWriter &writer, Node *node,
         break;
     }
 
-    /*
-      For our pages, we canonicalize the target, keyword and content
-      item names so that they can be used by qdoc for other sets of
-      documentation.
-
-      The reason we do this here is that we don't want to ruin
-      externally composed indexes, containing non-qdoc-style target names
-      when reading in indexes.
-
-      targets and keywords are now allowed in any node, not just inner nodes.
-    */
-
-    if (node->doc().hasTargets()) {
-        bool external = false;
-        if (node->isExternalPage())
-            external = true;
-        const auto &targets = node->doc().targets();
-        for (const Atom *target : targets) {
-            const QString &title = target->string();
-            QString name = Utilities::asAsciiPrintable(title);
-            writer.writeStartElement("target");
-            if (!external)
-                writer.writeAttribute("name", name);
-            else
-                writer.writeAttribute("name", title);
-            if (name != title)
-                writer.writeAttribute("title", title);
-            writer.writeEndElement(); // target
-        }
-    }
-    if (node->doc().hasKeywords()) {
-        const auto &keywords = node->doc().keywords();
-        for (const Atom *keyword : keywords) {
-            const QString &title = keyword->string();
-            QString name = Utilities::asAsciiPrintable(title);
-            writer.writeStartElement("keyword");
-            writer.writeAttribute("name", name);
-            if (name != title)
-                writer.writeAttribute("title", title);
-            writer.writeEndElement(); // keyword
-        }
-    }
+    writeTargets(writer, node);
 
     /*
       Some nodes have a table of contents. For these, we close
@@ -1294,6 +1285,8 @@ void QDocIndexFiles::generateFunctionSection(QXmlStreamWriter &writer, FunctionN
         writer.writeEndElement(); // parameter
     }
 
+    writeTargets(writer, fn);
+
     // Append to the section if the callback object was set
     if (post_)
         post_->append(writer, fn);
diff --git a/src/qdoc/qdoc/src/qdoc/qdocindexfiles.h b/src/qdoc/qdoc/src/qdoc/qdocindexfiles.h
index 6148c6cd2..2225aa576 100644
--- a/src/qdoc/qdoc/src/qdoc/qdocindexfiles.h
+++ b/src/qdoc/qdoc/src/qdoc/qdocindexfiles.h
@@ -46,6 +46,7 @@ private:
     void resolveIndex();
     int indexForNode(Node *node);
     bool adoptRelatedNode(Aggregate *adoptiveParent, int index);
+    void writeTargets(QXmlStreamWriter &writer, Node *node);
 
     void generateIndex(const QString &fileName, const QString &url, const QString &title,
                        Generator *g);
diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/html/trailingbackslashes.index b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/html/trailingbackslashes.index
index f9e9c4ff0..be2edeaf0 100644
--- a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/html/trailingbackslashes.index
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/html/trailingbackslashes.index
@@ -3,9 +3,15 @@
 <INDEX url="" title="TrailingBackslashes Reference Documentation" version="" project="TrailingBackslashes">
     <namespace name="" status="active" access="public" module="trailingbackslashes">
         <struct name="Struct" href="struct.html" status="active" access="public" location="trailing_backslashes.h" documented="true" module="TrailingBackslashes">
-            <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()"/>
-            <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()"/>
-            <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()"/>
+            <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()">
+                <keyword name="two-slashes-here" title="two slashes here"/>
+            </function>
+            <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()">
+                <keyword name="two-slashes-again" title="two slashes again"/>
+            </function>
+            <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()">
+                <keyword name="one-slash" title="one slash"/>
+            </function>
         </struct>
         <module name="TrailingBackslashes" href="trailingbackslashes-module.html" status="internal" seen="false" title=""/>
     </namespace>
diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/struct.webxml b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/struct.webxml
index 86f6fcd59..85a7a1f28 100644
--- a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/struct.webxml
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/struct.webxml
@@ -4,6 +4,7 @@
         <struct name="Struct" href="struct.html" status="active" access="public" location="trailing_backslashes.h" documented="true" module="TrailingBackslashes">
             <description/>
             <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()">
+                <keyword name="two-slashes-here" title="two slashes here"/>
                 <description>
                     <see-also>
                         <link raw="one slash" href="struct.html#oneTrailingSlash" type="function">one slash</link>
@@ -11,6 +12,7 @@
                 </description>
             </function>
             <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()">
+                <keyword name="two-slashes-again" title="two slashes again"/>
                 <description>
                     <see-also>
                         <link raw="two slashes here" href="struct.html#MultipleTrailingSlashes" type="function">two slashes here</link>
@@ -18,6 +20,7 @@
                 </description>
             </function>
             <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()">
+                <keyword name="one-slash" title="one slash"/>
                 <description>
                     <see-also>
                         <link raw="two slashes again" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" type="function">two slashes again</link>
diff --git a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/trailingbackslashes.index b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/trailingbackslashes.index
index f9e9c4ff0..be2edeaf0 100644
--- a/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/trailingbackslashes.index
+++ b/src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/trailing_backslashes/expected/webxml/trailingbackslashes.index
@@ -3,9 +3,15 @@
 <INDEX url="" title="TrailingBackslashes Reference Documentation" version="" project="TrailingBackslashes">
     <namespace name="" status="active" access="public" module="trailingbackslashes">
         <struct name="Struct" href="struct.html" status="active" access="public" location="trailing_backslashes.h" documented="true" module="TrailingBackslashes">
-            <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()"/>
-            <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()"/>
-            <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()"/>
+            <function name="MultipleTrailingSlashes" fullname="Struct::MultipleTrailingSlashes" href="struct.html#MultipleTrailingSlashes" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void MultipleTrailingSlashes()">
+                <keyword name="two-slashes-here" title="two slashes here"/>
+            </function>
+            <function name="multipleTrailingSlashesAndRandomWhitespace" fullname="Struct::multipleTrailingSlashesAndRandomWhitespace" href="struct.html#multipleTrailingSlashesAndRandomWhitespace" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void multipleTrailingSlashesAndRandomWhitespace()">
+                <keyword name="two-slashes-again" title="two slashes again"/>
+            </function>
+            <function name="oneTrailingSlash" fullname="Struct::oneTrailingSlash" href="struct.html#oneTrailingSlash" status="active" access="public" location="trailing_backslashes.h" documented="true" meta="plain" type="void" signature="void oneTrailingSlash()">
+                <keyword name="one-slash" title="one slash"/>
+            </function>
         </struct>
         <module name="TrailingBackslashes" href="trailingbackslashes-module.html" status="internal" seen="false" title=""/>
     </namespace>