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 NODE_H
5#define NODE_H
6
7#include "access.h"
8#include "doc.h"
9#include "enumitem.h"
10#include "importrec.h"
11#include "parameters.h"
12#include "relatedclass.h"
13
14#include <QtCore/qdir.h>
15#include <QtCore/qlist.h>
16#include <QtCore/qmap.h>
17#include <QtCore/qstringlist.h>
18
19QT_BEGIN_NAMESPACE
20
21class Aggregate;
22class ClassNode;
23class CollectionNode;
24class EnumNode;
25class ExampleNode;
26class FunctionNode;
27class Node;
28class QDocDatabase;
29class QmlTypeNode;
30class PageNode;
31class PropertyNode;
32class QmlPropertyNode;
33class SharedCommentNode;
34class Tree;
35class TypedefNode;
36
37typedef QMap<QString, FunctionNode *> FunctionMap;
38typedef QList<Node *> NodeList;
39typedef QList<ClassNode *> ClassList;
40typedef QList<Node *> NodeVector;
41typedef QMap<QString, Node *> NodeMap;
42typedef QMap<QString, NodeMap> NodeMapMap;
43typedef QMultiMap<QString, Node *> NodeMultiMap;
44typedef QMap<QString, NodeMultiMap> NodeMultiMapMap;
45typedef QMap<QString, CollectionNode *> CNMap;
46typedef QMultiMap<QString, CollectionNode *> CNMultiMap;
47
48class Node
49{
50public:
51 enum NodeType : unsigned char {
52 NoType,
53 Namespace,
54 Class,
55 Struct,
56 Union,
57 HeaderFile,
58 Page,
59 Enum,
60 Example,
61 ExternalPage,
62 Function,
63 Typedef,
64 TypeAlias,
65 Property,
66 Variable,
67 Group,
68 Module,
69 QmlType,
70 QmlModule,
71 QmlProperty,
72 QmlValueType,
73 SharedComment,
74 Collection,
75 Proxy
76 };
77
78 enum Genus : unsigned char {
79 DontCare = 0x0,
80 CPP = 0x1,
81 QML = 0x4,
82 DOC = 0x8,
83 API = CPP | QML
84 };
85
86 enum Status : unsigned char {
87 Deprecated,
88 Preliminary,
89 Active,
90 Internal,
91 DontDocument
92 }; // don't reorder this enum
93
94 enum ThreadSafeness : unsigned char {
95 UnspecifiedSafeness,
96 NonReentrant,
97 Reentrant,
98 ThreadSafe
99 };
100
101 enum SignatureOption : unsigned char {
102 SignaturePlain = 0x0,
103 SignatureDefaultValues = 0x1,
104 SignatureReturnType = 0x2,
105 SignatureTemplateParams = 0x4
106 };
107 Q_DECLARE_FLAGS(SignatureOptions, SignatureOption)
108
109 enum LinkType : unsigned char { StartLink, NextLink, PreviousLink, ContentsLink };
110
111 enum FlagValue { FlagValueDefault = -1, FlagValueFalse = 0, FlagValueTrue = 1 };
112
113 virtual ~Node() = default;
114 virtual Node *clone(Aggregate *) { return nullptr; } // currently only FunctionNode
115 [[nodiscard]] virtual Tree *tree() const;
116 [[nodiscard]] Aggregate *root() const;
117
118 [[nodiscard]] NodeType nodeType() const { return m_nodeType; }
119 [[nodiscard]] QString nodeTypeString() const;
120
121 [[nodiscard]] Genus genus() const { return m_genus; }
122 void setGenus(Genus t) { m_genus = t; }
123 static Genus getGenus(NodeType t);
124
125 [[nodiscard]] bool isActive() const { return m_status == Active; }
126 [[nodiscard]] bool isClass() const { return m_nodeType == Class; }
127 [[nodiscard]] bool isCppNode() const { return genus() == CPP; }
128 [[nodiscard]] bool isDontDocument() const { return (m_status == DontDocument); }
129 [[nodiscard]] bool isEnumType() const { return m_nodeType == Enum; }
130 [[nodiscard]] bool isExample() const { return m_nodeType == Example; }
131 [[nodiscard]] bool isExternalPage() const { return m_nodeType == ExternalPage; }
132 [[nodiscard]] bool isFunction(Genus g = DontCare) const
133 {
134 return m_nodeType == Function && (genus() == g || g == DontCare);
135 }
136 [[nodiscard]] bool isGroup() const { return m_nodeType == Group; }
137 [[nodiscard]] bool isHeader() const { return m_nodeType == HeaderFile; }
138 [[nodiscard]] bool isIndexNode() const { return m_indexNodeFlag; }
139 [[nodiscard]] bool isModule() const { return m_nodeType == Module; }
140 [[nodiscard]] bool isNamespace() const { return m_nodeType == Namespace; }
141 [[nodiscard]] bool isPage() const { return m_nodeType == Page; }
142 [[nodiscard]] bool isPreliminary() const { return (m_status == Preliminary); }
143 [[nodiscard]] bool isPrivate() const { return m_access == Access::Private; }
144 [[nodiscard]] bool isProperty() const { return m_nodeType == Property; }
145 [[nodiscard]] bool isProxyNode() const { return m_nodeType == Proxy; }
146 [[nodiscard]] bool isPublic() const { return m_access == Access::Public; }
147 [[nodiscard]] bool isProtected() const { return m_access == Access::Protected; }
148 [[nodiscard]] bool isQmlBasicType() const { return m_nodeType == QmlValueType; }
149 [[nodiscard]] bool isQmlModule() const { return m_nodeType == QmlModule; }
150 [[nodiscard]] bool isQmlNode() const { return genus() == QML; }
151 [[nodiscard]] bool isQmlProperty() const { return m_nodeType == QmlProperty; }
152 [[nodiscard]] bool isQmlType() const { return m_nodeType == QmlType || m_nodeType == QmlValueType; }
153 [[nodiscard]] bool isRelatedNonmember() const { return m_relatedNonmember; }
154 [[nodiscard]] bool isStruct() const { return m_nodeType == Struct; }
155 [[nodiscard]] bool isSharedCommentNode() const { return m_nodeType == SharedComment; }
156 [[nodiscard]] bool isTypeAlias() const { return m_nodeType == TypeAlias; }
157 [[nodiscard]] bool isTypedef() const
158 {
159 return m_nodeType == Typedef || m_nodeType == TypeAlias;
160 }
161 [[nodiscard]] bool isUnion() const { return m_nodeType == Union; }
162 [[nodiscard]] bool isVariable() const { return m_nodeType == Variable; }
163 [[nodiscard]] bool isGenericCollection() const { return (m_nodeType == Node::Collection); }
164
165 [[nodiscard]] virtual bool isDeprecated() const { return (m_status == Deprecated); }
166 [[nodiscard]] virtual bool isAbstract() const { return false; }
167 [[nodiscard]] virtual bool isAggregate() const { return false; } // means "can have children"
168 [[nodiscard]] virtual bool isFirstClassAggregate() const
169 {
170 return false;
171 } // Aggregate but not proxy or prop group"
172 [[nodiscard]] virtual bool isAlias() const { return false; }
173 [[nodiscard]] virtual bool isAttached() const { return false; }
174 [[nodiscard]] virtual bool isClassNode() const { return false; }
175 [[nodiscard]] virtual bool isCollectionNode() const { return false; }
176 [[nodiscard]] virtual bool isDefault() const { return false; }
177 [[nodiscard]] virtual bool isInternal() const;
178 [[nodiscard]] virtual bool isMacro() const { return false; }
179 [[nodiscard]] virtual bool isPageNode() const { return false; } // means "generates a doc page"
180 [[nodiscard]] virtual bool isQtQuickNode() const { return false; }
181 [[nodiscard]] virtual bool isRelatableType() const { return false; }
182 [[nodiscard]] virtual bool isMarkedReimp() const { return false; }
183 [[nodiscard]] virtual bool isPropertyGroup() const { return false; }
184 [[nodiscard]] virtual bool isStatic() const { return false; }
185 [[nodiscard]] virtual bool isTextPageNode() const
186 {
187 return false;
188 } // means PageNode but not Aggregate
189 [[nodiscard]] virtual bool isWrapper() const;
190
191 [[nodiscard]] QString plainName() const;
192 QString plainFullName(const Node *relative = nullptr) const;
193 [[nodiscard]] QString plainSignature() const;
194 QString fullName(const Node *relative = nullptr) const;
195 [[nodiscard]] virtual QString signature(Node::SignatureOptions) const { return plainName(); }
196
197 [[nodiscard]] const QString &fileNameBase() const { return m_fileNameBase; }
198 [[nodiscard]] bool hasFileNameBase() const { return !m_fileNameBase.isEmpty(); }
199 void setFileNameBase(const QString &t) { m_fileNameBase = t; }
200
201 void setAccess(Access t) { m_access = t; }
202 void setLocation(const Location &t);
203 void setDoc(const Doc &doc, bool replace = false);
204 void setStatus(Status t);
205 void setThreadSafeness(ThreadSafeness t) { m_safeness = t; }
206 void setSince(const QString &since);
207 void setPhysicalModuleName(const QString &name) { m_physicalModuleName = name; }
208 void setUrl(const QString &url) { m_url = url; }
209 void setTemplateDecl(const QString &t) { m_templateDecl = t; }
210 void setReconstitutedBrief(const QString &t) { m_reconstitutedBrief = t; }
211 void setParent(Aggregate *n) { m_parent = n; }
212 void setIndexNodeFlag(bool isIndexNode = true) { m_indexNodeFlag = isIndexNode; }
213 void setHadDoc() { m_hadDoc = true; }
214 virtual void setRelatedNonmember(bool b) { m_relatedNonmember = b; }
215 virtual void addMember(Node *) {}
216 [[nodiscard]] virtual bool hasNamespaces() const { return false; }
217 [[nodiscard]] virtual bool hasClasses() const { return false; }
218 virtual void setAbstract(bool) {}
219 virtual void setWrapper() {}
220 virtual void setDataType(const QString &) {}
221 [[nodiscard]] virtual bool wasSeen() const { return false; }
222 virtual void appendGroupName(const QString &) {}
223 [[nodiscard]] virtual QString element() const { return QString(); }
224 [[nodiscard]] virtual bool docMustBeGenerated() const { return false; }
225
226 [[nodiscard]] virtual QString title() const { return name(); }
227 [[nodiscard]] virtual QString subtitle() const { return QString(); }
228 [[nodiscard]] virtual QString fullTitle() const { return name(); }
229 virtual bool setTitle(const QString &) { return false; }
230 virtual bool setSubtitle(const QString &) { return false; }
231
232 void markInternal()
233 {
234 setAccess(Access::Private);
235 setStatus(Internal);
236 }
237 virtual void markDefault() {}
238 virtual void markReadOnly(bool) {}
239
240 [[nodiscard]] Aggregate *parent() const { return m_parent; }
241 [[nodiscard]] const QString &name() const { return m_name; }
242 [[nodiscard]] QString physicalModuleName() const { return m_physicalModuleName; }
243 [[nodiscard]] QString url() const { return m_url; }
244 virtual void setQtVariable(const QString &) {}
245 [[nodiscard]] virtual QString qtVariable() const { return QString(); }
246 virtual void setQtCMakeComponent(const QString &) {}
247 [[nodiscard]] virtual QString qtCMakeComponent() const { return QString(); }
248 [[nodiscard]] virtual bool hasTag(const QString &) const { return false; }
249
250 void setDeprecatedSince(const QString &sinceVersion);
251 [[nodiscard]] const QString &deprecatedSince() const { return m_deprecatedSince; }
252
253 [[nodiscard]] const QMap<LinkType, std::pair<QString, QString>> &links() const { return m_linkMap; }
254 void setLink(LinkType linkType, const QString &link, const QString &desc);
255
256 [[nodiscard]] Access access() const { return m_access; }
257 [[nodiscard]] const Location &declLocation() const { return m_declLocation; }
258 [[nodiscard]] const Location &defLocation() const { return m_defLocation; }
259 [[nodiscard]] const Location &location() const
260 {
261 return (m_defLocation.isEmpty() ? m_declLocation : m_defLocation);
262 }
263 [[nodiscard]] const Doc &doc() const { return m_doc; }
264 [[nodiscard]] bool isInAPI() const
265 {
266 return !isPrivate() && !isInternal() && !isDontDocument() && hasDoc();
267 }
268 [[nodiscard]] bool hasDoc() const { return (m_hadDoc || !m_doc.isEmpty()); }
269 [[nodiscard]] bool hadDoc() const { return m_hadDoc; }
270 [[nodiscard]] Status status() const { return m_status; }
271 [[nodiscard]] ThreadSafeness threadSafeness() const;
272 [[nodiscard]] ThreadSafeness inheritedThreadSafeness() const;
273 [[nodiscard]] QString since() const { return m_since; }
274 [[nodiscard]] const QString &templateDecl() const { return m_templateDecl; }
275 [[nodiscard]] const QString &reconstitutedBrief() const { return m_reconstitutedBrief; }
276
277 [[nodiscard]] bool isSharingComment() const { return (m_sharedCommentNode != nullptr); }
278 [[nodiscard]] bool hasSharedDoc() const;
279 void setSharedCommentNode(SharedCommentNode *t) { m_sharedCommentNode = t; }
280 SharedCommentNode *sharedCommentNode() { return m_sharedCommentNode; }
281
282 [[nodiscard]] QString extractClassName(const QString &string) const;
283 [[nodiscard]] virtual QString qmlTypeName() const { return m_name; }
284 [[nodiscard]] virtual QString qmlFullBaseName() const { return QString(); }
285 [[nodiscard]] virtual QString logicalModuleName() const { return QString(); }
286 [[nodiscard]] virtual QString logicalModuleVersion() const { return QString(); }
287 [[nodiscard]] virtual QString logicalModuleIdentifier() const { return QString(); }
288
289 virtual void setLogicalModuleInfo(const QStringList &) {}
290 [[nodiscard]] virtual CollectionNode *logicalModule() const { return nullptr; }
291 virtual void setQmlModule(CollectionNode *) {}
292 virtual ClassNode *classNode() { return nullptr; }
293 virtual void setClassNode(ClassNode *) {}
294 [[nodiscard]] const QString &outputSubdirectory() const { return m_outSubDir; }
295 virtual void setOutputSubdirectory(const QString &t) { m_outSubDir = t; }
296 [[nodiscard]] QString fullDocumentName() const;
297 QString qualifyCppName();
298 QString qualifyQmlName();
299 QString qualifyWithParentName();
300
301 static FlagValue toFlagValue(bool b);
302 static bool fromFlagValue(FlagValue fv, bool defaultValue);
303 static QString nodeTypeString(NodeType t);
304 static bool nodeNameLessThan(const Node *first, const Node *second);
305
306protected:
307 Node(NodeType type, Aggregate *parent, QString name);
308
309private:
310 NodeType m_nodeType {};
311 Genus m_genus {};
312 Access m_access { Access::Public };
313 ThreadSafeness m_safeness { UnspecifiedSafeness };
314 Status m_status { Active };
315 bool m_indexNodeFlag : 1;
316 bool m_relatedNonmember : 1;
317 bool m_hadDoc : 1;
318
319 Aggregate *m_parent { nullptr };
320 SharedCommentNode *m_sharedCommentNode { nullptr };
321 QString m_name {};
322 Location m_declLocation {};
323 Location m_defLocation {};
324 Doc m_doc {};
325 QMap<LinkType, std::pair<QString, QString>> m_linkMap {};
326 QString m_fileNameBase {};
327 QString m_physicalModuleName {};
328 QString m_url {};
329 QString m_since {};
330 QString m_templateDecl {};
331 QString m_reconstitutedBrief {};
332 QString m_outSubDir {};
333 QString m_deprecatedSince {};
334};
335
336Q_DECLARE_OPERATORS_FOR_FLAGS(Node::SignatureOptions)
337
338QT_END_NAMESPACE
339
340#endif
341

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