QDoc: Move parseFnArg out of ClangCodeParser

When QDoc processes a project, it parses its code-base to obtain and
sanitize the user-provided documentation for the project.

For projects that makes use of C++ code, QDoc uses Clang's APIs to
obtain the required information about the code-base.

Profiling shows that calls to Clang are the major bottleneck in QDoc at
the current time.

To reduce the time spent by Clang, QDoc is being moved to parallelize
and batch certain operations that are related to Clang calls.

`ClangCodeParser`, the component responsible for all of the calls to
Clang libraries, is currently architectured in a way that is not usable
for those optimization purposes.

Hence, it is slowly being modified to be better suited for those
purposes.
As part of those modification, we expect `ClangCodeParser` to be split
into multiple components.

Currently, `ClangCodeParser` is the entry point to a series of
operations that happen in different phases and have very different
restriction on their scopes and their dependencies.

To fullfill and simplify the parallelization efforts, those operations
are being split up to so that we can reorganize their order and
restrictions.

When QDoc parses a project, it extracts the user-provided block-comments
that comprise the documentation.

Later, it processes them in multiple ways.
For example, it ties a documentation block to a `Node`, an internal
representation for documentable elements, by examining the usage of "topic
commands" in the block.

For "\fn" commands, which are used to document a C++ callable, QDoc
makes calls to Clang's APIs to parse the argument of the command so that
it can later compare it to the internal representation that QDoc built
of the code-base.

This is performed by `ClangCodeParser::parseFnArg` which is called by
`CppCodeParser`, which is the component responsible for processing
documentation blocks.

`parseFnArg` calls are intended, later on, to be batched for performance
reasons, albeit they are not expected to be parallelized at this point.

Hence, we move `parseFnArg` out of `ClangCodeParser` to simplify those
feature developments by having more control over which parts of
`ClangCodeParser` receive which changes.

`parseFnArg` was removed and replaced with the call operator of a new
class, `FnCommandParser`, a component that will only take care of
processing "\fn" commands.

`CppCodeParser`, which depended implicitly upon `ClangCodeParser` to
call `parseFnArg`, was modified to depend on `FnCommandParser`
explicitly.

The main loop of QDoc was modified to create and pass around an instance
of `FnCommandParser` as needed.

Task-number: QTBUG-111686
Change-Id: I517bd0d62b348ca39c4a8c10c4c2d78ab7c5ae15
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

1 files changed, 31 insertions, 3 deletions

diff --git a/src/qdoc/qdoc/src/qdoc/clangcodeparser.h b/src/qdoc/qdoc/src/qdoc/clangcodeparser.h
index 2318a048d..e6d78c719 100644
--- a/src/qdoc/qdoc/src/qdoc/clangcodeparser.h
+++ b/src/qdoc/qdoc/src/qdoc/clangcodeparser.h
@@ -4,8 +4,7 @@
 #ifndef CLANGCODEPARSER_H
 #define CLANGCODEPARSER_H
 
-#include "cppcodeparser.h"
-
+#include "codeparser.h"
 #include "config.h"
 
 #include <QtCore/qtemporarydir.h>
@@ -15,6 +14,8 @@
 
 typedef struct CXTranslationUnitImpl *CXTranslationUnit;
 
+class CppCodeParser;
+
 QT_BEGIN_NAMESPACE
 
 struct ParsedCppFileIR {
@@ -35,6 +36,34 @@ std::optional<PCHFile> buildPCH(
     const QList<QByteArray>& defines
 );
 
+struct FnCommandParser {
+    FnCommandParser(
+        QDocDatabase* qdb,
+        const std::set<Config::HeaderFilePath>& all_headers,
+        const QList<QByteArray>& defines,
+        std::optional<std::reference_wrapper<const PCHFile>> pch
+    ) : m_qdb{qdb},
+        m_allHeaders{all_headers},
+        m_defines{defines},
+        m_args{},
+        m_pch{pch}
+    {}
+
+    Node *operator()(
+        const Location &location,
+        const QString &fnSignature,
+        const QString &idTag,
+        QStringList context
+   );
+
+private:
+    QDocDatabase* m_qdb;
+    const std::set<Config::HeaderFilePath>& m_allHeaders; // file name->path
+    QList<QByteArray> m_defines {};
+    std::vector<const char *> m_args {};
+    std::optional<std::reference_wrapper<const PCHFile>> m_pch;
+};
+
 class ClangCodeParser : public CodeParser
 {
 public:
@@ -52,7 +81,6 @@ public:
     QStringList sourceFileNameFilter() override;
     void parseSourceFile(const Location &, const QString &, CppCodeParser&) override {}
     ParsedCppFileIR parse_cpp_file(const QString &filePath);
-    Node *parseFnArg(const Location &location, const QString &fnSignature, const QString &idTag, QStringList context);
 
 private:
     std::set<Config::HeaderFilePath> m_allHeaders {}; // file name->path