qdoc: Make \target and \keyword commands link as expected

When resolving targets added for each node, QDoc didn't run the
check recursively; this meant that \target and \keyword commands
did not link when used in documentation nodes that are not direct
children of the root node. There include e.g. documentation for
functions and QML properties/methods.

This commit fixes that issue, and also modifies the behavior of
\keyword slightly: Using a \keyword no longer generates a HTML
anchor reference. Instead, linking to a keyword links directly
to the parent item which defines the \keyword. This produces
cleaner HTML by omitting unnecessary anchors.

Change-Id: I87659642770a5372409ecb09cb576fbad295155e
Task-number: QTBUG-47286
Reviewed-by: Martin Smith <[email protected]>

5 files changed, 23 insertions, 15 deletions

diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
index b4ed391301c..0f9ca463bba 100644
--- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -2092,8 +2092,11 @@
     {sa-command} {\\sa (see also)} commands.
 
     The \\keyword command is like the \l {target-command} {\\target}
-    command, but stronger. A keyword can be linked from anywhere using
-    a simple syntax.
+    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. A keyword can be linked from anywhere using a
+    simple syntax.
 
     Keywords must be unique over all the documents processed during
     the QDoc run. The command uses the rest of the line as its
diff --git a/src/tools/qdoc/helpprojectwriter.cpp b/src/tools/qdoc/helpprojectwriter.cpp
index 0e2ba738699..996cf03f324 100644
--- a/src/tools/qdoc/helpprojectwriter.cpp
+++ b/src/tools/qdoc/helpprojectwriter.cpp
@@ -307,8 +307,7 @@ bool HelpProjectWriter::generateSection(HelpProject &project,
                     QStringList details;
                     details << keyword->string()
                             << keyword->string()
-                            << gen_->fullDocumentLocation(node, false) +
-                        QLatin1Char('#') + Doc::canonicalTitle(keyword->string());
+                            << gen_->fullDocumentLocation(node, false);
                     project.keywords.append(details);
                 }
                 else
@@ -357,8 +356,7 @@ bool HelpProjectWriter::generateSection(HelpProject &project,
                             QStringList details;
                             details << keyword->string()
                                     << keyword->string()
-                                    << gen_->fullDocumentLocation(node, false) +
-                                       QLatin1Char('#') + Doc::canonicalTitle(keyword->string());
+                                    << gen_->fullDocumentLocation(node, false);
                             project.keywords.append(details);
                         }
                         else
@@ -438,8 +436,7 @@ bool HelpProjectWriter::generateSection(HelpProject &project,
                             QStringList details;
                             details << keyword->string()
                                     << keyword->string()
-                                    << gen_->fullDocumentLocation(node, false) +
-                                       QLatin1Char('#') + Doc::canonicalTitle(keyword->string());
+                                    << gen_->fullDocumentLocation(node, false);
                             project.keywords.append(details);
                         } else
                             docNode->doc().location().warning(
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index e345e1745d7..ecccd48a6cc 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -283,12 +283,17 @@ QString HtmlGenerator::format()
  */
 void HtmlGenerator::generateKeywordAnchors(const Node* node)
 {
+    Q_UNUSED(node);
+    // Disabled: keywords always link to the top of the QDoc
+    // comment they appear in, and do not use a dedicated anchor.
+#if 0
     if (!node->doc().isEmpty()) {
         const QList<Atom*>& keywords = node->doc().keywords();
         foreach (Atom* a, keywords) {
             out() << QLatin1String("<a name=\"") << Doc::canonicalTitle(a->string()) << QLatin1String("\"></a>");
         }
     }
+#endif
 }
 
 /*!
@@ -3809,10 +3814,8 @@ QString HtmlGenerator::getAutoLink(const Atom *atom, const Node *relative, const
         link = linkForNode(*node, relative);
         if ((*node)->docSubtype() == Node::Image)
             link = "images/used-in-examples/" + link;
-        if (!ref.isEmpty())
-            link += QLatin1Char('#') + ref;
     }
-    else if (!ref.isEmpty()) {
+    if (!ref.isEmpty()) {
         int hashtag = link.lastIndexOf(QChar('#'));
         if (hashtag != -1)
             link.truncate(hashtag);
diff --git a/src/tools/qdoc/tree.cpp b/src/tools/qdoc/tree.cpp
index 6c21d730c15..e0fd68d2e70 100644
--- a/src/tools/qdoc/tree.cpp
+++ b/src/tools/qdoc/tree.cpp
@@ -995,7 +995,6 @@ void Tree::insertTarget(const QString& name,
  */
 void Tree::resolveTargets(Aggregate* root)
 {
-    // need recursion
     foreach (Node* child, root->childNodes()) {
         if (child->type() == Node::Document) {
             DocumentNode* node = static_cast<DocumentNode*>(child);
@@ -1039,9 +1038,8 @@ void Tree::resolveTargets(Aggregate* root)
                 QString ref = refForAtom(keywords.at(i));
                 QString title = keywords.at(i)->string();
                 if (!ref.isEmpty() && !title.isEmpty()) {
-                    QString key = Doc::canonicalTitle(title);
                     TargetRec* target = new TargetRec(ref, title, TargetRec::Keyword, child, 1);
-                    nodesByTargetRef_.insert(key, target);
+                    nodesByTargetRef_.insert(Doc::canonicalTitle(title), target);
                     nodesByTargetTitle_.insert(title, target);
                 }
             }
@@ -1059,6 +1057,8 @@ void Tree::resolveTargets(Aggregate* root)
                 }
             }
         }
+        if (child->isAggregate())
+            resolveTargets(static_cast<Aggregate*>(child));
     }
 }
 
diff --git a/src/tools/qdoc/tree.h b/src/tools/qdoc/tree.h
index 0f41c221b61..9e195c90ae2 100644
--- a/src/tools/qdoc/tree.h
+++ b/src/tools/qdoc/tree.h
@@ -56,7 +56,12 @@ struct TargetRec
               TargetRec::TargetType type,
               Node* node,
               int priority)
-    : node_(node), ref_(name), title_(title), priority_(priority), type_(type) { }
+    : node_(node), ref_(name), title_(title), priority_(priority), type_(type) {
+        // Discard the dedicated ref for keywords - they always
+        // link to the top of the QDoc comment they appear in
+        if (type == Keyword)
+            ref_.clear();
+    }
 
     bool isEmpty() const { return ref_.isEmpty(); }