QDoc: Warn when generating a file multiple times per project

When generating documentation, QDoc may overwrite files that exist in
the output directory. This behavior is wanted; previously QDoc warned
for each overwrite, making the warning count between multiple
documentation builds not representable. However, users rely on QDocs
traditional warning output and are unlikely to notice debug log
messages.

This change makes QDoc issue a warning when obtaining a file handle for
an output file if that file is known to have been generated previously
in the current execution. It also introduces a new environment variable
`QDOC_ALL_OVERWRITES_ARE_WARNINGS`, to allow the enforcement of QDoc's
past behavior of unconditionally warning instead of debug logging these
events.

The QDoc manual is updated accordingly.

Fixes: QTBUG-121437
Pick-to: 6.5
Change-Id: I834027201197039bb4591e633bf72845e8a4343c
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit 54e5d595b7400730546335ffa02bf2ea95b2fcef)
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 35860c9c196f1f6174f7c0601edb1ed3fb5c5a64)

2 files changed, 23 insertions, 2 deletions

diff --git a/src/qdoc/qdoc/doc/qdoc-warnings.qdoc b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc
index f9968fc09..66176122b 100644
--- a/src/qdoc/qdoc/doc/qdoc-warnings.qdoc
+++ b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc
@@ -797,4 +797,17 @@
     .qdocconf file.
 
     See also \l{Creating Help Project Files} and \l {qhp-variable}{qhp}.
+
+    \section1 Already generated FILE for this project
+
+    While generating the documentation for a project, QDoc keeps track of the
+    file names of the files it has generated. QDoc will issue a warning when it
+    opens a file for writing if that file is known to have been generated
+    previously, in the current execution. This can happen if a \qdoccmd page
+    command uses the same name as \qdoccmd group, for example.
+
+    You can set the environment variable \c QDOC_ALL_OVERWRITES_ARE_WARNINGS to
+    unconditionally warn about all such events. This may be useful when tracking
+    down the offending definitions.
+
 */
diff --git a/src/qdoc/qdoc/generator.cpp b/src/qdoc/qdoc/generator.cpp
index 7630b717b..7b6c46da2 100644
--- a/src/qdoc/qdoc/generator.cpp
+++ b/src/qdoc/qdoc/generator.cpp
@@ -193,6 +193,9 @@ int Generator::appendSortedQmlNames(Text &text, const Node *base, const NodeList
  */
 QFile *Generator::openSubPageFile(const Node *node, const QString &fileName)
 {
+    if (s_outFileNames.contains(fileName))
+        node->location().warning("Already generated %1 for this project"_L1.arg(fileName));
+
     QString path = outputDir() + QLatin1Char('/');
     if (Generator::useOutputSubdirs() && !node->outputSubdirectory().isEmpty()
         && !outputDir().endsWith(node->outputSubdirectory())) {
@@ -203,8 +206,13 @@ QFile *Generator::openSubPageFile(const Node *node, const QString &fileName)
     auto outPath = s_redirectDocumentationToDevNull ? QStringLiteral("/dev/null") : path;
     auto outFile = new QFile(outPath);
 
-    if (!s_redirectDocumentationToDevNull && outFile->exists())
-        qCDebug(lcQdoc) << "Output file already exists; overwriting" << qPrintable(outFile->fileName());
+    if (!s_redirectDocumentationToDevNull && outFile->exists()) {
+        const QString warningText {"Output file already exists, overwriting %1"_L1.arg(outFile->fileName())};
+        if (qEnvironmentVariableIsSet("QDOC_ALL_OVERWRITES_ARE_WARNINGS"))
+            node->location().warning(warningText);
+        else
+            qCDebug(lcQdoc) << qUtf8Printable(warningText);
+    }
 
     if (!outFile->open(QFile::WriteOnly | QFile::Text)) {
         node->location().fatal(