qdoc: Allow tying a \keyword and a \target to a section title

Previously, a \keyword could only be used to create a link target to
the topic it appears in. Adding a link target to a specific location
within the topic (e.g. a \page) was only possible with the \target
command; however, a \target does not add a keyword entry to the
Qt Help project (.qhp) file like a \keyword does.

Enable tying a \keyword to a \section1..4 title within a documentation
comment. If a \keyword appears directly before a \section command, the
section's href is adopted by the keyword and recorded into the .qhp.
This way, it's possible to have keyword in the Assistant's or Qt Creator
Help's index that refer to a section. These indexed sections are also
available for the context help.

Likewise, these changes alter the behavior of the \target command to be
slightly cleaner:

  \target hola
  \section1 Hello

Will make \l {hola} link to the anchor generated for the section,
instead of a (somewhat arbitrary) location just above the section.

Add a new value `ContentsKeyword` to TargetRec::TargetType enum to
facilitate this. As a drive-by, add internal documentation for all
TargetType enum values to clarify their roles.

Fixes: QTBUG-128573
Change-Id: Ifacdfab174f1aad7fcb7420416e7b56c461ea04e
Reviewed-by: Paul Wicking <[email protected]>
(cherry picked from commit 9e94ec6)
Reviewed-by: Qt Cherry-pick Bot <[email protected]>

Author: toreinio

src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc

@@ -1771,14 +1771,21 @@
     and the location to generated indices.
 
     The \\keyword command is like the \l {target-command} {\\target}
-    command, except when linking to keyword the link goes to the top of
-    the QDoc comment where the \\keyword appears in. If you want to
-    create a link target to a \c section unit within a \\page, use
-    \\target instead.
-
-    Keywords are also registered in indices of generated offline
-    documentation files (.qch). This allows users to look up the location
-    by keyword, for instance, in
+    command, except that when linking to a keyword, by default the link
+    goes to the top of the QDoc comment (topic) the \\keyword appears in.
+
+    If you want to create a keyword for a \c section unit within a
+    topic, add the \\keyword directly above the section title:
+
+    \badcode
+    \keyword debug
+    \section1 Debug command line option (--debug)
+    ...
+    \endcode
+
+    Unlike \\target, keywords are registered in indices of generated
+    offline documentation files (.qch). This allows users to look up the
+    location by keyword, for instance, in
     \l[QtAssistant]{Searching for Keywords}{Qt Assistant's Index Search},
     and makes the keyword accessible in \QC's context help.
 

src/qdoc/qdoc/src/qdoc/helpprojectwriter.cpp

@@ -253,8 +253,15 @@ bool HelpProjectWriter::generateSection(HelpProject &project, QXmlStreamWriter &
     auto appendDocKeywords = [&](const Node *n) {
         for (const auto *kw : n->doc().keywords()) {
                 if (!kw->string().isEmpty()) {
+                    QStringList ref_parts = m_gen->fullDocumentLocation(n).split('#'_L1);
+                    // Use keyword's custom anchor if it has one
+                    if (kw->count() > 1) {
+                        if (ref_parts.count() > 1)
+                            ref_parts.pop_back();
+                        ref_parts << kw->string(1);
+                    }
                     project.m_keywords.append(Keyword(kw->string(), kw->string(),
-                            m_gen->fullDocumentLocation(n)));
+                            ref_parts.join('#'_L1)));
                 }
             }
     };

src/qdoc/qdoc/src/qdoc/tree.cpp

@@ -34,6 +34,28 @@ QT_BEGIN_NAMESPACE
   is being generated.
  */
 
