qdoc: Make QDoc's output less noisy by default

By default, QDoc printed progress information such as

qt.qdoc: Start/Stop qdoc for <project> in <mode>
qt.qdoc: Parse source files for <project>

These do not provide much useful information, so hide them under the
--log-progress command line option. --debug now also implies
--log-progress.

Remove all uses of leftover debug statements that used qDebug(), or
where suitable, convert them to use logging category with qCDebug()
and friends.

Remove unused function FunctionNode::debug().

Clean up formatting and language for some of QDoc's output messages
in passing.

Fixes: QTBUG-110923
Change-Id: I2cab456b0e144249e4234a253fd1c90d76666132
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
(cherry picked from commit b2864f175fe21d8d4bd7e67fbc4bac61a5087228)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

11 files changed, 30 insertions, 59 deletions

diff --git a/src/qdoc/config.cpp b/src/qdoc/config.cpp
index b9a029fcb..4fef9529a 100644
--- a/src/qdoc/config.cpp
+++ b/src/qdoc/config.cpp
@@ -408,7 +408,7 @@ void Config::processCommandLineOptions(const QStringList &args)
         m_qdocPass = Prepare;
     if (m_parser.isSet(m_parser.generateOption))
         m_qdocPass = Generate;
-    if (m_parser.isSet(m_parser.logProgressOption))
+    if (m_debug || m_parser.isSet(m_parser.logProgressOption))
         setStringList(CONFIG_LOGPROGRESS, QStringList("true"));
     if (m_parser.isSet(m_parser.timestampsOption))
         setStringList(CONFIG_TIMESTAMPS, QStringList("true"));
@@ -1392,7 +1392,6 @@ QString Config::popWorkingDir()
     if (!m_workingDirs.isEmpty())
         return m_workingDirs.pop();
 
-    qDebug() << "RETURNED EMPTY WORKING DIR";
     return QString();
 }
 
