QDoc: Extract helper functions from Generator to Utilities

This change adds a new Utilities namespace to QDoc. This namespace
holds QDoc-internal utility methods. The first few methods are
debugging methods extracted from Generator::. Generator is then changed
to make use of the same methods from Utilities.

As a concequence of this, Utilities is also introduced to
ClangCodeParser and main.

This enables further refactoring of several classes, including the
QDocCommandLineParser class. The purpose is to clarify dependencies and
reduce entanglement, so that QDoc's classes become easier to test.

Task-number: QTBUG-71176
Change-Id: I5838fc2d933f78db682cb6e4755d31bb48175fcb
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

8 files changed, 112 insertions, 32 deletions

diff --git a/src/qdoc/clangcodeparser.cpp b/src/qdoc/clangcodeparser.cpp
index c9bebd446..bbe3f9ba7 100644
--- a/src/qdoc/clangcodeparser.cpp
+++ b/src/qdoc/clangcodeparser.cpp
@@ -48,6 +48,7 @@
 #include "generator.h"
 #include "loggingcategory.h"
 #include "qdocdatabase.h"
+#include "utilities.h"
 
 #include <QtCore/qdebug.h>
 #include <QtCore/qelapsedtimer.h>
@@ -1536,7 +1537,7 @@ Node *ClangCodeParser::parseFnArg(const Location &location, const QString &fnArg
                                                                CXTranslationUnit_SkipFunctionBodies |
                                                                CXTranslationUnit_KeepGoing);
     // Change 2nd parameter to 1 to make clang report errors.
-    CXIndex index = clang_createIndex(1, Generator::debugging() ? 1 : 0);
+    CXIndex index = clang_createIndex(1, Utilities::debugging() ? 1 : 0);
 
     std::vector<const char *> args(std::begin(defaultArgs_), std::end(defaultArgs_));
     // Add the defines from the qdocconf file.
diff --git a/src/qdoc/generator.cpp b/src/qdoc/generator.cpp
index 87dba3d9f..3a2fc802d 100644
--- a/src/qdoc/generator.cpp
+++ b/src/qdoc/generator.cpp
@@ -87,28 +87,6 @@ static QLatin1String gt("&gt;");
 static QLatin1String lt("&lt;");
 static QLatin1String quot("&quot;");
 
