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, 18 insertions, 15 deletions

diff --git a/src/tools/qdoc/tree.cpp b/src/tools/qdoc/tree.cpp
index 147abe21af..e689227bf1 100644
--- a/src/tools/qdoc/tree.cpp
+++ b/src/tools/qdoc/tree.cpp
@@ -563,20 +563,6 @@ Node* Tree::findNodeByNameAndType(const QStringList& path, Node::Type type) cons
 {
     return findNodeRecursive(path, 0, root(), type);
 }
-#if 0
-/*!
-  Find the node with the specified \a path name that is of
-  the specified \a type and \a subtype. Begin the search at
-  the \a start node. If the \a start node is 0, begin the
-  search at the tree root. \a subtype is not used unless
-  \a type is \c{Document}.
- */
-Node* Tree::findHtmlFileNode(const QStringList& path) const
-{
-    return findNodeRecursive(path, 0, root());
-}
-#endif
-/* internal members */
 
 /*!
   Recursive search for a node identified by \a path. Each
@@ -624,7 +610,7 @@ Node* Tree::findNodeRecursive(const QStringList& path,
         }
         else if (n->name() == name) {
             if (pathIndex+1 >= path.size()) {
-                if (n->type() == type)
+                if ((n->type() == type) || (type == Node::NoType))
                     return n;
                 continue;
             }
@@ -816,6 +802,23 @@ void Tree::insertTarget(const QString& name, TargetRec::Type type, Node* node, i
 }
 
 /*!
+  Searches this tree for a node named \a target and returns
+  a pointer to it if found. The \a start node is the starting
+  point, but it only makes sense if \a start is in this tree.
+  If \a start is not in this tree, \a start is set to 0 before
+  beginning the search to ensure that the search starts at the
+  root.
+ */
+const Node* Tree::resolveTarget(const QString& target, const Node* start)
+{
+    QStringList path = target.split("::");
+    int flags = SearchBaseClasses | SearchEnumValues | NonFunction;
+    if (start && start->tree() != this)
+        start = 0;
+    return findNode(path, start, flags);
+}
+
+/*!
  */
 void Tree::resolveTargets(InnerNode* root)
 {