qdoc: Include source file and line number of links

Each entry in the link-to-link tables and in the
broken-links table now includes the source file
path of the file where the link or broken link
appears and the line number in that file. The
line number often refers to where the comment
that contains the link begins, so sometimes
the link or broken link appears further down in
that comment.

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

4 files changed, 47 insertions, 25 deletions

diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index cdbfd7b8f5..e158a8dff6 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -386,19 +386,24 @@ QString HtmlGenerator::generateLinksToLinksPage(const QString& module, CodeMarke
     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()
+    out() << "<p>This is a 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";
+    out() << "Click on a link to go to the location of the link. The link is marked ";
+    out() << "with red asterisks. ";
+    out() << "Click on the marked link to see if it goes to the right place.</p>\n";
     TargetList* tlist = qdb_->getTargetList(module);
     if (tlist) {
-        out() << "<table class=\"alignedsummary\">\n";
+        out() << "<table class=\"valuelist\"><tr valign=\"top\" class=\"odd\"><th class=\"tblConst\">Link to  link...</th><th class=\"tblval\">In file...</th><th class=\"tbldscr\">Somewhere after line number...</th></tr>\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() << "<tr><td class=\"topAlign\">";
             out() << "<a href=\"" << t->fileName_ << "#" << t->target_ << "\">";
-            out() << t->text_ << "</a>";
-            out() << "</td></tr>\n";
+            out() << t->text_ << "</a></td>";
+            out() << "<td class=\"topAlign\">";
+            QString f = t->loc_->doc().location().filePath();
+            out() << f << "</td>";
+            out() << "<td class=\"topAlign\">";
+            out() << t->loc_->doc().location().lineNo() << "</td></tr>\n";
         }
         out() << "</table>\n";
     }
@@ -424,19 +429,23 @@ QString HtmlGenerator::generateLinksToBrokenLinksPage(CodeMarker* marker, int& c
         count = tlist->size();
         fileName = "aaa-links-to-broken-links.html";
         beginSubPage(node, fileName);
-        QString title = "Links from " + defaultModuleName() + " that go nowhere";
+        QString title = "Broken links in " + defaultModuleName();
         generateHeader(title, node, marker);
         generateTitle(title, Text(), SmallSubTitle, node, marker);
-        out() << "<p>This is the complete list of broken links in " << defaultModuleName() << ".  ";
-        out() << "Click on a link to go directly to the actual link in the docs.  ";
-        out() << "The target for the link could not be found.</p>\n";
-        out() << "<table class=\"alignedsummary\">\n";
+        out() << "<p>This is a list of broken links in " << defaultModuleName() << ".  ";
+        out() << "Click on a link to go to the broken link.  ";
+        out() << "The link's target could not be found.</p>\n";
+        out() << "<table class=\"valuelist\"><tr valign=\"top\" class=\"odd\"><th class=\"tblConst\">Link to broken link...</th><th class=\"tblval\">In file...</th><th class=\"tbldscr\">Somewhere after line number...</th></tr>\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() << "<tr><td class=\"topAlign\">";
             out() << "<a href=\"" << t->fileName_ << "#" << t->target_ << "\">";
-            out() << t->text_ << "</a>";
-            out() << "</td></tr>\n";
+            out() << t->text_ << "</a></td>";
+            out() << "<td class=\"topAlign\">";
+            QString f = t->loc_->doc().location().filePath();
+            out() << f << "</td>";
+            out() << "<td class=\"topAlign\">";
+            out() << t->loc_->doc().location().lineNo() << "</td></tr>\n";
         }
         out() << "</table>\n";
         generateFooter();
