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

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