diff --git a/src/qdoc/functionnode.cpp b/src/qdoc/functionnode.cpp
index 90cc73ec6..f212fdb47 100644
--- a/src/qdoc/functionnode.cpp
+++ b/src/qdoc/functionnode.cpp
@@ -443,15 +443,6 @@ QString FunctionNode::signature(bool values, bool noReturnType, bool templatePar
 }
 
 /*!
-  Print some information used for debugging qdoc. Only used when debugging.
- */
-void FunctionNode::debug() const
-{
-    qDebug("QML METHOD %s m_returnType %s m_parentPath %s", qPrintable(name()),
-           qPrintable(m_returnType), qPrintable(m_parentPath.join(' ')));
-}
-
-/*!
   Compares this FunctionNode to \a node. If \a sameParent is \c true, compares
   also the parent of the two nodes. Returns \c true if they describe
   the same function.
diff --git a/src/qdoc/functionnode.h b/src/qdoc/functionnode.h
index ec790b454..64f22307e 100644
--- a/src/qdoc/functionnode.h
+++ b/src/qdoc/functionnode.h
@@ -135,8 +135,6 @@ public:
         return parent()->logicalModuleIdentifier();
     }
 
-    void debug() const;
-
     void setFinal(bool b) { m_isFinal = b; }
     [[nodiscard]] bool isFinal() const { return m_isFinal; }
 
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 0f9470ad6..b2509f71e 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -1790,16 +1790,11 @@ QString Generator::outputSuffix(const Node *node)
 }
 
 bool Generator::parseArg(const QString &src, const QString &tag, int *pos, int n,
-                         QStringView *contents, QStringView *par1, bool debug)
+                         QStringView *contents, QStringView *par1)
 {
 #define SKIP_CHAR(c)                                                                               \
-    if (debug)                                                                                     \
-        qDebug() << "looking for " << c << " at " << QString(src.data() + i, n - i);               \
-    if (i >= n || src[i] != c) {                                                                   \
-        if (debug)                                                                                 \
-            qDebug() << " char '" << c << "' not found";                                           \
+    if (i >= n || src[i] != c)                                                                     \
         return false;                                                                              \
-    }                                                                                              \
     ++i;
 
 #define SKIP_SPACE                                                                                 \
@@ -1817,9 +1812,6 @@ bool Generator::parseArg(const QString &src, const QString &tag, int *pos, int n
         return false;
     }
 
-    if (debug)
-        qDebug() << "haystack:" << src << "needle:" << tag << "i:" << i;
-
     // skip tag
     i += tag.size();
 
@@ -1831,8 +1823,6 @@ bool Generator::parseArg(const QString &src, const QString &tag, int *pos, int n
         while (i < n && src[i].isLetter())
             ++i;
         if (src[i] == '=') {
-            if (debug)
-                qDebug() << "read parameter" << QString(src.data() + j, i - j);
             SKIP_CHAR('=');
             SKIP_CHAR('"');
             // skip parameter name
@@ -1842,9 +1832,6 @@ bool Generator::parseArg(const QString &src, const QString &tag, int *pos, int n
             *par1 = QStringView(src).mid(j, i - j);
             SKIP_CHAR('"');
             SKIP_SPACE;
-        } else {
-            if (debug)
-                qDebug() << "no optional parameter found";
         }
     }
     SKIP_SPACE;
@@ -1873,10 +1860,9 @@ bool Generator::parseArg(const QString &src, const QString &tag, int *pos, int n
     i += tag.size() + 4;
 
     *pos = i;
-    if (debug)
-        qDebug() << " tag " << tag << " found: pos now: " << i;
     return true;
 #undef SKIP_CHAR
+#undef SKIP_SPACE
 }
 
 QString Generator::plainCode(const QString &markedCode)
diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h
index 032a6fd75..cc59125f3 100644
--- a/src/qdoc/generator.h
+++ b/src/qdoc/generator.h
@@ -138,7 +138,7 @@ protected:
     QTextStream &out();
     QString outFileName();
     bool parseArg(const QString &src, const QString &tag, int *pos, int n, QStringView *contents,
-                  QStringView *par1 = nullptr, bool debug = false);
+                  QStringView *par1 = nullptr);
     void unknownAtom(const Atom *atom);
     int appendSortedQmlNames(Text &text, const Node *base, const NodeList &subs);
 
diff --git a/src/qdoc/main.cpp b/src/qdoc/main.cpp
index 0add31ccc..cdea4c8b9 100644
--- a/src/qdoc/main.cpp
+++ b/src/qdoc/main.cpp
@@ -132,11 +132,13 @@ static void loadIndexFiles(const QSet<QString> &formats)
                     }
                 }
                 // Remove self-dependencies and possible duplicates
-                config.dependModules().removeAll(config.getString(CONFIG_PROJECT).toLower());
+                QString project{config.getString(CONFIG_PROJECT)};
+                config.dependModules().removeAll(project.toLower());
                 config.dependModules().removeDuplicates();
-                qCCritical(lcQdoc) << "qdocconf file has depends = *; loading all "
+                qCCritical(lcQdoc) << "Configuration file for"
+                               << project << "has depends = *; loading all"
                                << config.dependModules().size()
-                               << " index files found";
+                               << "index files found";
             }
             for (const auto &module : config.dependModules()) {
                 QList<QFileInfo> foundIndices;
@@ -206,10 +208,14 @@ static void loadIndexFiles(const QSet<QString> &formats)
     Prints to stderr the name of the project that QDoc is running for,
     in which mode and which phase.
 
-    If QDoc is running in debug mode, also logs the command line arguments.
+    If QDoc is not running in debug mode or --log-progress command line
+    option is not set, do nothing.
  */
 void logStartEndMessage(const QLatin1String &startStop, const Config &config)
 {
+    if (!config.getBool(CONFIG_LOGPROGRESS))
+        return;
+
     const QString runName = " qdoc for "
             + config.getString(CONFIG_PROJECT)
             + QLatin1String(" in ")
@@ -536,7 +542,8 @@ static void processQdocconfFile(const QString &fileName)
           Parse each source text file in the set using the appropriate parser and
           add it to the big tree.
         */
-        qCInfo(lcQdoc) << "Parse source files for" << project;
+        if (config.getBool(CONFIG_LOGPROGRESS))
+            qCInfo(lcQdoc) << "Parse source files for" << project;
         for (auto it = sources.cbegin(), end = sources.cend(); it != end; ++it) {
             const auto &key = it.key();
             auto *codeParser = CodeParser::parserForSourceFile(key);
@@ -545,7 +552,8 @@ static void processQdocconfFile(const QString &fileName)
                 codeParser->parseSourceFile(config.location(), key);
             }
         }
