qdoc: Stop auto-linking to section titles

The purpose of the auto-linking feature is to link strings in the
text that resemble class or function names to API reference. However,
QDoc did not discriminate between the types of the resolved link
targets. Therefore, writing

  \section1 QString

on a random \page would potentially redirect all autolinks to QString
to that section.

To fix, turn Node::Genus into attributes so we can do bitwise operations
on the genus, and introduce Node::API that includes all API reference
node genera.

Node::API is not assigned to nodes directly, but is used in searches
to match against any API reference nodes.

Task-number: QTBUG-91141
Change-Id: Ic0a22b7105e1278662f5ae7d4132980200638225
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 10268e3e9c5f47db8231f2ac907a46cf9283d365)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

19 files changed, 125 insertions, 25 deletions

diff --git a/src/qdoc/aggregate.cpp b/src/qdoc/aggregate.cpp
index 2dda68365..9fcbf75ae 100644
--- a/src/qdoc/aggregate.cpp
+++ b/src/qdoc/aggregate.cpp
@@ -104,7 +104,7 @@ Node *Aggregate::findChildNode(const QString &name, Node::Genus genus, int findF
     } else {
         const NodeList &nodes = m_nonfunctionMap.values(name);
         for (auto *node : nodes) {
-            if (genus == node->genus()) {
+            if (genus & node->genus()) {
                 if (findFlags & TypesOnly) {
                     if (!node->isTypedef() && !node->isClassNode() && !node->isQmlType()
                         && !node->isQmlBasicType() && !node->isJsType()
@@ -116,7 +116,7 @@ Node *Aggregate::findChildNode(const QString &name, Node::Genus genus, int findF
             }
         }
     }
-    if (genus != Node::DontCare && this->genus() != genus)
+    if (genus != Node::DontCare && !(genus & this->genus()))
         return nullptr;
     return m_functionMap.value(name);
 }
diff --git a/src/qdoc/atom.cpp b/src/qdoc/atom.cpp
index f0a7c63f2..ee788ec2d 100644
--- a/src/qdoc/atom.cpp
+++ b/src/qdoc/atom.cpp
@@ -442,6 +442,10 @@ void LinkAtom::resolveSquareBracketParams()
             genus_ = Node::DOC;
             continue;
         }
+        if (param == "api") {
+            genus_ = Node::API;
+            continue;
+        }
         error_ = squareBracketParams_;
         break;
     }
diff --git a/src/qdoc/docbookgenerator.cpp b/src/qdoc/docbookgenerator.cpp
index f721e0ca1..c04eccd9d 100644
--- a/src/qdoc/docbookgenerator.cpp
+++ b/src/qdoc/docbookgenerator.cpp
@@ -227,13 +227,17 @@ int DocBookGenerator::generateAtom(const Atom *atom, const Node *relative, CodeM
     int idx = 0;
     int skipAhead = 0;
     static bool inPara = false;
+    Node::Genus genus = Node::DontCare;
 
     switch (atom->type()) {
     case Atom::AutoLink:
+        // Allow auto-linking to nodes in API reference
+        genus = Node::API;
+        Q_FALLTHROUGH();
     case Atom::NavAutoLink:
         if (!inLink && !m_inContents && !m_inSectionHeading) {
             const Node *node = nullptr;
-            QString link = getAutoLink(atom, relative, &node);
+            QString link = getAutoLink(atom, relative, &node, genus);
             if (!link.isEmpty() && node && node->status() == Node::Obsolete
                 && relative->parent() != node && !relative->isObsolete()) {
                 link.clear();
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index e80649a95..f9215bcfa 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -299,6 +299,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
 {
     int idx, skipAhead = 0;
     static bool in_para = false;
+    Node::Genus genus = Node::DontCare;
 
     switch (atom->type()) {
     case Atom::AutoLink: {
@@ -307,12 +308,14 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
             out() << protectEnc(atom->string());
             break;
         }
+        // Allow auto-linking to nodes in API reference
+        genus = Node::API;
     }
         Q_FALLTHROUGH();
     case Atom::NavAutoLink:
         if (!m_inLink && !m_inContents && !m_inSectionHeading) {
             const Node *node = nullptr;
-            QString link = getAutoLink(atom, relative, &node);
+            QString link = getAutoLink(atom, relative, &node, genus);
             if (link.isEmpty()) {
                 if (autolinkErrors())
                     relative->doc().location().warning(
diff --git a/src/qdoc/node.h b/src/qdoc/node.h
index ef452202b..d5e241812 100644
--- a/src/qdoc/node.h
+++ b/src/qdoc/node.h
@@ -107,7 +107,14 @@ public:
         LastType
     };
 
-    enum Genus : unsigned char { DontCare, CPP, JS, QML, DOC };
+    enum Genus : unsigned char {
+        DontCare = 0x0,
+        CPP = 0x1,
+        JS = 0x2,
+        QML = 0x4,
+        DOC = 0x8,
+        API = CPP | JS | QML
+        };
 
     enum Status : unsigned char {
         Obsolete,
diff --git a/src/qdoc/qdocdatabase.cpp b/src/qdoc/qdocdatabase.cpp
index 9df6532d7..3b189fad5 100644
--- a/src/qdoc/qdocdatabase.cpp
+++ b/src/qdoc/qdocdatabase.cpp
@@ -1508,15 +1508,16 @@ void QDocDatabase::mergeCollections(CollectionNode *c)
 }
 
 /*!
-  Searches for the node that matches the path in \a atom. The
-  \a relative node is used if the first leg of the path is
-  empty, i.e. if the path begins with a hashtag. The function
-  also sets \a ref if there remains an unused leg in the path
-  after the node is found. The node is returned as well as the
-  \a ref. If the returned node pointer is null, \a ref is not
-  valid.
- */
-const Node *QDocDatabase::findNodeForAtom(const Atom *a, const Node *relative, QString &ref)
+  Searches for the node that matches the path in \a atom and the
+  specified \a genus. The \a relative node is used if the first
+  leg of the path is empty, i.e. if the path begins with '#'.
+  The function also sets \a ref if there remains an unused leg
+  in the path after the node is found. The node is returned as
+  well as the \a ref. If the returned node pointer is null,
+  \a ref is also not valid.
+ */
+const Node *QDocDatabase::findNodeForAtom(const Atom *a, const Node *relative, QString &ref,
+                                          Node::Genus genus)
 {
     const Node *node = nullptr;
 
@@ -1525,7 +1526,6 @@ const Node *QDocDatabase::findNodeForAtom(const Atom *a, const Node *relative, Q
     QString first = targetPath.first().trimmed();
 
     Tree *domain = nullptr;
-    Node::Genus genus = Node::DontCare;
 
     if (atom->isLinkAtom()) {
         domain = atom->domain();
diff --git a/src/qdoc/qdocdatabase.h b/src/qdoc/qdocdatabase.h
index 5d85b9d68..6d11242fc 100644
--- a/src/qdoc/qdocdatabase.h
+++ b/src/qdoc/qdocdatabase.h
@@ -308,9 +308,10 @@ public:
     /*******************************************************************/
 
     /*****************************************************************************
-      This function can handle parameters enclosed in '[' ']' (domanin and genus).
+      This function can handle parameters enclosed in '[' ']' (domain and genus).
     ******************************************************************************/
-    const Node *findNodeForAtom(const Atom *atom, const Node *relative, QString &ref);
+    const Node *findNodeForAtom(const Atom *atom, const Node *relative, QString &ref,
+                                Node::Genus genus = Node::DontCare);
     /*******************************************************************/
 
     /*******************************************************************
diff --git a/src/qdoc/tree.cpp b/src/qdoc/tree.cpp
index 138798d20..9d220d9d7 100644
--- a/src/qdoc/tree.cpp
+++ b/src/qdoc/tree.cpp
@@ -595,7 +595,7 @@ const Node *Tree::matchPathAndTarget(const QStringList &path, int idx, const QSt
         NodeVector nodes;
         static_cast<const Aggregate *>(node)->findChildren(name, nodes);
         for (const auto *node : qAsConst(nodes)) {
-            if (genus != Node::DontCare && node->genus() != genus)
+            if (genus != Node::DontCare && !(genus & node->genus()))
                 continue;
             const Node *t = matchPathAndTarget(path, idx + 1, target, node, flags, genus, ref);
             if (t && !t->isPrivate())
@@ -830,7 +830,7 @@ const Node *Tree::findUnambiguousTarget(const QString &target, Node::Genus genus
         if (it.key() != key)
             break;
         TargetRec *candidate = it.value();
-        if ((genus == Node::DontCare) || (genus == candidate->genus())) {
+        if ((genus == Node::DontCare) || (genus & candidate->genus())) {
             if (!bestTarget || (candidate->priority_ < bestTarget->priority_)) {
                 bestTarget = candidate;
                 bestTargetList.clear();
@@ -854,7 +854,7 @@ const Node *Tree::findUnambiguousTarget(const QString &target, Node::Genus genus
         if (it.key() != key)
             break;
         TargetRec *candidate = it.value();
-        if ((genus == Node::DontCare) || (genus == candidate->genus())) {
+        if ((genus == Node::DontCare) || (genus & candidate->genus())) {
             if (!bestTarget || (candidate->priority_ < bestTarget->priority_)) {
                 bestTarget = candidate;
                 bestTargetList.clear();
@@ -1216,7 +1216,7 @@ const FunctionNode *Tree::findFunctionNode(const QStringList &path, const Parame
     if (relative == nullptr)
         relative = root();
     else if (genus != Node::DontCare) {
-        if (genus != relative->genus())
+        if (!(genus & relative->genus()))
             relative = root();
     }
 
diff --git a/src/qdoc/webxmlgenerator.cpp b/src/qdoc/webxmlgenerator.cpp
index 8befa6642..08e5d06d0 100644
--- a/src/qdoc/webxmlgenerator.cpp
+++ b/src/qdoc/webxmlgenerator.cpp
@@ -301,7 +301,7 @@ const Atom *WebXMLGenerator::addAtomElements(QXmlStreamWriter &writer, const Ato
     case Atom::AutoLink:
         if (!m_inLink && !m_inSectionHeading) {
             const Node *node = nullptr;
-            QString link = getLink(atom, relative, &node);
+            QString link = getAutoLink(atom, relative, &node, Node::API);
             if (node) {
                 startLink(writer, atom, node, link);
                 if (m_inLink) {
diff --git a/src/qdoc/xmlgenerator.cpp b/src/qdoc/xmlgenerator.cpp
index d161e5693..e5d879e5e 100644
--- a/src/qdoc/xmlgenerator.cpp
+++ b/src/qdoc/xmlgenerator.cpp
@@ -405,11 +405,12 @@ QString XmlGenerator::getLink(const Atom *atom, const Node *relative, const Node
   to the node holding the qdoc comment where the link command
   was found.
  */
-QString XmlGenerator::getAutoLink(const Atom *atom, const Node *relative, const Node **node)
+QString XmlGenerator::getAutoLink(const Atom *atom, const Node *relative, const Node **node,
+                                  Node::Genus genus)
 {
     QString ref;
 
-    *node = m_qdb->findNodeForAtom(atom, relative, ref);
+    *node = m_qdb->findNodeForAtom(atom, relative, ref, genus);
     if (!(*node))
         return QString();
 
diff --git a/src/qdoc/xmlgenerator.h b/src/qdoc/xmlgenerator.h
index 0397096c5..a57648412 100644
--- a/src/qdoc/xmlgenerator.h
+++ b/src/qdoc/xmlgenerator.h
@@ -59,7 +59,8 @@ protected:
     QString refForNode(const Node *node);
     QString linkForNode(const Node *node, const Node *relative);
     QString getLink(const Atom *atom, const Node *relative, const Node **node);
-    QString getAutoLink(const Atom *atom, const Node *relative, const Node **node);
+    QString getAutoLink(const Atom *atom, const Node *relative, const Node **node,
+                        Node::Genus = Node::DontCare);
 
     QPair<QString, QString> anchorForNode(const Node *node);
 
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/autolinking.html b/tests/auto/qdoc/generatedoutput/expected_output/autolinking.html
new file mode 100644
index 000000000..a8495eb90
--- /dev/null
+++ b/tests/auto/qdoc/generatedoutput/expected_output/autolinking.html
@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+<!-- classlists.qdoc -->
+  <title>Autolinking | TestCPP</title>
+</head>
+<body>
+<div class="sidebar">
+<div class="toc">
+<h3><a name="toc">Contents</a></h3>
+<ul>
+<li class="level1"><a href="#testqdoc">TestQDoc</a></li>
+</ul>
+</div>
+<div class="sidebar-content" id="sidebar-content"></div></div>
+<h1 class="title">Autolinking</h1>
+<span class="subtitle"></span>
+<!-- $$$autolinking.html-description -->
+<div class="descr"> <a name="details"></a>
+<a name="testqdoc"></a>
+<h2 id="testqdoc">TestQDoc</h2>
+<p>The string <a href="testqdoc.html">TestQDoc</a> links to the C++ namespace unless linking explicitly, <a href="autolinking.html#testqdoc">like this</a>, or <a href="autolinking.html#testqdoc">this</a>. Also,</p>
+<p>Autolinks:</p>
+<ul>
+<li><a href="testqdoc-testderived.html">TestQDoc::TestDerived</a></li>
+</ul>
+<p>Explicit links:</p>
+<ul>
+<li><a href="testqdoc-testderived.html">TestQDoc::TestDerived</a></li>
+<li><a href="obsolete-classes.html#testqdoc">Obsolete Classes#TestQDoc</a></li>
+</ul>
+</div>
+<!-- @@@autolinking.html -->
+</body>
+</html>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp b/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp
index 8484915eb..c83440461 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp
+++ b/tests/auto/qdoc/generatedoutput/expected_output/dontdocument/dontdocument.qhp
@@ -20,6 +20,7 @@
             </section>
         </toc>
         <keywords>
+            <keyword name="Autolinking" id="Autolinking" ref="autolinking.html"/>
             <keyword name="Classes" id="Classes" ref="classes.html"/>
             <keyword name="Obsolete Classes" id="Obsolete Classes" ref="obsolete-classes.html"/>
             <keyword name="QDOCTEST_MACRO" id="QDOCTEST_MACRO" ref="testqdoc.html#QDOCTEST_MACRO"/>
@@ -47,6 +48,7 @@
             <keyword name="virtualFun" id="TestDerived::virtualFun" ref="testqdoc-testderived.html#virtualFun"/>
         </keywords>
         <files>
+            <file>autolinking.html</file>
             <file>classes.html</file>
             <file>obsolete-classes.html</file>
             <file>seenclass.html</file>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/obsolete-classes.html b/tests/auto/qdoc/generatedoutput/expected_output/obsolete-classes.html
index 93a35078b..e8e4c4e3a 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/obsolete-classes.html
+++ b/tests/auto/qdoc/generatedoutput/expected_output/obsolete-classes.html
@@ -11,6 +11,7 @@
 <h3><a name="toc">Contents</a></h3>
 <ul>
 <li class="level1"><a href="#classes-with-obsolete-members">Classes with obsolete members</a></li>
+<li class="level2"><a href="#testqdoc">TestQDoc</a></li>
 </ul>
 </div>
 <div class="sidebar-content" id="sidebar-content"></div></div>
@@ -26,6 +27,8 @@
 <dd><a href="..//testqdoc-testderived-obsolete.html">TestDerived</a> (<a href="testqdoc.html">TestQDoc</a>)</dd>
 </dl>
 </div>
+<a name="testqdoc"></a>
+<h3 id="testqdoc">TestQDoc</h3>
 </div>
 <!-- @@@obsolete-classes.html -->
 </body>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index b/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index
index b08864064..dd2b42463 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index
+++ b/tests/auto/qdoc/generatedoutput/expected_output/properties/testcpp.index
@@ -6,8 +6,12 @@
         <function name="QDOCTEST_MACRO2" href="testqdoc-test.html#QDOCTEST_MACRO2" status="active" access="public" documented="true" related="1" since="Test 1.1" meta="macrowithparams" virtual="non" const="false" static="false" final="false" override="false" type="" brief="A macro with argument x" signature="QDOCTEST_MACRO2(int &amp;x)" groups="testgroup">
             <parameter type="int &amp;" name="x" default=""/>
         </function>
+        <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="" module="TestCPP">
+            <contents name="testqdoc" title="TestQDoc" level="1"/>
+        </page>
         <page name="obsolete-classes.html" href="obsolete-classes.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Obsolete Classes" fulltitle="Obsolete Classes" subtitle="" module="TestCPP">
             <contents name="classes-with-obsolete-members" title="Classes with obsolete members" level="1"/>
+            <contents name="testqdoc" title="TestQDoc" level="2"/>
         </page>
         <page name="https://wiki.qt.io/QProperty" href="https://wiki.qt.io/QProperty" status="active" location="properties.qdoc" documented="true" subtype="externalpage" title="QProperty" fulltitle="QProperty" subtitle=""/>
         <namespace name="TestQDoc" href="testqdoc.html" status="active" access="public" location="testcpp.h" documented="true" module="TestCPP" brief="A namespace">
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/test.qhp b/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
index 40e35b27a..4fffda513 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
+++ b/tests/auto/qdoc/generatedoutput/expected_output/test.qhp
@@ -8,6 +8,7 @@
             <section ref="uicomponents-qmlmodule.html" title="UI Components">
                 <section ref="uicomponents-qmlmodule.html" title="Test">
                     <section ref="qdoc-test-qmlmodule.html" title=""/>
+                    <section ref="autolinking.html" title="Autolinking"/>
                     <section ref="test-cmaketest-example.html" title="CMake Example Project"/>
                     <section ref="test-demos-demo-example.html" title="Demo"/>
                     <section ref="test-demos-hidden-example.html" title="Hidden Demo"/>
@@ -61,6 +62,7 @@
         <keywords>
             <keyword name="AbstractParent" id="QML.AbstractParent" ref="qml-qdoc-test-abstractparent.html"/>
             <keyword name="AbstractParent" id="QML.QDoc.Test1.AbstractParent" ref="qml-qdoc-test-abstractparent.html"/>
+            <keyword name="Autolinking" id="Autolinking" ref="autolinking.html"/>
             <keyword name="Child" id="QML.Child" ref="qml-qdoc-test-child.html"/>
             <keyword name="Child" id="QML.QDoc.Test1.Child" ref="qml-qdoc-test-child.html"/>
             <keyword name="DocTest" id="QML.DocTest" ref="qml-qdoc-test-doctest.html"/>
@@ -140,6 +142,7 @@
             <keyword name="virtualFun" id="TestDerived::virtualFun" ref="testqdoc-testderived.html#virtualFun"/>
         </keywords>
         <files>
+            <file>autolinking.html</file>
             <file>images/leonardo-da-vinci.png</file>
             <file>obsolete-classes.html</file>
             <file>qdoc-test-qmlmodule.html</file>
diff --git a/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index b/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index
index d0b2309b4..9f17e95d0 100644
--- a/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index
+++ b/tests/auto/qdoc/generatedoutput/expected_output/testcpp.index
@@ -6,8 +6,12 @@
         <function name="QDOCTEST_MACRO2" href="testqdoc-test.html#QDOCTEST_MACRO2" status="active" access="public" documented="true" related="1" since="Test 1.1" meta="macrowithparams" virtual="non" const="false" static="false" final="false" override="false" type="" brief="A macro with argument x" signature="QDOCTEST_MACRO2(int &amp;x)" groups="testgroup">
             <parameter type="int &amp;" name="x" default=""/>
         </function>
+        <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="" module="TestCPP">
+            <contents name="testqdoc" title="TestQDoc" level="1"/>
+        </page>
         <page name="obsolete-classes.html" href="obsolete-classes.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Obsolete Classes" fulltitle="Obsolete Classes" subtitle="" module="TestCPP">
             <contents name="classes-with-obsolete-members" title="Classes with obsolete members" level="1"/>
+            <contents name="testqdoc" title="TestQDoc" level="2"/>
         </page>
         <namespace name="TestQDoc" href="testqdoc.html" status="active" access="public" location="testcpp.h" documented="true" module="TestCPP" brief="A namespace">
             <contents name="usage" title="Usage" level="1"/>
diff --git a/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc b/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc
index 7e57b57ee..188676c05 100644
--- a/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc
+++ b/tests/auto/qdoc/generatedoutput/testdata/testcpp/classlists.qdoc
@@ -32,4 +32,30 @@
 
     \section1 Classes with obsolete members
     \generatelist obsoletecppmembers
+
+    \section2 TestQDoc
+*/
+
+/*!
+    \page autolinking.html
+    \title Autolinking
+
+    //! a section title that qualifies for autolinking
+    \section1 TestQDoc
+
+    The string TestQDoc links to the C++ namespace unless linking explicitly,
+    \l {#TestQDoc}{like this}, or \l {TestQDoc}{this}. Also,
+
+    Autolinks:
+
+    \list
+        \li TestQDoc::TestDerived
+    \endlist
+
+    Explicit links:
+
+    \list
+        \li \l [CPP] {TestQDoc::TestDerived}
+        \li \l {Obsolete Classes#TestQDoc}
+    \endlist
 */
diff --git a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
index 515b816d4..31885fec2 100644
--- a/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
+++ b/tests/auto/qdoc/generatedoutput/tst_generatedoutput.cpp
@@ -240,6 +240,7 @@ void tst_generatedOutput::htmlFromCpp()
                    "testqdoc-testderived-members.html "
                    "testqdoc-testderived-obsolete.html "
                    "obsolete-classes.html "
+                   "autolinking.html "
                    "testqdoc.html");
 }