qdoc: Don't output undocumented functions from Q_OBJECT

Earlier, a test was added to qdoc to ensure that functions added
to class declarations by macros like Q_OBJECT would not cause qdoc
to output warnings that the functions were not documented. But the
undocumented functions were still listed in the documentation. This
update keeps them out of the documentation.

Task-number: QTBUG-66742
Change-Id: I10014341fc7b870ef937ef7f0a303ccc301bf8b5
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

4 files changed, 38 insertions, 18 deletions

diff --git a/src/qdoc/cppcodemarker.cpp b/src/qdoc/cppcodemarker.cpp
index 5bd64ca87..17694e201 100644
--- a/src/qdoc/cppcodemarker.cpp
+++ b/src/qdoc/cppcodemarker.cpp
@@ -560,6 +560,10 @@ QList<Section> CppCodeMarker::sections(const Aggregate *inner,
                             ++c;
                             continue;
                         }
+                        else if (func->isIgnored()) {
+                            ++c;
+                            continue;
+                        }
                     }
                     else if ((*c)->type() == Node::Variable) {
                         const VariableNode *var = static_cast<const VariableNode *>(*c);
@@ -700,6 +704,10 @@ QList<Section> CppCodeMarker::sections(const Aggregate *inner,
                         insert(memberVariables, *c, style, status);
                 } else if ((*c)->isFunction()) {
                     FunctionNode *function = static_cast<FunctionNode *>(*c);
+                    if (function->isIgnored()) {
+                        ++c;
+                        continue;
+                    }
                     if (!function->isSharingComment()) {
                         if (!function->hasAssociatedProperties() || !function->doc().isEmpty())
                             insert(memberFunctions, function, style, status);
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 1256477c2..1e28ce5ef 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -836,24 +836,7 @@ void Generator::generateBody(const Node *node, CodeMarker *marker)
                 out() << "</p>";
             }
             else if (!node->isWrapper() && !quiet && !node->isReimplemented()) {
-                bool report = true;
-                /*
-                  These are the member function names added by macros.
-                  Usually they are not documented, but they can be
-                  documented, so this test avoids reporting an error
-                  if they are not documented.
-
-                  But maybe we should generate a standard text for each
-                  of them?
-                 */
-                if (node->name().startsWith(QLatin1String("qt_")) ||
-                    node->name() == QLatin1String("metaObject") ||
-                    node->name() == QLatin1String("tr") ||
-                    node->name() == QLatin1String("trUtf8") ||
-                    node->name() == QLatin1String("d_func")) {
-                    report = false;
-                }
-                if (report)
+                if (!func->isIgnored()) // undocumented functions added by Q_OBJECT
                     node->location().warning(tr("No documentation for '%1'").arg(node->plainSignature()));
             }
         }
diff --git a/src/qdoc/node.cpp b/src/qdoc/node.cpp
index 7e3b2d96a..de2fec53d 100644
--- a/src/qdoc/node.cpp
+++ b/src/qdoc/node.cpp
@@ -2482,6 +2482,34 @@ bool FunctionNode::compare(const FunctionNode *fn) const
 }
 
 /*!
+  In some cases, it is ok for a public function to be not documented.
+  For example, the macro Q_OBJECT adds several functions to the API of
+  a class, but these functions are normally not meant to be documented.
+  So if a function node doesn't have documentation, then if its name is
+  in the list of functions that it is ok not to document, this function
+  returns true. Otherwise, it returns false.
+
+  These are the member function names added by macros.  Usually they
+  are not documented, but they can be documented, so this test avoids
+  reporting an error if they are not documented.
+
+  But maybe we should generate a standard text for each of them?
+ */
+bool FunctionNode::isIgnored() const
+{
+    if (!hasDoc() && !hasSharedDoc()) {
+        if (name().startsWith(QLatin1String("qt_")) ||
+            name() == QLatin1String("metaObject") ||
+            name() == QLatin1String("tr") ||
+            name() == QLatin1String("trUtf8") ||
+            name() == QLatin1String("d_func")) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/*!
   \class PropertyNode
 
   This class describes one instance of using the Q_PROPERTY macro.
diff --git a/src/qdoc/node.h b/src/qdoc/node.h
index 38fc99f03..14c214e93 100644
--- a/src/qdoc/node.h
+++ b/src/qdoc/node.h
@@ -1058,6 +1058,7 @@ public:
     void setTag(const QString& t) { tag_ = t; }
     const QString &tag() const { return tag_; }
     bool compare(const FunctionNode *fn) const;
+    bool isIgnored() const;
 
 private:
     void addAssociatedProperty(PropertyNode* property);