qdoc: Generate cross-module links-to-links pages

The cross-module link report is modified so that each module
listed in the table is a link to a subpage on which all the
links from the current module to that module are listed. To
check that these links go to the correct place, click on one
to be taken to the actual link. The actual link is marked
with red asterisks. Click on that link to check that the link
goes to the correct page. Repeat this process for all the
links in the table.

Change-Id: Ifddf7108ed7ef090c4063909fdbd10dac1f2566b
Task-number: QTBUG-41850
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

8 files changed, 171 insertions, 65 deletions

diff --git a/src/tools/qdoc/atom.cpp b/src/tools/qdoc/atom.cpp
index 1af31afedd..e227526d90 100644
--- a/src/tools/qdoc/atom.cpp
+++ b/src/tools/qdoc/atom.cpp
@@ -107,6 +107,8 @@ QT_BEGIN_NAMESPACE
   \value ListItemLeft
   \value ListItemRight
   \value ListRight
+  \value NavAutoLink
+  \value NavLink
   \value Nop
   \value Note
   \value ParaLeft
@@ -193,6 +195,8 @@ static const struct {
     { "ListItemLeft", Atom::ListItemLeft },
     { "ListItemRight", Atom::ListItemRight },
     { "ListRight", Atom::ListRight },
+    { "NavAutoLink", Atom::NavAutoLink },
+    { "NavLink", Atom::NavLink },
     { "Nop", Atom::Nop },
     { "NoteLeft", Atom::NoteLeft },
     { "NoteRight", Atom::NoteRight },
diff --git a/src/tools/qdoc/atom.h b/src/tools/qdoc/atom.h
index 3a7e992f7b..daa94a1fb8 100644
--- a/src/tools/qdoc/atom.h
+++ b/src/tools/qdoc/atom.h
@@ -57,7 +57,7 @@ public:
         BriefRight,
         C,
         CaptionLeft,
-        CaptionRight,           // 10
+        CaptionRight,
         Code,
         CodeBad,
         CodeNew,
@@ -67,7 +67,7 @@ public:
         DivLeft,
         DivRight,
         EndQmlText,
-        FootnoteLeft,           // 20
+        FootnoteLeft,
         FootnoteRight,
         FormatElse,
         FormatEndif,
@@ -77,7 +77,7 @@ public:
         GeneratedList,
         GuidLink,
         HR,
-        Image,                  // 30
+        Image,
         ImageText,
         ImportantLeft,
         ImportantRight,
@@ -87,7 +87,7 @@ public:
         LegaleseLeft,
         LegaleseRight,
         LineBreak,
-        Link,                   // 40
+        Link,
         LinkNode,
         ListLeft,
         ListItemNumber,
@@ -96,8 +96,10 @@ public:
         ListItemLeft,
         ListItemRight,
         ListRight,
+        NavAutoLink,
+        NavLink,
         Nop,
-        NoteLeft,               // 50
+        NoteLeft,
         NoteRight,
         ParaLeft,
         ParaRight,
@@ -107,7 +109,7 @@ public:
         QuotationRight,
         RawString,
         SectionLeft,
-        SectionRight,           // 60
+        SectionRight,
         SectionHeadingLeft,
         SectionHeadingRight,
         SidebarLeft,
@@ -117,7 +119,7 @@ public:
         SnippetIdentifier,
         SnippetLocation,
         String,
-        TableLeft,              // 70
+        TableLeft,
         TableRight,
         TableHeaderLeft,
         TableHeaderRight,
@@ -127,7 +129,7 @@ public:
         TableItemRight,
         TableOfContents,
         Target,
-        UnhandledFormat,        // 80
+        UnhandledFormat,
         UnknownCommand,
         Last = UnknownCommand
     };
diff --git a/src/tools/qdoc/doc.cpp b/src/tools/qdoc/doc.cpp
index cdb8472e4f..53d8ea885d 100644
--- a/src/tools/qdoc/doc.cpp
+++ b/src/tools/qdoc/doc.cpp
@@ -1991,7 +1991,7 @@ void DocParser::append(const QString &string)
     Atom::Type lastType = priv->text.lastAtom()->type();
     if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n")))
         priv->text.lastAtom()->chopString();
