qdoc: Don't print unnecessary qdoc warnings

Generates default doc for destructor that is declared but not
documented, thereby avoiding the "No documentation for..." error.

This change reveals several new constructors and assignment operators
that are not documented. Most of these will be handled automatically
the same way these destructors are handled, but that fix will be in a
separate update.

Change-Id: Iffb3834b2ea31fd47d578bf1444be2f25a60ae6f
Task-number: QTBUG-50630
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>

5 files changed, 54 insertions, 9 deletions

diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 81ad2a94b..c8c2ecefd 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -752,8 +752,26 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
         }
     }
     if (node->doc().isEmpty()) {
-        if (!node->isWrapper() && !quiet && !node->isReimplemented()) { // ### might be unnecessary
-            node->location().warning(tr("No documentation for '%1'").arg(node->plainFullName()));
+        /*
+          Test for special function, like a destructor or copy constructor,
+          that has no documentation.
+        */
+        if (node->type() == Node::Function) {
+            const FunctionNode* func = static_cast<const FunctionNode*>(node);
+            if (func->isDtor()) {
+                Text text;
+                text << "Destroys the instance of ";
+                text << func->parent()->name() << ".";
+                if (func->isVirtual())
+                    text << " The destructor is virtual.";
+                generateText(text, node, marker);
+            }
+            else if (!node->isWrapper() && !quiet && !node->isReimplemented()) {
+                node->location().warning(tr("No documentation for '%1'").arg(node->plainSignature()));
+            }
+        }
+        else if (!node->isWrapper() && !quiet && !node->isReimplemented()) {
+            node->location().warning(tr("No documentation for '%1'").arg(node->plainSignature()));
         }
     }
     else {
diff --git a/src/qdoc/node.cpp b/src/qdoc/node.cpp
index 2e2b938b6..d91d473ce 100644
--- a/src/qdoc/node.cpp
+++ b/src/qdoc/node.cpp
@@ -165,6 +165,29 @@ QString Node::plainFullName(const Node* relative) const
 }
 
 /*!
+  Constructs and returns the node's fully qualified signature
+  by recursively ascending the parent links and prepending each
+  parent name + "::" to the plain signature. The return type is
+  not included.
+ */
+QString Node::plainSignature() const
+{
+    if (name_.isEmpty())
+        return QLatin1String("global");
+
+    QString fullName;
+    const Node* node = this;
+    while (node) {
+        fullName.prepend(node->signature(false, true));
+        if (node->parent()->name().isEmpty())
+            break;
+        fullName.prepend(QLatin1String("::"));
+        node = node->parent();
+    }
+    return fullName;
+}
+
+/*!
   Constructs and returns this node's full name.
  */
 QString Node::fullName(const Node* relative) const
@@ -2139,10 +2162,10 @@ QStringList FunctionNode::reconstructParameters(bool values) const
   is true, the default values of the parameters are included, if
   present.
  */
-QString FunctionNode::signature(bool values) const
+QString FunctionNode::signature(bool values, bool noReturnType) const
 {
     QString s;
-    if (!returnType().isEmpty())
+    if (!noReturnType && !returnType().isEmpty())
         s = returnType() + QLatin1Char(' ');
     s += name() + QLatin1Char('(');
     QStringList reconstructedParameters = reconstructParameters(values);
diff --git a/src/qdoc/node.h b/src/qdoc/node.h
index 29bbd12ca..9df3dd70a 100644
--- a/src/qdoc/node.h
+++ b/src/qdoc/node.h
@@ -159,7 +159,9 @@ public:
 
     QString plainName() const;
     QString plainFullName(const Node* relative = 0) const;
+    QString plainSignature() const;
     QString fullName(const Node* relative=0) const;
+    virtual QString signature(bool ,  bool ) const { return plainName(); }
 
     const QString& fileNameBase() const { return fileNameBase_; }
     bool hasFileNameBase() const { return !fileNameBase_.isEmpty(); }
@@ -894,6 +896,8 @@ public:
     bool isOverload() const { return overload_; }
     bool isReimplemented() const Q_DECL_OVERRIDE { return reimplemented_; }
     bool isFunction() const Q_DECL_OVERRIDE { return true; }
+    bool isDtor() const { return (metaness_ == Dtor); }
+    bool isVirtual() const { return (virtualness_ == NormalVirtual); }
     virtual bool isQmlSignal() const Q_DECL_OVERRIDE {
         return (type() == Node::QmlSignal) && (genus() == Node::QML);
     }
@@ -926,7 +930,7 @@ public:
     bool hasActiveAssociatedProperty() const;
 
     QStringList reconstructParameters(bool values = false) const;
-    QString signature(bool values = false) const;
+    virtual QString signature(bool values, bool noReturnType = false) const;
     virtual QString element() const Q_DECL_OVERRIDE { return parent()->name(); }
     virtual bool isAttached() const Q_DECL_OVERRIDE { return attached_; }
     virtual bool isQtQuickNode() const Q_DECL_OVERRIDE { return parent()->isQtQuickNode(); }
diff --git a/src/qdoc/qdocindexfiles.cpp b/src/qdoc/qdocindexfiles.cpp
index fc306b25d..f588638fe 100644
--- a/src/qdoc/qdocindexfiles.cpp
+++ b/src/qdoc/qdocindexfiles.cpp
@@ -1273,7 +1273,7 @@ bool QDocIndexFiles::generateIndexSection(QXmlStreamWriter& writer,
               Note: The "signature" attribute is written to the
               index file, but it is not read back in. Is that ok?
             */
-            QString signature = functionNode->signature();
+            QString signature = functionNode->signature(false);
             if (functionNode->isConst())
                 signature += " const";
             if (functionNode->isFinal())
@@ -1497,9 +1497,9 @@ bool compareNodes(const Node* n1, const Node* n2)
         else if (f1->isConst() > f2->isConst())
             return false;
 
-        if (f1->signature() < f2->signature())
+        if (f1->signature(false) < f2->signature(false))
             return true;
-        else if (f1->signature() > f2->signature())
+        else if (f1->signature(false) > f2->signature(false))
             return false;
     }
 
diff --git a/src/qdoc/qdoctagfiles.cpp b/src/qdoc/qdoctagfiles.cpp
index 95087200d..cc5b30c8e 100644
--- a/src/qdoc/qdoctagfiles.cpp
+++ b/src/qdoc/qdoctagfiles.cpp
@@ -287,7 +287,7 @@ void QDocTagFiles::generateTagFileMembers(QXmlStreamWriter& writer, const Aggreg
                 QStringList pieces = gen_->fullDocumentLocation(node, false).split(QLatin1Char('#'));
                 writer.writeTextElement("anchorfile", pieces[0]);
                 writer.writeTextElement("anchor", pieces[1]);
-                QString signature = functionNode->signature();
+                QString signature = functionNode->signature(false);
                 signature = signature.mid(signature.indexOf(QChar('('))).trimmed();
                 if (functionNode->isConst())
                     signature += " const";