qdoc: Always try to use the declaration location

qdoc now always tries to use an element's declaration location
for the "location," "filepath," and "lineno" attributes in the
index file, when it makes sense to use the declaration location.
That's pretty much everything in C++.

qdoc records both the declaration location and the definition
location in the element's tree node. When it writes the element
to the index file, it asks for the declaration location.

Change-Id: I2d169a0f028bb0d46717e6f822dacc6dd20673b2
Task-number: QTBUG-46034
Reviewed-by: Venugopal Shivashankar <[email protected]>
Reviewed-by: Topi Reiniö <[email protected]>

5 files changed, 54 insertions, 22 deletions

diff --git a/src/tools/qdoc/location.cpp b/src/tools/qdoc/location.cpp
index 5eba2a69ef7..98b63fd035c 100644
--- a/src/tools/qdoc/location.cpp
+++ b/src/tools/qdoc/location.cpp
@@ -202,25 +202,34 @@ void Location::pop()
  */
 
 /*! \fn const QString& Location::filePath() const
-  Returns the current path and file name.
-  Must not be called on an empty Location object.
+  Returns the current path and file name. If the Location is
+  empty, the returned string is null.
 
   \sa lineNo(), columnNo()
  */
 
 /*!
-  Returns the file name part of the file path, ie the
-  current file.  Must not be called on an empty Location
-  object.
+  Returns the file name part of the file path, ie the current
+  file. Returns an empty string if the file path is empty.
  */
 QString Location::fileName() const
 {
     QString fp = filePath();
-    return fp.mid(fp.lastIndexOf('/') + 1);
+    return (fp.isEmpty() ? fp : fp.mid(fp.lastIndexOf('/') + 1));
 }
 
 
 /*!
+  Returns the suffix of the file name. Returns an empty string
+  if the file path is empty.
+ */
+QString Location::fileSuffix() const
+{
+    QString fp = filePath();
+    return (fp.isEmpty() ? fp : fp.mid(fp.lastIndexOf('.') + 1));
+}
+
+/*!
   \brief  Returns \a path which is canonicalized and relative to the config file.
 
   QDir::relativeFilePath does not canonicalize the paths, so
diff --git a/src/tools/qdoc/location.h b/src/tools/qdoc/location.h
index 5250e27a477..ade7a1518af 100644
--- a/src/tools/qdoc/location.h
+++ b/src/tools/qdoc/location.h
@@ -72,6 +72,7 @@ public:
     int depth() const { return stkDepth; }
     const QString& filePath() const { return stkTop->filePath; }
     QString fileName() const;
+    QString fileSuffix() const;
     int lineNo() const { return stkTop->lineNo; }
     int columnNo() const { return stkTop->columnNo; }
     bool etc() const { return etcetera; }
diff --git a/src/tools/qdoc/node.cpp b/src/tools/qdoc/node.cpp
index dbe397357ce..e58e65a633c 100644
--- a/src/tools/qdoc/node.cpp
+++ b/src/tools/qdoc/node.cpp
@@ -683,6 +683,24 @@ const Node* Node::root() const
 }
 
 /*!
+  Sets the node's declaration location, its definition
+  location, or both, depending on the suffix of the file
+  name from the file path in location \a t.
+ */
+void Node::setLocation(const Location& t)
+{
+    QString suffix = t.fileSuffix();
+    if (suffix == "h")
+        declLocation_ = t;
+    else if (suffix == "cpp")
+        defLocation_ = t;
+    else {
+        declLocation_ = t;
+        defLocation_ = t;
+    }
+}
+
+/*!
   \class Aggregate
  */
 
@@ -2278,16 +2296,16 @@ bool QmlPropertyNode::isWritable()
                 if (pn)
                     return pn->isWritable();
                 else
