qdoc: Improve resolving related non-members and their overload numbers

There were several problems related to resolving related non-member
(RNM) functions for classes. This commit does the following changes:

  - Overload numbers for RNMs are now calculated at the time the
    \relates command is processed, instead of a separate step.
  - If a \relates refers to an entity outside the module boundary,
    write the argument passed to it as-is into the index file.
  - Delay the destruction of QDocIndexFiles singleton, to resolve
    the RNMs read from the index files prior to generating docs.
  - Remove the redundant call to normalizeOverloads() for single-
    exec mode as unnecessary.

These changes ensure that all RNMs are listed in the documentation
for the node that they belong to.

A remaining issue is that if a function relates to a class outside
the module boundary, that function documentation will be empty
because the doc content is not stored into the index file (for
obvious reasons). Single-exec mode does not have this problem.

Change-Id: I33f038120728932cd9fd70da28d9090023068bd6
Task-number: QTBUG-47589
Reviewed-by: Topi Reiniö <[email protected]>

1 files changed, 71 insertions, 23 deletions

diff --git a/src/tools/qdoc/node.cpp b/src/tools/qdoc/node.cpp
index c803acbf605..c879d1d9b41 100644
--- a/src/tools/qdoc/node.cpp
+++ b/src/tools/qdoc/node.cpp
@@ -106,7 +106,24 @@ Node::~Node()
 {
     if (parent_)
         parent_->removeChild(this);
+
     if (relatesTo_)
+        removeRelates();
+}
+
+/*!
+    Removes this node from the aggregate's list of related
+    nodes, or if this node has created a dummy "relates"
+    aggregate, deletes it.
+*/
+void Node::removeRelates()
+{
+    if (!relatesTo_)
+        return;
+
+    if (relatesTo_->isDocumentNode() && !relatesTo_->parent())
+        delete relatesTo_;
+    else
         relatesTo_->removeRelated(this);
 }
 
@@ -463,11 +480,19 @@ bool Node::fromFlagValue(FlagValue fv, bool defaultValue)
  */
 void Node::setRelates(Aggregate *pseudoParent)
 {
-    if (relatesTo_) {
-        relatesTo_->removeRelated(this);
-    }
+    removeRelates();
     relatesTo_ = pseudoParent;
-    pseudoParent->related_.append(this);
+    pseudoParent->addRelated(this);
+}
+
+/*!
+  Sets the (unresolved) entity \a name that this node relates to.
+ */
+void Node::setRelates(const QString& name)
+{
+    removeRelates();
+    // Create a dummy aggregate for writing the name into the index
+    relatesTo_ = new DocumentNode(0, name, Node::NoSubtype, Node::NoPageType);
 }
 
 /*!
@@ -934,8 +959,9 @@ void Aggregate::makeUndocumentedChildrenInternal()
 }
 
 /*!
-  This is where we should set the overload numbers, including
-  the related non-members.
+  This is where we set the overload numbers for function nodes.
+  \note Overload numbers for related non-members are handled
+  separately.
  */
 void Aggregate::normalizeOverloads()
 {
@@ -1007,23 +1033,6 @@ void Aggregate::normalizeOverloads()
         ++p;
     }
     /*
-      Add the related non-members here.
-     */
-    if (!related_.isEmpty()) {
-        foreach (Node* n, related_) {
-            if (n->isFunction()) {
-                FunctionNode* fn = static_cast<FunctionNode*>(n);
-                QMap<QString, Node *>::Iterator p = primaryFunctionMap_.find(fn->name());
-                if (p != primaryFunctionMap_.end()) {
-                    secondaryFunctionMap_[fn->name()].append(fn);
-                    fn->setOverloadNumber(secondaryFunctionMap_[fn->name()].size());
-                }
-                else
-                    fn->setOverloadNumber(0);
-            }
-        }
-    }
-    /*
       Recursive part.
      */
     NodeList::ConstIterator c = childNodes().constBegin();
@@ -1322,10 +1331,49 @@ QString Node::physicalModuleName() const
 }
 
 /*!
+  Removes a node from the list of nodes related to this one.
+  If it is a function node, also remove from the primary/
+  secondary function maps.
  */
 void Aggregate::removeRelated(Node *pseudoChild)
 {
     related_.removeAll(pseudoChild);
+
+    if (pseudoChild->isFunction()) {
+        QMap<QString, Node *>::Iterator p = primaryFunctionMap_.find(pseudoChild->name());
+        while (p != primaryFunctionMap_.end()) {
+            if (p.value() == pseudoChild) {
+                primaryFunctionMap_.erase(p);
+                break;
+            }
+            ++p;
+        }
+        NodeList& overloads = secondaryFunctionMap_[pseudoChild->name()];
+        overloads.removeAll(pseudoChild);
+    }
+}
+
+/*!
+  Adds \a pseudoChild to the list of nodes related to this one. Resolve a correct
+  overload number for a related non-member function.
+ */
+void Aggregate::addRelated(Node *pseudoChild)
+{
+    related_.append(pseudoChild);
+
+    if (pseudoChild->isFunction()) {
+        FunctionNode* fn = static_cast<FunctionNode*>(pseudoChild);
+        if (primaryFunctionMap_.contains(pseudoChild->name())) {
+            secondaryFunctionMap_[pseudoChild->name()].append(pseudoChild);
+            fn->setOverloadNumber(secondaryFunctionMap_[pseudoChild->name()].size());
+            fn->setOverloadFlag(true);
+        }
+        else {
+            primaryFunctionMap_.insert(pseudoChild->name(), pseudoChild);
+            fn->setOverloadNumber(0);
+            fn->setOverloadFlag(false);
+        }
+    }
 }
 
 /*!