qdoc: Warn about documented global functions that generate no docs

Generator::generateDocumentation() recursively traverses the tree of
PageNode objects, i.e. nodes that generate output. However, it did
not check if there are documented nodes in the global scope (root
namespace) that generate no output.

A typical case where this happens is global functions, where the
author forgot to associate the function to something using the
\relates command.

Make QDoc print out a warning for these nodes, and mark them
to have 'DontDocument' status so they will be ignored later on
for linking and inclusion in the .qhp file.

Also in Generator::generateDocumentation(), rename a variable local
to a for-loop from 'node' to 'child', to prevent shadowing a 'node'
in the outer scope.

Pick-to: 6.5
Fixes: QTBUG-112256
Change-Id: I74fcc704f6848fc1eef8529da80f57678a83766e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

2 files changed, 20 insertions, 3 deletions

diff --git a/src/qdoc/doc/qdoc-warnings.qdoc b/src/qdoc/doc/qdoc-warnings.qdoc
index 69c76ede3..518f1255c 100644
--- a/src/qdoc/doc/qdoc-warnings.qdoc
+++ b/src/qdoc/doc/qdoc-warnings.qdoc
@@ -780,4 +780,14 @@
     \note Since content that is too long is not parsed in full, QDoc may
     issue warnings that are false positives. Resolve all warnings of this type
     before fixing other warnings.
+
+    \section1 No documentation generated for function <name> in global scope
+
+    QDoc was able to match the documentation for a function \e {<name>} to its
+    declaration, but no output was generated because the function is declared
+    in the global namespace.
+
+    Use the \l {relates-command}{\\relates} command to associate the function
+    with a documented type, namespace, or a header file. The function is then
+    listed as a \e {related non-member} on the associated reference page.
 */
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 3d1f420ee..9dfe88a0b 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -1079,9 +1079,16 @@ void Generator::generateDocumentation(Node *node)
     if (node->isAggregate()) {
         auto *aggregate = static_cast<Aggregate *>(node);
         const NodeList &children = aggregate->childNodes();
-        for (auto *node : children) {
-            if (node->isPageNode() && !node->isPrivate())
-                generateDocumentation(node);
+        for (auto *child : children) {
+            if (child->isPageNode() && !child->isPrivate()) {
+                generateDocumentation(child);
+            } else if (!node->parent() && child->isInAPI() && !child->isRelatedNonmember()) {
+                // Warn if there are documented non-page-generating nodes in the root namespace
+                child->location().warning(u"No documentation generated for %1 '%2' in global scope."_s
+                    .arg(typeString(child), child->name()),
+                            u"Maybe you forgot to use the '\\relates' command?"_s);
+                child->setStatus(Node::DontDocument);
+            }
         }
     }
 }