-                    location().warning(tr("No Q_PROPERTY for QML property %1::%2::%3 "
-                                          "in C++ class documented as QML type: "
-                                          "(property not found in the C++ class or its base classes)")
-                                       .arg(logicalModuleName()).arg(qmlTypeName()).arg(name()));
+                    defLocation().warning(tr("No Q_PROPERTY for QML property %1::%2::%3 "
+                                             "in C++ class documented as QML type: "
+                                             "(property not found in the C++ class or its base classes)")
+                                          .arg(logicalModuleName()).arg(qmlTypeName()).arg(name()));
             }
             else
-                location().warning(tr("No Q_PROPERTY for QML property %1::%2::%3 "
-                                      "in C++ class documented as QML type: "
-                                      "(C++ class not specified or not found).")
-                                   .arg(logicalModuleName()).arg(qmlTypeName()).arg(name()));
+                defLocation().warning(tr("No Q_PROPERTY for QML property %1::%2::%3 "
+                                         "in C++ class documented as QML type: "
+                                         "(C++ class not specified or not found).")
+                                      .arg(logicalModuleName()).arg(qmlTypeName()).arg(name()));
         }
     }
     return true;
diff --git a/src/tools/qdoc/node.h b/src/tools/qdoc/node.h
index 845b99a4e84..8a666b1161f 100644
--- a/src/tools/qdoc/node.h
+++ b/src/tools/qdoc/node.h
@@ -167,7 +167,7 @@ public:
     void setGenus(Genus t) { genus_ = (unsigned char) t; }
 
     void setAccess(Access t) { access_ = (unsigned char) t; }
-    void setLocation(const Location& location) { loc_ = location; }
+    void setLocation(const Location& t);
     void setDoc(const Doc& doc, bool replace = false);
     void setStatus(Status t) {
         if (status_ == (unsigned char) Obsolete && t == Deprecated)
@@ -276,7 +276,9 @@ public:
     Access access() const { return (Access) access_; }
     bool isPrivate() const { return (Access) access_ == Private; }
     QString accessString() const;
-    const Location& location() const { return loc_; }
+    const Location& declLocation() const { return declLocation_; }
+    const Location& defLocation() const { return defLocation_; }
+    const Location& location() const { return (defLocation_.isEmpty() ? declLocation_ : defLocation_); }
     const Doc& doc() const { return doc_; }
     bool hasDoc() const { return !doc_.isEmpty(); }
     Status status() const { return (Status) status_; }
@@ -345,7 +347,8 @@ private:
     Aggregate* parent_;
     Aggregate* relatesTo_;
     QString name_;
-    Location loc_;
+    Location declLocation_;
+    Location defLocation_;
     Doc doc_;
     QMap<LinkType, QPair<QString, QString> > linkMap_;
     QString fileNameBase_;
diff --git a/src/tools/qdoc/qdocindexfiles.cpp b/src/tools/qdoc/qdocindexfiles.cpp
index dc6bb674f2d..2e49c1c5945 100644
--- a/src/tools/qdoc/qdocindexfiles.cpp
+++ b/src/tools/qdoc/qdocindexfiles.cpp
@@ -954,11 +954,12 @@ bool QDocIndexFiles::generateIndexSection(QXmlStreamWriter& writer,
         if (node->isAbstract())
             writer.writeAttribute("abstract", "true");
     }
-    if (!node->location().fileName().isEmpty())
-        writer.writeAttribute("location", node->location().fileName());
-    if (!node->location().filePath().isEmpty()) {
-        writer.writeAttribute("filepath", node->location().filePath());
-        writer.writeAttribute("lineno", QString("%1").arg(node->location().lineNo()));
+    const Location& declLocation = node->declLocation();
+    if (!declLocation.fileName().isEmpty())
+        writer.writeAttribute("location", declLocation.fileName());
+    if (!declLocation.filePath().isEmpty()) {
+        writer.writeAttribute("filepath", declLocation.filePath());
+        writer.writeAttribute("lineno", QString("%1").arg(declLocation.lineNo()));
     }
 
     if (!node->since().isEmpty()) {