1// Copyright (C) 2021 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0
3
4#ifndef GENERATOR_H
5#define GENERATOR_H
6
7#include "text.h"
8#include "utilities.h"
9#include "filesystem/fileresolver.h"
10
11#include <QtCore/qlist.h>
12#include <QtCore/qmap.h>
13#include <QtCore/qstring.h>
14#include <QtCore/qstringlist.h>
15#include <QtCore/qtextstream.h>
16#include <optional>
17
18QT_BEGIN_NAMESPACE
19
20class Aggregate;
21class ClassNode;
22class CodeMarker;
23class CollectionNode;
24class ExampleNode;
25class FunctionNode;
26class INode;
27class Location;
28class Node;
29class PageNode;
30class QDocDatabase;
31class QmlTypeNode;
32
33struct RelatedClass;
34
35typedef QMultiMap<QString, Node *> NodeMultiMap;
36
37class Generator
38{
39public:
40 enum ListType { Generic, Obsolete };
41
42 enum Addendum {
43 Invokable,
44 PrivateSignal,
45 QmlSignalHandler,
46 AssociatedProperties,
47 BindableProperty,
48 OverloadNote
49 };
50
51 enum class AdmonitionPrefix : unsigned char
52 {
53 None,
54 Note
55 };
56
57 Generator(FileResolver& file_resolver);
58 virtual ~Generator();
59
60 virtual bool canHandleFormat(const QString &format) { return format == this->format(); }
61 virtual QString format() = 0;
62 virtual void generateDocs();
63 virtual void initializeGenerator();
64 virtual void initializeFormat();
65 virtual void terminateGenerator();
66 virtual QString typeString(const Node *node);
67
68 QString fullDocumentLocation(const Node *node);
69 QString linkForExampleFile(const QString &path, const QString &fileExt = QString());
70 static QString exampleFileTitle(const ExampleNode *relative, const QString &fileName);
71 static Generator *currentGenerator() { return s_currentGenerator; }
72 static Generator *generatorForFormat(const QString &format);
73 static void initialize();
74 static const QString &outputDir() { return s_outDir; }
75 static const QString &outputSubdir() { return s_outSubdir; }
76 static void terminate();
77 static const QStringList &outputFileNames() { return s_outFileNames; }
78 static bool noLinkErrors() { return s_noLinkErrors; }
79 static bool autolinkErrors() { return s_autolinkErrors; }
80 static QString defaultModuleName() { return s_project; }
81 static void resetUseOutputSubdirs() { s_useOutputSubdirs = false; }
82 static bool useOutputSubdirs() { return s_useOutputSubdirs; }
83 static void setQmlTypeContext(QmlTypeNode *t) { s_qmlTypeContext = t; }
84 static QmlTypeNode *qmlTypeContext() { return s_qmlTypeContext; }
85 static QString cleanRef(const QString &ref, bool xmlCompliant = false);
86 static QString plainCode(const QString &markedCode);
87 virtual QString fileBase(const Node *node) const;
88
89protected:
90 static QFile *openSubPageFile(const PageNode *node, const QString &fileName);
91 void beginSubPage(const Node *node, const QString &fileName);
92 void endSubPage();
93 [[nodiscard]] virtual QString fileExtension() const = 0;
94 virtual void generateExampleFilePage(const Node *, ResolvedFile, CodeMarker * = nullptr) {}
95 virtual void generateAlsoList(const Node *node, CodeMarker *marker);
96 virtual void generateAlsoList(const Node *node) { generateAlsoList(node, marker: nullptr); }
97 virtual qsizetype generateAtom(const Atom *, const Node *, CodeMarker *) { return 0; }
98 virtual void generateBody(const Node *node, CodeMarker *marker);
99 virtual void generateCppReferencePage(Aggregate *, CodeMarker *) {}
100 virtual void generateProxyPage(Aggregate *, CodeMarker *) {}
101 virtual void generateQmlTypePage(QmlTypeNode *, CodeMarker *) {}
102 virtual void generatePageNode(PageNode *, CodeMarker *) {}
103 virtual void generateCollectionNode(CollectionNode *, CodeMarker *) {}
104 virtual void generateGenericCollectionPage(CollectionNode *, CodeMarker *) {}
105 virtual void generateDocumentation(Node *node);
106 virtual bool generateText(const Text &text, const Node *relative, CodeMarker *marker);
107 virtual bool generateText(const Text &text, const Node *relative)
108 {
109 return generateText(text, relative, marker: nullptr);
110 };
111 virtual int skipAtoms(const Atom *atom, Atom::AtomType type) const;
112
113 static bool matchAhead(const Atom *atom, Atom::AtomType expectedAtomType);
114 static QString outputPrefix(const Node *node);
115 static QString outputSuffix(const Node *node);
116 static void supplementAlsoList(const Node *node, QList<Text> &alsoList);
117 static QString trimmedTrailing(const QString &string, const QString &prefix,
118 const QString &suffix);
119 void initializeTextOutput();
120 QString fileName(const Node *node, const QString &extension = QString()) const;
121 QMap<QString, QString> &formattingLeftMap();
122 QMap<QString, QString> &formattingRightMap();
123 const Atom *generateAtomList(const Atom *atom, const Node *relative, CodeMarker *marker,
124 bool generate, int &numGeneratedAtoms);
125 void generateEnumValuesForQmlReference(const Node *node, CodeMarker *marker);
126 void generateRequiredLinks(const Node *node, CodeMarker *marker);
127 void generateLinkToExample(const ExampleNode *en, CodeMarker *marker,
128 const QString &exampleUrl);
129 virtual void generateFileList(const ExampleNode *en, CodeMarker *marker, bool images);
130 static QString formatSince(const Node *node);
131 void generateSince(const Node *node, CodeMarker *marker);
132 void generateNoexceptNote(const Node *node, CodeMarker *marker);
133 void generateStatus(const Node *node, CodeMarker *marker);
134 virtual void generateAddendum(const Node *node, Addendum type, CodeMarker *marker,
135 AdmonitionPrefix prefix);
136 virtual void generateAddendum(const Node *node, Addendum type, CodeMarker *marker)
137 {
138 generateAddendum(node, type, marker, prefix: AdmonitionPrefix::Note);
139 };
140 void generateThreadSafeness(const Node *node, CodeMarker *marker);
141 bool generateComparisonCategory(const Node *node, CodeMarker *marker = nullptr);
142 bool generateComparisonList(const Node *node);
143
144 QString generateOverloadSnippet(const FunctionNode *func);
145 QString generateObjectName(const QString &className);
146
147 QString indent(int level, const QString &markedCode);
148 QTextStream &out();
149 QString outFileName();
150 bool parseArg(const QString &src, const QString &tag, int *pos, int n, QStringView *contents,
151 QStringView *par1 = nullptr);
152 void unknownAtom(const Atom *atom);
153 int appendSortedQmlNames(Text &text, const Node *base, const QStringList &knownTypes,
154 const QList<Node *> &subs);
155
156 static bool hasExceptions(const Node *node, QList<Node *> &reentrant, QList<Node *> &threadsafe,
157 QList<Node *> &nonreentrant);
158
159 QString naturalLanguage;
160 QString tagFile_;
161 QStack<QTextStream *> outStreamStack;
162
163 void appendFullName(Text &text, const Node *apparentNode, const Node *relative,
164 const Node *actualNode = nullptr);
165 void appendFullName(Text &text, const Node *apparentNode, const QString &fullName,
166 const Node *actualNode);
167 int appendSortedNames(Text &text, const ClassNode *classe,
168 const QList<RelatedClass> &classes);
169 void appendSignature(Text &text, const Node *node);
170 void signatureList(const QList<Node *> &nodes, const Node *relative, CodeMarker *marker);
171
172 void addImageToCopy(const ExampleNode *en, const ResolvedFile& resolved_file);
173 // TODO: This seems to be used as the predicate in std::sort calls.
174 // Remove it as it is unneeded.
175 // Indeed, it could be replaced by std::less and, furthermore,
176 // std::sort already defaults to operator< when no predicate is
177 // provided.
178 static bool comparePaths(const QString &a, const QString &b) { return (a < b); }
179 static bool appendTrademark(const Atom *atom);
180 static std::optional<std::pair<QString, QString>> cmakeRequisite(const CollectionNode *cn);
181
182public:
183 static Qt::SortOrder sortOrder(const QString &str)
184 {
185 return (str == "descending") ? Qt::DescendingOrder : Qt::AscendingOrder;
186 }
187
188 static void addNodeLink(Text &text, const QString &nodeRef, const QString &linkText);
189 static void addNodeLink(Text &text, const INode *node, const QString &linkText = QString());
190
191
192private:
193 static Generator *s_currentGenerator;
194 static QMap<QString, QMap<QString, QString>> s_fmtLeftMaps;
195 static QMap<QString, QMap<QString, QString>> s_fmtRightMaps;
196 static QList<Generator *> s_generators;
197 static QString s_project;
198 static QString s_outDir;
199 static QString s_outSubdir;
200 static QStringList s_outFileNames;
201 static QSet<QString> s_outputFormats;
202 static QSet<QString> s_trademarks;
203 static QHash<QString, QString> s_outputPrefixes;
204 static QHash<QString, QString> s_outputSuffixes;
205 static bool s_noLinkErrors;
206 static bool s_autolinkErrors;
207 static bool s_redirectDocumentationToDevNull;
208 static bool s_useOutputSubdirs;
209 static QmlTypeNode *s_qmlTypeContext;
210
211 void generateReimplementsClause(const FunctionNode *fn, CodeMarker *marker);
212 static void copyTemplateFiles(const QString &configVar, const QString &subDir);
213
214protected:
215 FileResolver& file_resolver;
216
217 QDocDatabase *m_qdb { nullptr };
218 bool m_inLink { false };
219 bool m_inContents { false };
220 bool m_inSectionHeading { false };
221 bool m_inTableHeader { false };
222 bool m_threeColumnEnumValueTable { true };
223 bool m_showInternal { false };
224 bool m_quoting { false };
225 int m_numTableRows { 0 };
226 QString m_link {};
227 QString m_sectionNumber {};
228};
229
230std::optional<QString> formatStatus(const Node *node, QDocDatabase *qdb);
231
232QT_END_NAMESPACE
233
234#endif
235

source code of qttools/src/qdoc/qdoc/src/qdoc/generator.h