-    priv->text << Atom(string);
+    priv->text << Atom(string); // The Atom type is Link.
 }
 
 void DocParser::append(Atom::Type type, const QString& p1, const QString& p2)
@@ -2008,7 +2008,7 @@ void DocParser::append(const QString& p1, const QString& p2)
     if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n")))
         priv->text.lastAtom()->chopString();
     if (p2.isEmpty())
-        priv->text << Atom(p1);
+        priv->text << Atom(p1); // The Atom type is Link.
     else
         priv->text << LinkAtom(p1, p2);
 }
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index ca58be57c7..f08f84abae 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -327,7 +327,10 @@ void HtmlGenerator::generateQAPage()
               << "class=\"even\"><th class=\"tblConst\">Destination Module</th>"
               << "<th class=\"tblval\">Link Count</th></tr>\n";
         for (int i = 0; i< strings.size(); ++i) {
-            out() << "<tr><td class=\"topAlign\"><tt>" << strings.at(i)
+            QString fileName = generateLinksToLinksPage(strings.at(i), marker);
+            out() << "<tr><td class=\"topAlign\"><tt>"
+                  << "<a href=\"" << fileName << "\">"
+                  << strings.at(i) << "</a>"
                   << "</tt></td><td class=\"topAlign\"><tt>" << counts.at(i)
                   << "</tt></td></tr>\n";
         }
@@ -339,7 +342,39 @@ void HtmlGenerator::generateQAPage()
         out() << "<p>" << protectEnc(t) << "</p>\n";
         out() << "<p>" << protectEnc(depends) << "</p>\n";
     }