@@ -481,7 +490,7 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
             else {
                 if (Generator::writeQaPages() && node && (atom->type() != Atom::NavAutoLink)) {
                     QString text = atom->string();
-                    QString target = qdb_->getNewLinkTarget(node, outFileName(), text);
+                    QString target = qdb_->getNewLinkTarget(relative, node, outFileName(), text);
                     out() << "<a id=\"" << Doc::canonicalTitle(target) << "\" class=\"qa-mark\"></a>";
                 }
                 beginLink(link, node, relative);
@@ -975,14 +984,14 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
             relative->doc().location().warning(tr("Can't link to '%1'").arg(atom->string()));
             if (Generator::writeQaPages() && (atom->type() != Atom::NavAutoLink)) {
                 QString text = atom->next()->next()->string();
-                QString target = qdb_->getNewLinkTarget(node, outFileName(), text, true);
+                QString target = qdb_->getNewLinkTarget(relative, node, outFileName(), text, true);
                 out() << "<a id=\"" << Doc::canonicalTitle(target) << "\" class=\"qa-mark\"></a>";
             }
         }
         else {
             if (Generator::writeQaPages() && node && (atom->type() != Atom::NavLink)) {
                 QString text = atom->next()->next()->string();
-                QString target = qdb_->getNewLinkTarget(node, outFileName(), text);
+                QString target = qdb_->getNewLinkTarget(relative, node, outFileName(), text);
                 out() << "<a id=\"" << Doc::canonicalTitle(target) << "\" class=\"qa-mark\"></a>";
             }
             /*
diff --git a/src/tools/qdoc/qdocdatabase.h b/src/tools/qdoc/qdocdatabase.h
index 148e40bb4a..9b4d7019ad 100644
--- a/src/tools/qdoc/qdocdatabase.h
+++ b/src/tools/qdoc/qdocdatabase.h
@@ -392,8 +392,12 @@ class QDocDatabase
     QString getLinkCounts(QStringList& strings, QVector<int>& counts) {
         return forest_.getLinkCounts(strings, counts);
     }
-    QString getNewLinkTarget(const Node* t, const QString& fileName, QString& text, bool broken = false) {
-        return primaryTree()->getNewLinkTarget(t, fileName, text, broken);
+    QString getNewLinkTarget(const Node* locNode,
+                             const Node* t,
+                             const QString& fileName,
+                             QString& text,
+                             bool broken = false) {
+        return primaryTree()->getNewLinkTarget(locNode, t, fileName, text, broken);
     }
     TargetList* getTargetList(const QString& t) { return primaryTree()->getTargetList(t); }
     QStringList getTargetListKeys() { return primaryTree()->getTargetListKeys(); }
diff --git a/src/tools/qdoc/tree.cpp b/src/tools/qdoc/tree.cpp
index e11b7f1490..a4b8d8cd8a 100644
--- a/src/tools/qdoc/tree.cpp
+++ b/src/tools/qdoc/tree.cpp
@@ -1423,7 +1423,11 @@ const Node* Tree::checkForCollision(const QString& name)
 
   The node \a t
  */
-QString Tree::getNewLinkTarget(const Node* t, const QString& fileName, QString& text, bool broken)
+QString Tree::getNewLinkTarget(const Node* locNode,
+                               const Node* t,
+                               const QString& fileName,
+                               QString& text,
+                               bool broken)
 {
     QString moduleName;
     if (t && !broken) {
@@ -1436,7 +1440,7 @@ QString Tree::getNewLinkTarget(const Node* t, const QString& fileName, QString&
         moduleName = "broken";
     incrementLinkCount();
     QString target = QString("qa-target-%1").arg(-(linkCount()));
-    TargetLoc* tloc = new TargetLoc(target, fileName, text, broken);
+    TargetLoc* tloc = new TargetLoc(locNode, target, fileName, text, broken);
     TargetList* tList = 0;
     TargetListMap::iterator i = targetListMap_->find(moduleName);
     if (i == targetListMap_->end()) {
diff --git a/src/tools/qdoc/tree.h b/src/tools/qdoc/tree.h
index a2578a3bc8..6ccf85371b 100644
--- a/src/tools/qdoc/tree.h
+++ b/src/tools/qdoc/tree.h
@@ -70,8 +70,9 @@ struct TargetRec
 struct TargetLoc
 {
   public:
-  TargetLoc(const QString& t, const QString& fileName, const QString& text, bool broken = false)
-  : target_(t), fileName_(fileName), text_(text), broken_(broken) { }
+  TargetLoc(const Node* loc, const QString& t, const QString& fileName, const QString& text, bool broken)
+  : loc_(loc), target_(t), fileName_(fileName), text_(text), broken_(broken) { }
+    const Node*   loc_;
     QString target_;
     QString fileName_;
     QString text_;
@@ -206,7 +207,11 @@ 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, bool broken);
+    QString getNewLinkTarget(const Node* locNode,
+                             const Node* t,
+                             const QString& fileName,
+                             QString& text,
+                             bool broken);
     TargetList* getTargetList(const QString& module);
     QStringList getTargetListKeys() { return targetListMap_->keys(); }