-static inline void setDebugEnabled(bool v)
-{
-    const_cast<QLoggingCategory &>(lcQdoc()).setEnabled(QtDebugMsg, v);
-}
-
-void Generator::startDebugging(const QString &message)
-{
-    setDebugEnabled(true);
-    qCDebug(lcQdoc, "START DEBUGGING: %s", qPrintable(message));
-}
-
-void Generator::stopDebugging(const QString &message)
-{
-    qCDebug(lcQdoc, "STOP DEBUGGING: %s", qPrintable(message));
-    setDebugEnabled(false);
-}
-
-bool Generator::debugging()
-{
-    return lcQdoc().isEnabled(QtDebugMsg);
-}
-
 /*!
   Constructs the generator base class. Prepends the newly
   constructed generator to the list of output generators.
diff --git a/src/qdoc/generator.h b/src/qdoc/generator.h
index 27a65bc8a..05d54fa66 100644
--- a/src/qdoc/generator.h
+++ b/src/qdoc/generator.h
@@ -79,9 +79,6 @@ public:
     static const QStringList &outputFileNames() { return outFileNames_; }
     static void writeOutFileNames();
     static void augmentImageDirs(QSet<QString> &moreImageDirs);
-    static void startDebugging(const QString &message);
-    static void stopDebugging(const QString &message);
-    static bool debugging();
     static bool noLinkErrors() { return noLinkErrors_; }
     static bool autolinkErrors() { return autolinkErrors_; }
     static void setQDocPass(QDocPass t) { qdocPass_ = t; }
diff --git a/src/qdoc/main.cpp b/src/qdoc/main.cpp
index 623bb0228..efeb1f30a 100644
--- a/src/qdoc/main.cpp
+++ b/src/qdoc/main.cpp
@@ -43,6 +43,7 @@
 #include "qdocglobals.h"
 #include "qmlcodemarker.h"
 #include "qmlcodeparser.h"
+#include "utilities.h"
 #include "qtranslator.h"
 #include "tokenizer.h"
 #include "tree.h"
@@ -512,8 +513,8 @@ static void processQdocconfFile(const QString &fileName, Config &config)
     qdb->clearLinkCounts();
 
     qCDebug(lcQdoc, "Terminating qdoc classes");
-    if (Generator::debugging())
-        Generator::stopDebugging(project);
+    if (Utilities::debugging())
+        Utilities::stopDebugging(project);
 
     msg = "End qdoc for " + config.getString(CONFIG_PROJECT) + phase;
     Location::logToStdErrAlways(msg);
diff --git a/src/qdoc/qdoc.pro b/src/qdoc/qdoc.pro
index 9e58c691b..1edf1249f 100644
--- a/src/qdoc/qdoc.pro
+++ b/src/qdoc/qdoc.pro
@@ -61,7 +61,8 @@ HEADERS += atom.h \
            tree.h \
            webxmlgenerator.h \
            qdocglobals.h \
-           qdoccommandlineparser.h
+           qdoccommandlineparser.h \
+           utilities.h
 
 SOURCES += atom.cpp \
            clangcodeparser.cpp \
@@ -94,7 +95,8 @@ SOURCES += atom.cpp \
            yyindent.cpp \
            webxmlgenerator.cpp \
            qdocglobals.cpp \
-           qdoccommandlineparser.cpp
+           qdoccommandlineparser.cpp \
+           utilities.cpp
 
 ### QML/JS Parser ###
 
diff --git a/src/qdoc/qdoccommandlineparser.cpp b/src/qdoc/qdoccommandlineparser.cpp
index d5d809e4c..83dc4568f 100644
--- a/src/qdoc/qdoccommandlineparser.cpp
+++ b/src/qdoc/qdoccommandlineparser.cpp
@@ -31,6 +31,7 @@
 #include "config.h"
 #include "generator.h"
 #include "loggingcategory.h"
+#include "utilities.h"
 
 #include <QtCore/qdebug.h>
 #include <QtCore/qfile.h>
@@ -210,10 +211,10 @@ void QDocCommandLineParser::process(const QStringList &arguments, QDocGlobals &q
         config->overrideOutputFormats.insert(format);
     qdocGlobals.setNoLinkErrors(isSet(noLinkErrorsOption) || qEnvironmentVariableIsSet("QDOC_NOLINKERRORS"));
     qdocGlobals.setAutolinkErrors(isSet(autoLinkErrorsOption));
+
     if (isSet(debugOption))
-        Generator::startDebugging(QString("command line"));
+        Utilities::startDebugging(QString("command line"));
     qCDebug(lcQdoc).noquote() << "Arguments :" << QCoreApplication::arguments();
-
     if (isSet(prepareOption))
         Generator::setQDocPass(Generator::Prepare);
     if (isSet(generateOption))
diff --git a/src/qdoc/utilities.cpp b/src/qdoc/utilities.cpp
new file mode 100644
index 000000000..308bb2c66
--- /dev/null
+++ b/src/qdoc/utilities.cpp
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the tools applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL-EXCEPT$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 as published by the Free Software
+** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "utilities.h"
+#include "loggingcategory.h"
+
+/*!
+    \namespace Utilities
+    \internal
+    \brief This namespace holds QDoc-internal utility methods.
+ */
+namespace Utilities {
+    static inline void setDebugEnabled(bool value)
+    {
+        const_cast<QLoggingCategory &>(lcQdoc()).setEnabled(QtDebugMsg, value);
+    }
+
+    void startDebugging(const QString &message)
+    {
+        setDebugEnabled(true);
+        qCDebug(lcQdoc, "START DEBUGGING: %ls", qUtf16Printable(message));
+    }
+
+    void stopDebugging(const QString &message)
+    {
+        qCDebug(lcQdoc, "STOP DEBUGGING: %ls", qUtf16Printable(message));
+        setDebugEnabled(false);
+    }
+
+    bool debugging()
+    {
+        return lcQdoc().isEnabled(QtDebugMsg);
+    }
+}
diff --git a/src/qdoc/utilities.h b/src/qdoc/utilities.h
new file mode 100644
index 000000000..da848795e
--- /dev/null
+++ b/src/qdoc/utilities.h
@@ -0,0 +1,41 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the tools applications of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:GPL-EXCEPT$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3 as published by the Free Software
+** Foundation with exceptions as appearing in the file LICENSE.GPL3-EXCEPT
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef UTILITIES_H
+#define UTILITIES_H
+
+#include <QtCore/qstring.h>
+
+namespace Utilities
+{
+    void startDebugging(const QString &message);
+    void stopDebugging(const QString &message);
+    bool debugging();
+};
+
+#endif // UTILITIES_H