qdoc: Give documenter more control of linking

This update enables using the module name as the parameter
in square brackets for the \l command. You will use this
when your link goes to the wrong page. e.g. Suppose this
link command went to a page in QtGui instead of the page
where it is meant to go in QtQuick:

\l { mytarget } { the text for my link }

When a link goes to a page in the wrong module, it means
the target exists in more than one module and because qdoc
searches the modules in sequence and stops when it finds a
match, it might match the wrong target. This would be a
collision in the single tree version of qdoc, but now qdoc
builds a separate tree for each module. Since you know
which module you want your link to go to, put the module
name in square brackets as the first parameter, like this:

\l [QtQuick] { mytarget } { the text for my link }

Now qdoc will only search for mytarget in the tree for
the QtQuick module.

The \target command can now be used anywhere. It has not
been tested in all possible locations, but it works in
the places where people have asked why it doesn't work there.

There will be a further update to complete this task for
implementing the other types of parameters that can be in
the square brackets.

Task-number: QTBUG-39221
Change-Id: I2db4fdd0319ff272ec1d2fa9dc396f14599d80f9
Reviewed-by: Martin Smith <martin.smith@digia.com>

1 files changed, 69 insertions, 55 deletions

diff --git a/src/tools/qdoc/qdocdatabase.cpp b/src/tools/qdoc/qdocdatabase.cpp
index 8bf83ca796..8f28e38431 100644
--- a/src/tools/qdoc/qdocdatabase.cpp
+++ b/src/tools/qdoc/qdocdatabase.cpp
@@ -384,7 +384,7 @@ void QDocForest::newPrimaryTree(const QString& module)
   point, but it only makes sense in the primary tree, which is
   searched first. After the primary tree is searched, \a relative
   is set to 0 for searching the index trees. When relative is 0,
-  the root node of the index tree is the starting point.
+  the root nodes of the index trees are the starting points.
  */
 const Node* QDocForest::resolveTarget(const QString& target, const Node* relative)
 {
@@ -395,11 +395,6 @@ const Node* QDocForest::resolveTarget(const QString& target, const Node* relativ
         const Node* n = t->findNode(path, relative, flags);
         if (n)
             return n;
-#if 0
-        n = t->findDocNodeByTitle(target);
-        if (n)
-            return n;
-#endif
         relative = 0;
     }
     return 0;
@@ -1567,67 +1562,86 @@ void QDocDatabase::mergeCollections(CollectionNode* cn)
     }
 }
 
-QT_END_NAMESPACE
-
-#if 0
-    void getAllGroups(CNMM& t);
-    void getAllModules(CNMM& t);
-    void getAllQmlModules(CNMM& t);
 
 /*!
-  For each tree in the forest, get the group map from the tree.
-  Insert each pair from the group map into the collection node
-  multimap \a t.
+  This function is called when the \a{atom} might be a link
+  atom. It handles the optional, square bracket parameters
+  for the link command.
  */
-void QDocForest::getAllGroups(CNMM& t)
+Node* QDocDatabase::findNode(const Atom* atom)
 {
-    foreach (Tree* t, searchOrder()) {
-        const GroupMap& gm = t->groups();
-        if (!gm.isEmpty()) {
-            GroupMap::const_iterator i = gm.begin();
-            while (i != gm.end()) {
-                t.insert(i.key(), i.value());
-                ++i;
-            }
-        }
+    QStringList path(atom->string());
+    if (atom->specifiesDomain()) {
+        return atom->domain()->findNodeByNameAndType(path, atom->goal());
     }
+    qDebug() << "FINDNODE:" << path << atom->goal();
+    return forest_.findNodeByNameAndType(path, atom->goal());
 }
 
-/*!
-  For each tree in the forest, get the module map from the tree.
-  Insert each pair from the module map into the collection node
-  multimap \a t.
- */
-void QDocForest::getAllModules(CNMM& t)
+const DocNode* QDocDatabase::findDocNodeByTitle(const Atom* atom)
 {
-    foreach (Tree* t, searchOrder()) {
-        const ModuleMap& mm = t->modules();
-        if (!mm.isEmpty()) {
-            ModuleMap::const_iterator i = mm.begin();
-            while (i != mm.end()) {
-                t.insert(i.key(), i.value());
-                ++i;
-            }
-        }
-    }
+    return forest_.findDocNodeByTitle(atom->string());
 }
 
 /*!
-  For each tree in the forest, get the QML module map from the
-  tree. Insert each pair from the QML module map into the
-  collection node multimap \a t.
- */
-void QDocForest::getAllQmlModules(CNMM& t)
+  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::findNode(const Atom* atom, const Node* relative, QString& ref)
 {
-    foreach (Tree* t, searchOrder()) {
-        const QmlModuleMap& qmm = t->groups();
-        if (!qmm.isEmpty()) {
-            QmlModuleMap::const_iterator i = qmm.begin();
-            while (i != qmm.end()) {
-                t.insert(i.key(), i.value());
-                ++i;
-            }
+    const Node* node = 0;
+    QStringList path = atom->string().split("#");
+    QString first = path.first().trimmed();
+    path.removeFirst();
+
+    if (first.isEmpty())
+        node = relative; // search for a target on the current page.
+    else if (atom->specifiesDomain()) {
+        qDebug() << "Processing LinkAtom";
+        if (first.endsWith(".html")) { // The target is an html file.
+            node = atom->domain()->findNodeByNameAndType(QStringList(first), Node::Document);
+        }
+        else if (first.endsWith("()")) { // The target is a C++ function or QML method.
+            node = atom->domain()->resolveFunctionTarget(first, 0); //relative);
+        }
+        else {
+            node = atom->domain()->resolveTarget(first, 0); // relative);
+            if (!node)
+                node = atom->domain()->findUnambiguousTarget(first, ref); // ref
+            if (!node && path.isEmpty())
+                node = atom->domain()->findDocNodeByTitle(first);
+        }
+    }
+    else {
+        if (first.endsWith(".html")) { // The target is an html file.
+            node = findNodeByNameAndType(QStringList(first), Node::Document); // ref
+        }
+        else if (first.endsWith("()")) { // The target is a C++ function or QML method.
+            node = resolveFunctionTarget(first, relative);
+        }
+        else {
+            node = resolveTarget(first, relative); // ref
+            if (!node)
+                node = findUnambiguousTarget(first, ref); // ref
+            if (!node && path.isEmpty())
+                node = findDocNodeByTitle(first);
+        }
+    }
+    if (node && ref.isEmpty()) {
+        if (!node->url().isEmpty())
+            return node;
+        if (!path.isEmpty()) {
+            ref = findTarget(path.first(), node);
+            if (ref.isEmpty())
+                node = 0;
         }
     }
+    return node;
 }
-#endif
+
+QT_END_NAMESPACE