+    generateFooter();
+    endSubPage();
+}
+
+/*!
+ */
+QString HtmlGenerator::generateLinksToLinksPage(const QString& module, CodeMarker* marker)
+{
+    NamespaceNode* node = qdb_->primaryTreeRoot();
+    QString fileName = "aaa-links-to-" + module + ".html";
+    beginSubPage(node, fileName);
+    QString title = "Links from " + defaultModuleName() + " to " + module;
+    generateHeader(title, node, marker);
+    generateTitle(title, Text(), SmallSubTitle, node, marker);
+    out() << "<p>This is the complete list of links from " << defaultModuleName()
+          << " to " << module << ".  ";
+    out() << "Click on a link to go directly to the actual link in the docs.  ";
+    out() << "Then click on that link to check whether it goes to the correct place.</p>\n";
+    TargetList* tlist = qdb_->getTargetList(module);
+    if (tlist) {
+        out() << "<table class=\"alignedsummary\">\n";
+        foreach (TargetLoc* t, *tlist) {
+            // e.g.: <a name="link-8421"></a><a href="layout.html">Layout Management</a>
+            out() << "<tr><td class=\"memItemLeft leftAlign topAlign\">";
+            out() << "<a href=\"" << t->fileName_ << "#" << t->target_ << "\">";
+            out() << t->text_ << "</a>";
+            out() << "</td></tr>\n";
+        }
+        out() << "</table>\n";
+    }
+    generateFooter();
     endSubPage();
+    return fileName;
 }
 
 /*!
@@ -360,6 +395,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
     case Atom::AbstractRight:
         break;
     case Atom::AutoLink:
+    case Atom::NavAutoLink:
         if (!inLink_ && !inContents_ && !inSectionHeading_) {
             const Node *node = 0;
             QString link = getAutoLink(atom, relative, &node);
@@ -374,6 +410,11 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
             if (link.isEmpty())
                 out() << protectEnc(atom->string());
             else {
+                if (Generator::writeQaPages() && node && (atom->type() != Atom::NavAutoLink)) {
+                    QString text = atom->string();
+                    QString target = qdb_->getNewLinkTarget(node, outFileName(), text);
+                    out() << "<a id=\"" << Doc::canonicalTitle(target) << "\" class=\"qa-mark\"></a>";
+                }
                 beginLink(link, node, relative);
                 generateLink(atom, marker);
                 endLink();
@@ -856,6 +897,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
         out() << "<br/>";
         break;
     case Atom::Link:
+    case Atom::NavLink:
     {
         inObsoleteLink = false;
         const Node *node = 0;
@@ -864,6 +906,17 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
             relative->doc().location().warning(tr("Can't link to '%1'").arg(atom->string()));
         }
         else {
+            if (Generator::writeQaPages() && node && (atom->type() != Atom::NavLink)) {
+                QString text = atom->next()->next()->string();
+                QString target = qdb_->getNewLinkTarget(node, outFileName(), text);
+                out() << "<a id=\"" << Doc::canonicalTitle(target) << "\" class=\"qa-mark\"></a>";
+            }
+            /*
+              mws saw this on 17/10/2014.
+              Is this correct? Setting node to 0 means the
+              following test always fails. Did we decide to
+              no longer warn about linking to obsolete things?
+             */
             node = 0;
             if (node && node->status() == Node::Obsolete) {
                 if ((relative->parent() != node) && !relative->isObsolete()) {
@@ -1698,11 +1751,11 @@ void HtmlGenerator::generateNavigationBar(const QString &title,
         return;
     if (!homepage.isEmpty())
         navigationbar << Atom(Atom::ListItemLeft)
-                    << Atom(Atom::AutoLink, homepage)
+                    << Atom(Atom::NavAutoLink, homepage)
                     << Atom(Atom::ListItemRight);
     if (!landingpage.isEmpty() && landingpage != title)
         navigationbar << Atom(Atom::ListItemLeft)
-                    << Atom(Atom::AutoLink, landingpage)
+                    << Atom(Atom::NavAutoLink, landingpage)
                     << Atom(Atom::ListItemRight);
 
     if (node->isClass()) {
@@ -1711,7 +1764,7 @@ void HtmlGenerator::generateNavigationBar(const QString &title,
 
         if (!cppclassespage.isEmpty())
             navigationbar << Atom(Atom::ListItemLeft)
-                        << Atom(Atom::Link, cppclassespage)
+                        << Atom(Atom::NavLink, cppclassespage)
                         << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
                         << Atom(Atom::String, QLatin1String("C++ Classes"))
                         << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
@@ -1725,7 +1778,7 @@ void HtmlGenerator::generateNavigationBar(const QString &title,
     else if (node->isQmlType() || node->isQmlBasicType()) {
         if (!qmltypespage.isEmpty())
             navigationbar << Atom(Atom::ListItemLeft)
-                          << Atom(Atom::Link, qmltypespage)
+                          << Atom(Atom::NavLink, qmltypespage)
                           << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
                           << Atom(Atom::String, QLatin1String("QML Types"))
                           << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
@@ -1737,7 +1790,7 @@ void HtmlGenerator::generateNavigationBar(const QString &title,
     else {
         if (node->isExampleFile()) {
             navigationbar << Atom(Atom::ListItemLeft)
-                          << Atom(Atom::Link, node->parent()->name())
+                          << Atom(Atom::NavLink, node->parent()->name())
                           << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
                           << Atom(Atom::String, node->parent()->title())
                           << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
@@ -3711,36 +3764,7 @@ QString HtmlGenerator::getLink(const Atom *atom, const Node *relative, const Nod
         if (t.startsWith("mailto:"))
             return t;
     }
-
-    QString ref;
-
-    *node = qdb_->findNodeForAtom(atom, relative, ref);
-    if (!(*node))
-        return QString();
-    if (Generator::writeQaPages())
-        qdb_->incrementLinkCount(*node);
-
-    QString url = (*node)->url();
-    if (!url.isEmpty()) {
-        if (ref.isEmpty())
-            return url;
-        int hashtag = url.lastIndexOf(QChar('#'));
-        if (hashtag != -1)
-            url.truncate(hashtag);
-        return url + "#" + ref;
-    }
-    /*
-      Given that *node is not null, we now cconstruct a link
-      to the page that *node represents, and then if we found
-      a target on that page, we connect the target to the link
-      with '#'.
-    */
-    QString link = linkForNode(*node, relative);
-    if (*node && (*node)->subType() == Node::Image)
-        link = "images/used-in-examples/" + link;
-    if (!ref.isEmpty())
-        link += QLatin1Char('#') + ref;
-    return link;
+    return getAutoLink(atom, relative, node);
 }
 
 /*!
@@ -3758,28 +3782,25 @@ QString HtmlGenerator::getLink(const Atom *atom, const Node *relative, const Nod
 QString HtmlGenerator::getAutoLink(const Atom *atom, const Node *relative, const Node** node)
 {
     QString ref;
-    QString link;
 
     *node = qdb_->findNodeForAtom(atom, relative, ref);
     if (!(*node))
         return QString();
 
-    if (Generator::writeQaPages())
-        qdb_->incrementLinkCount(*node);
-
-    QString url = (*node)->url();
-    if (!url.isEmpty()) {
-        if (ref.isEmpty())
-            return url;
-        int hashtag = url.lastIndexOf(QChar('#'));
+    QString link = (*node)->url();
+    if (link.isEmpty()) {
+        link = linkForNode(*node, relative);
+        if ((*node)->subType() == Node::Image)
+            link = "images/used-in-examples/" + link;
+        if (!ref.isEmpty())
+            link += QLatin1Char('#') + ref;
+    }
+    else if (!ref.isEmpty()) {
+        int hashtag = link.lastIndexOf(QChar('#'));
         if (hashtag != -1)
-            url.truncate(hashtag);
-        return url + "#" + ref;
+            link.truncate(hashtag);
+        link += "#" + ref;
     }
-
-    link = linkForNode(*node, relative);
-    if (!ref.isEmpty())
-        link += QLatin1Char('#') + ref;
     return link;
 }
 
diff --git a/src/tools/qdoc/htmlgenerator.h b/src/tools/qdoc/htmlgenerator.h
index 825522a121..b8ead2bbec 100644
--- a/src/tools/qdoc/htmlgenerator.h
+++ b/src/tools/qdoc/htmlgenerator.h
@@ -90,6 +90,7 @@ public:
 
 protected:
     virtual void generateQAPage();
+    QString generateLinksToLinksPage(const QString& module, CodeMarker* marker);
     virtual int generateAtom(const Atom *atom,
                              const Node *relative,
                              CodeMarker *marker);
diff --git a/src/tools/qdoc/qdocdatabase.h b/src/tools/qdoc/qdocdatabase.h
index 02d39e62e7..09bfbbfac3 100644
--- a/src/tools/qdoc/qdocdatabase.h
+++ b/src/tools/qdoc/qdocdatabase.h
@@ -392,6 +392,11 @@ class QDocDatabase
     QString getLinkCounts(QStringList& strings, QVector<int>& counts) {
         return forest_.getLinkCounts(strings, counts);
     }
+    QString getNewLinkTarget(const Node* t, const QString& fileName, QString& text) {
+        return primaryTree()->getNewLinkTarget(t, fileName, text);
+    }
+    TargetList* getTargetList(const QString& t) { return primaryTree()->getTargetList(t); }
+    QStringList getTargetListKeys() { return primaryTree()->getTargetListKeys(); }
 
  private:
     friend class QDocIndexFiles;
diff --git a/src/tools/qdoc/tree.cpp b/src/tools/qdoc/tree.cpp
index f3a6ed78da..6610bd0db4 100644
--- a/src/tools/qdoc/tree.cpp
+++ b/src/tools/qdoc/tree.cpp
@@ -71,10 +71,14 @@ Tree::Tree(const QString& module, QDocDatabase* qdb)
       linkCount_(0),
       module_(module),
       qdb_(qdb),
-      root_(0, QString())
+      root_(0, QString()),
+      targetListMap_(0)
 {
     root_.setModuleName(module_);
     root_.setTree(this);
+    if (Generator::writeQaPages()) {
+        targetListMap_ = new TargetListMap;
+    }
 }
 
 /*!
@@ -100,6 +104,18 @@ Tree::~Tree()
     }
     nodesByTargetRef_.clear();
     nodesByTargetTitle_.clear();
+    if (Generator::writeQaPages() && targetListMap_) {
+        TargetListMap::iterator i = targetListMap_->begin();
+        while (i != targetListMap_->end()) {
+            TargetList* tlist = i.value();
+            if (tlist) {
+                foreach (TargetLoc* tloc, *tlist)
+                    delete tloc;
+            }
+            delete tlist;
+            ++i;
+        }
+    }
 }
 
 /* API members */
@@ -1399,4 +1415,45 @@ const Node* Tree::checkForCollision(const QString& name)
     return findNode(QStringList(name), 0, 0, Node::DontCare);
 }
 
+/*!
+  Generate a target of the form link-nnn, where the nnn is
+  the current link count for this tree. This target string
+  is returned. It will be output as an HTML anchor just before
+  an HTML link to the node \a t.
+
+  The node \a t
+ */
+QString Tree::getNewLinkTarget(const Node* t, const QString& fileName, QString& text)
+{
+    QString target;
+    if (t) {
+        Tree* tree = t->tree();
+        incrementLinkCount();
+        if (tree != this)
+            tree->incrementLinkCount();
+        target = QString("qa-target-%1").arg(-(linkCount()));
+        QString moduleName = tree->moduleName();
+        TargetLoc* tloc = new TargetLoc(target, fileName, text);
+        TargetList* tList = 0;
+        TargetListMap::iterator i = targetListMap_->find(moduleName);
+        if (i == targetListMap_->end()) {
+            tList = new TargetList;
+            i = targetListMap_->insert(moduleName, tList);
+        }
+        else
+            tList = i.value();
+        tList->append(tloc);
+    }
+    return target;
+}
+
+/*!
+  Look up the target list for the specified \a module
+  and return a pointer to it.
+ */
+TargetList* Tree::getTargetList(const QString& module)
+{
+    return targetListMap_->value(module);
+}
+
 QT_END_NAMESPACE
diff --git a/src/tools/qdoc/tree.h b/src/tools/qdoc/tree.h
index 75f751f976..9c55595a77 100644
--- a/src/tools/qdoc/tree.h
+++ b/src/tools/qdoc/tree.h
@@ -67,10 +67,22 @@ struct TargetRec
     Type type_;
 };
 
+struct TargetLoc
+{
+  public:
+  TargetLoc(const QString& t, const QString& fileName, const QString& text)
+  : target_(t), fileName_(fileName), text_(text) { }
+    QString target_;
+    QString fileName_;
+    QString text_;
+};
+
 typedef QMultiMap<QString, TargetRec*> TargetMap;
 typedef QMultiMap<QString, DocNode*> DocNodeMultiMap;
 typedef QMap<QString, QmlClassNode*> QmlTypeMap;
 typedef QMultiMap<QString, const ExampleNode*> ExampleNodeMap;
+typedef QVector<TargetLoc*> TargetList;
+typedef QMap<QString, TargetList*> TargetListMap;
 
 class Tree
 {
@@ -193,18 +205,21 @@ class Tree
     bool docsHaveBeenGenerated() const { return docsHaveBeenGenerated_; }
     void setTreeHasBeenAnalyzed() { treeHasBeenAnalyzed_ = true; }
     void setdocsHaveBeenGenerated() { docsHaveBeenGenerated_ = true; }
+    QString getNewLinkTarget(const Node* t, const QString& fileName, QString& text);
+    TargetList* getTargetList(const QString& module);
+    QStringList getTargetListKeys() { return targetListMap_->keys(); }
 
  public:
     const QString& moduleName() const { return module_; }
     const QString& indexFileName() const { return indexFileName_; }
-    void incrementLinkCount() { --linkCount_; }
+    long incrementLinkCount() { return --linkCount_; }
     void clearLinkCount() { linkCount_ = 0; }
-    int linkCount() const { return linkCount_; }
+    long linkCount() const { return linkCount_; }
 
 private:
     bool treeHasBeenAnalyzed_;
     bool docsHaveBeenGenerated_;
-    int linkCount_;
+    long linkCount_;
     QString module_;
     QString indexFileName_;
     QDocDatabase* qdb_;
@@ -218,6 +233,7 @@ private:
     CNMap                   qmlModules_;
     QmlTypeMap              qmlTypeMap_;
     ExampleNodeMap          exampleNodeMap_;
+    TargetListMap*          targetListMap_;
 };
 
 QT_END_NAMESPACE