-        qCInfo(lcQdoc) << "Source files parsed for" << project;
+        if (config.getBool(CONFIG_LOGPROGRESS))
+            qCInfo(lcQdoc) << "Source files parsed for" << project;
     }
     /*
       Now the primary tree has been built from all the header and
@@ -670,14 +678,6 @@ int main(int argc, char **argv)
     translators.clear();
 #endif
     QmlTypeNode::terminate();
-
-#ifdef DEBUG_SHUTDOWN_CRASH
-    qDebug() << "main(): Delete qdoc database";
-#endif
     QDocDatabase::destroyQdocDB();
-#ifdef DEBUG_SHUTDOWN_CRASH
-    qDebug() << "main(): qdoc database deleted";
-#endif
-
     return Location::exitCode();
 }
diff --git a/src/qdoc/qdoccommandlineparser.cpp b/src/qdoc/qdoccommandlineparser.cpp
index 6f025576e..8d2395e29 100644
--- a/src/qdoc/qdoccommandlineparser.cpp
+++ b/src/qdoc/qdoccommandlineparser.cpp
@@ -182,5 +182,5 @@ void QDocCommandLineParser::process(const QStringList &arguments)
     QCommandLineParser::process(allArguments);
 
     if (isSet(singleExecOption) && isSet(indexDirOption))
-        qDebug("WARNING: -indexdir option ignored: Index files are not used in single-exec mode.");
+        qCWarning(lcQdoc) << "Warning: -indexdir option ignored: Index files are not used in single-exec mode.";
 }
diff --git a/src/qdoc/qdocdatabase.cpp b/src/qdoc/qdocdatabase.cpp
index b31348a76..49317aef3 100644
--- a/src/qdoc/qdocdatabase.cpp
+++ b/src/qdoc/qdocdatabase.cpp
@@ -127,7 +127,7 @@ void QDocForest::setPrimaryTree(const QString &t)
     m_primaryTree = findTree(T);
     m_forest.remove(T);
     if (m_primaryTree == nullptr)
-        qDebug() << "ERROR: Could not set primary tree to:" << t;
+        qCCritical(lcQdoc) << "Error: Could not set primary tree to" << t;
 }
 
 /*!
@@ -1234,7 +1234,7 @@ void QDocDatabase::readIndexes(const QStringList &indexFiles)
         if (!isLoaded(fn))
             filesToRead << file;
         else
-            qDebug() << "This index file is already in memory:" << file;
+            qCCritical(lcQdoc) << "Index file" << file << "is already in memory.";
     }
     QDocIndexFiles::qdocIndexFiles()->readIndexes(filesToRead);
 }
diff --git a/src/qdoc/qmlcodeparser.cpp b/src/qdoc/qmlcodeparser.cpp
index 0bf9b8486..22c1d1903 100644
--- a/src/qdoc/qmlcodeparser.cpp
+++ b/src/qdoc/qmlcodeparser.cpp
@@ -5,6 +5,7 @@
 
 #include "node.h"
 #include "qmlvisitor.h"
+#include "utilities.h"
 
 #ifndef QT_NO_DECLARATIVE
 #    include <private/qqmljsast_p.h>
@@ -87,8 +88,6 @@ void QmlCodeParser::parseSourceFile(const Location &location, const QString &fil
     QString document = in.readAll();
     in.close();
 
-    Location fileLocation(filePath);
-
     QString newCode = document;
     extractPragmas(newCode);
     m_lexer->setCode(newCode, 1);
@@ -98,17 +97,13 @@ void QmlCodeParser::parseSourceFile(const Location &location, const QString &fil
         QmlDocVisitor visitor(filePath, newCode, &m_engine, topicCommands() + commonMetaCommands(),
                               topicCommands());
         QQmlJS::AST::Node::accept(ast, &visitor);
-        if (visitor.hasError()) {
-            qDebug().nospace() << qPrintable(filePath) << ": Could not analyze QML file. "
-                               << "The output is incomplete.";
-        }
+        if (visitor.hasError())
+            Location(filePath).warning("Could not analyze QML file, output is incomplete.");
     }
     const auto &messages = m_parser->diagnosticMessages();
     for (const auto &msg : messages) {
-        qDebug().nospace() << qPrintable(filePath) << ':'
-                           << msg.loc.startLine << ": QML syntax error at col "
-                           << msg.loc.startColumn
-                           << ": " << qPrintable(msg.message);
+        qCDebug(lcQdoc, "%s: %d: %d: QML syntax error: %s", qUtf8Printable(filePath),
+                msg.loc.startLine, msg.loc.startColumn, qUtf8Printable(msg.message));
     }
     m_currentFile.clear();
 #else
diff --git a/src/qdoc/qmlvisitor.cpp b/src/qdoc/qmlvisitor.cpp
index 1e7218fd1..9e70a356a 100644
--- a/src/qdoc/qmlvisitor.cpp
+++ b/src/qdoc/qmlvisitor.cpp
@@ -11,6 +11,7 @@
 #include "qdocdatabase.h"
 #include "qmlpropertynode.h"
 #include "tokenizer.h"
+#include "utilities.h"
 
 #include <QtCore/qdebug.h>
 #include <QtCore/qfileinfo.h>
@@ -148,7 +149,7 @@ bool QmlDocVisitor::applyDocumentation(QQmlJS::SourceLocation location, Node *no
                             nodes.append(n);
                         }
                     } else
-                        qDebug() << "  FAILED TO PARSE QML PROPERTY:" << topic << args;
+                        qCDebug(lcQdoc) << "Failed to parse QML property:" << topic << args;
                 } else if (topic.endsWith(QLatin1String("method")) || topic == COMMAND_QMLSIGNAL) {
                     if (node->isFunction()) {
                         auto *fn = static_cast<FunctionNode *>(node);
diff --git a/tests/auto/qdoc/qdoccommandlineparser/CMakeLists.txt b/tests/auto/qdoc/qdoccommandlineparser/CMakeLists.txt
index 117abf67b..ef872534e 100644
--- a/tests/auto/qdoc/qdoccommandlineparser/CMakeLists.txt
+++ b/tests/auto/qdoc/qdoccommandlineparser/CMakeLists.txt
@@ -11,6 +11,7 @@ qt_internal_add_test(tst_qdoccommandlineparser
     WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" # special case
     SOURCES
         ../../../../src/qdoc/qdoccommandlineparser.cpp ../../../../src/qdoc/qdoccommandlineparser.h
+        ../../../../src/qdoc/utilities.cpp ../../../../src/qdoc/utilities.h
         tst_qdoccommandlineparser.cpp
     INCLUDE_DIRECTORIES
         ../../../../src/qdoc