+/*!
+  \class TargetRec
+  \brief A record of a linkable target within the documentation.
+*/
+
+/*!
+    \enum TargetRec::TargetType
+
+    A type of a linkable target record.
+
+    \value Unknown
+           Unknown/target not set.
+    \value Target
+           A location marked with a \\target command.
+    \value Keyword
+           A location marked with a \\keyword command.
+    \value Contents
+           A table of contents item (section title).
+    \value ContentsKeyword
+           A \\keyword tied to a section title.
+*/
+
 /*!
   Constructs a Tree. \a qdb is the pointer to the singleton
   qdoc database that is constructing the tree. This might not
@@ -788,6 +810,18 @@ void Tree::addTargetsToTargetMap(Node *node) {
     }
 }
 
+/*
+    If atom \a a is immediately followed by a
+    section title (\section1..\section4 command),
+    returns the SectionLeft atom; otherwise nullptr.
+*/
+static const Atom *nextSection(const Atom *a)
+{
+    while (a && a->next(Atom::SectionRight))
+        a = a->next(); // skip closing section atoms
+    return a ? a->next(Atom::SectionLeft) : nullptr;
+}
+
 /*!
     \internal
 
@@ -801,9 +835,11 @@ void Tree::addKeywordsToTargetMaps(Node *node) {
         QString ref = refForAtom(i);
         QString title = i->string();
         if (!ref.isEmpty() && !title.isEmpty()) {
-            auto *target = new TargetRec(ref, TargetRec::Keyword, node, 1);
+            auto *target = new TargetRec(ref, nextSection(i) ? TargetRec::ContentsKeyword : TargetRec::Keyword, node, 1);
             m_nodesByTargetRef.insert(Utilities::asAsciiPrintable(title), target);
             m_nodesByTargetTitle.insert(title, target);
+            if (!target->isEmpty())
+                i->append(target->m_ref);
         }
     }
 }
@@ -948,6 +984,9 @@ const PageNode *Tree::findPageNodeByTitle(const QString &title) const
 /*!
   Returns a canonical title for the \a atom, if the \a atom
   is a SectionLeft, SectionHeadingLeft, Keyword, or Target.
+
+  If a target or a keyword is immediately followed by a
+  section, the former adopts the title (ref) of the latter.
  */
 QString Tree::refForAtom(const Atom *atom)
 {
@@ -964,6 +1003,8 @@ QString Tree::refForAtom(const Atom *atom)
     case Atom::Target:
         [[fallthrough]];
     case Atom::Keyword:
+        if (const auto *section = nextSection(atom))
+            return refForAtom(section);
         return Utilities::asAsciiPrintable(atom->string());
     default:
         return {};

src/qdoc/qdoc/src/qdoc/tree.h

@@ -24,10 +24,13 @@ class QDocDatabase;
 struct TargetRec
 {
 public:
-    enum TargetType { Unknown, Target, Keyword, Contents };
+    enum TargetType { Unknown, Target, Keyword, Contents, ContentsKeyword };
 
     TargetRec(QString name, TargetRec::TargetType type, Node *node, int priority)
-        : m_node(node), m_ref(std::move(name)), m_type(type), m_priority(priority)
+        : m_node(node),
+          m_ref(std::move(name)),
+          m_type(type == ContentsKeyword ? Keyword : type),
+          m_priority(priority)
     {
         // Discard the dedicated ref for keywords - they always
         // link to the top of the QDoc comment they appear in

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/docbook/autolinking.xml

@@ -29,4 +29,7 @@
 <db:section xml:id="someprop">
 <db:title>someProp</db:title>
 </db:section>
+<db:section xml:id="indexedkeyword-property">
+<db:title>indexedKeyword property</db:title>
+</db:section>
 </db:article>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/autolinking.html

@@ -12,6 +12,7 @@ <h3 id="toc">Contents</h3>
 <ul>
 <li class="level1"><a href="#testqdoc">TestQDoc</a></li>
 <li class="level1"><a href="#someprop">someProp</a></li>
+<li class="level1"><a href="#indexedkeyword-property">indexedKeyword property</a></li>
 </ul>
 </div>
 <div class="sidebar-content" id="sidebar-content"></div></div>
@@ -30,6 +31,7 @@ <h2 id="testqdoc">TestQDoc</h2>
 <li><a href="obsolete-classes.html#testqdoc">Obsolete Classes#TestQDoc</a></li>
 </ul>
 <h2 id="someprop">someProp</h2>
+<h2 id="indexedkeyword-property">indexedKeyword property</h2>
 </div>
 <!-- @@@autolinking.html -->
 </body>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/test.index

@@ -20,8 +20,10 @@
             <qmlproperty name="name" fullname="QDoc.Test.AbstractParent.name" status="active" access="public" location="parent.qdoc" documented="true" type="string" attached="false" writable="true" brief="Name of this parent"/>
         </qmlclass>
         <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="">
+            <keyword name="indexedkeyword" title="indexedKeyword"/>
             <contents name="testqdoc" title="TestQDoc" level="1"/>
             <contents name="someprop" title="someProp" level="1"/>
+            <contents name="indexedkeyword-property" title="indexedKeyword property" level="1"/>
         </page>
         <page name="cmaketest" href="test-cmaketest-example.html" status="active" location="cmaketest.qdoc" documented="true" subtype="example" title="CMake Example Project" fulltitle="CMake Example Project" subtitle="">
             <page name="cmaketest/main.cpp" href="test-cmaketest-main-cpp.html" status="active" subtype="file" title="" fulltitle="main.cpp Example File" subtitle="cmaketest/main.cpp"/>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/html/test.qhp

@@ -150,6 +150,7 @@
             <keyword name="group.third" id="Type::group.third" ref="qml-qdoc-test-type.html#group.third-prop"/>
             <keyword name="id" id="Type::id" ref="qml-qdoc-test-type.html#id-prop"/>
             <keyword name="id" id="TestDerived::id" ref="testqdoc-testderived.html#id"/>
+            <keyword name="indexedKeyword" id="indexedKeyword" ref="autolinking.html#indexedkeyword-property"/>
             <keyword name="inlineFunction" id="Test::inlineFunction" ref="testqdoc-test.html#inlineFunction"/>
             <keyword name="int" id="QML.int" ref="qml-int.html"/>
             <keyword name="int" id="QML.QDoc.Test1.int" ref="qml-int.html"/>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/webxml/autolinking.webxml

@@ -2,8 +2,10 @@
 <WebXML>
     <document>
         <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="">
+            <keyword name="indexedkeyword" title="indexedKeyword"/>
             <contents name="testqdoc" title="TestQDoc" level="1"/>
             <contents name="someprop" title="someProp" level="1"/>
+            <contents name="indexedkeyword-property" title="indexedKeyword property" level="1"/>
             <description>
                 <section id="testqdoc">
                     <heading level="1">TestQDoc</heading>
@@ -30,6 +32,9 @@
                 <section id="someprop">
                     <heading level="1">someProp</heading>
                 </section>
+                <section id="indexedkeyword-property">
+                    <heading level="1">indexedKeyword property</heading>
+                </section>
             </description>
         </page>
     </document>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/expected/webxml/test.index

@@ -20,8 +20,10 @@
             <qmlproperty name="name" fullname="QDoc.Test.AbstractParent.name" status="active" access="public" location="parent.qdoc" documented="true" type="string" attached="false" writable="true" brief="Name of this parent"/>
         </qmlclass>
         <page name="autolinking.html" href="autolinking.html" status="active" location="classlists.qdoc" documented="true" subtype="page" title="Autolinking" fulltitle="Autolinking" subtitle="">
+            <keyword name="indexedkeyword" title="indexedKeyword"/>
             <contents name="testqdoc" title="TestQDoc" level="1"/>
             <contents name="someprop" title="someProp" level="1"/>
+            <contents name="indexedkeyword-property" title="indexedKeyword property" level="1"/>
         </page>
         <page name="cmaketest" href="test-cmaketest-example.html" status="active" location="cmaketest.qdoc" documented="true" subtype="example" title="CMake Example Project" fulltitle="CMake Example Project" subtitle=""/>
         <qmlclass name="Child" qml-module-name="QDoc.Test" qml-base-type="QDoc.Test::AbstractParent" fullname="QDoc.Test.Child" href="qml-qdoc-test-child.html" status="active" access="public" location="parent.qdoc" since="1.1" documented="true" title="Child" fulltitle="Child" subtitle="" brief="A Child inheriting its parent">

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/comprehensiveproject/src/classlists.qdoc

@@ -37,6 +37,11 @@
 
     //! a section title shadowing a known property name
     \section1 someProp
+
+    //! A section title tied to a keyword; the keyword entry
+    //! in the qhp uses the ref of the section title
+    \keyword indexedKeyword
+    \section1 indexedKeyword property
 */
 
 /*!

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/outputfromqdocfiles/expected/docbook/qdoctests-qdocfileoutput.xml

@@ -59,7 +59,7 @@
 <db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml#link-targets">Linking to a section title</db:link></db:para>
 </db:listitem>
 <db:listitem>
-<db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml#link-test-target">Linking using a \target string</db:link></db:para>
+<db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml#link-targets">Linking using a \target string</db:link></db:para>
 </db:listitem>
 <db:listitem>
 <db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml">Linking using a \keyword string</db:link></db:para>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/outputfromqdocfiles/expected/html/qdoctests-qdocfileoutput.html

@@ -48,7 +48,7 @@ <h2 id="linking">Linking</h2>
 <ul>
 <li><a href="qdoctests-qdocfileoutput-linking.html">Linking to a page title</a></li>
 <li><a href="qdoctests-qdocfileoutput-linking.html#link-targets">Linking to a section title</a></li>
-<li><a href="qdoctests-qdocfileoutput-linking.html#link-test-target">Linking using a \target string</a></li>
+<li><a href="qdoctests-qdocfileoutput-linking.html#link-targets">Linking using a \target string</a></li>
 <li><a href="qdoctests-qdocfileoutput-linking.html">Linking using a \keyword string</a></li>
 </ul>
 <h2 id="qdoc-linking-test">QDoc Linking Test</h2>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/outputfromqdocfiles/expected/webxml/qdoctests-qdocfileoutput.webxml

@@ -71,7 +71,7 @@
                         </item>
                         <item>
                             <para>
-                                <link raw="link-test-target" href="qdoctests-qdocfileoutput-linking.html#link-test-target" type="page" page="Testing QDoc's link command">Linking using a \target string</link></para>
+                                <link raw="link-test-target" href="qdoctests-qdocfileoutput-linking.html#link-targets" type="page" page="Testing QDoc's link command">Linking using a \target string</link></para>
                         </item>
                         <item>
                             <para>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/tocnavigation/expected/docbook/qdoctests-qdocfileoutput.xml

@@ -59,7 +59,7 @@
 <db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml#link-targets">Linking to a section title</db:link></db:para>
 </db:listitem>
 <db:listitem>
-<db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml#link-test-target">Linking using a \target string</db:link></db:para>
+<db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml#link-targets">Linking using a \target string</db:link></db:para>
 </db:listitem>
 <db:listitem>
 <db:para><db:link xlink:href="qdoctests-qdocfileoutput-linking.xml">Linking using a \keyword string</db:link></db:para>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/tocnavigation/expected/html/qdoctests-qdocfileoutput.html

@@ -50,7 +50,7 @@ <h2 id="linking">Linking</h2>
 <ul>
 <li><a href="qdoctests-qdocfileoutput-linking.html">Linking to a page title</a></li>
 <li><a href="qdoctests-qdocfileoutput-linking.html#link-targets">Linking to a section title</a></li>
-<li><a href="qdoctests-qdocfileoutput-linking.html#link-test-target">Linking using a \target string</a></li>
+<li><a href="qdoctests-qdocfileoutput-linking.html#link-targets">Linking using a \target string</a></li>
 <li><a href="qdoctests-qdocfileoutput-linking.html">Linking using a \keyword string</a></li>
 </ul>
 <h2 id="qdoc-linking-test">QDoc Linking Test</h2>

src/qdoc/qdoc/tests/validateqdocoutputfiles/testdata/tocnavigation/expected/webxml/qdoctests-qdocfileoutput.webxml

@@ -71,7 +71,7 @@
                         </item>
                         <item>
                             <para>
-                                <link raw="link-test-target" href="qdoctests-qdocfileoutput-linking.html#link-test-target" type="page" page="Testing QDoc's link command">Linking using a \target string</link></para>
+                                <link raw="link-test-target" href="qdoctests-qdocfileoutput-linking.html#link-targets" type="page" page="Testing QDoc's link command">Linking using a \target string</link></para>
                         </item>
                         <item>
                             <para>