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.

Fixes: QTBUG-112256
Change-Id: I74fcc704f6848fc1eef8529da80f57678a83766e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 65e94d012b7d38669e9cdc4e885bdc34a86607af)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 20 insertions, 3 deletions

diff --git a/src/qdoc/doc/qdoc-warnings.qdoc b/src/qdoc/doc/qdoc-warnings.qdoc
index 25ac050b0..e9e0b2c80 100644
--- a/src/qdoc/doc/qdoc-warnings.qdoc
+++ b/src/qdoc/doc/qdoc-warnings.qdoc
@@ -785,4 +785,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 b2509f71e..ec811554b 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -1075,9 +1075,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);
+            }
         }
     }
 }