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 AGGREGATE_H |
5 | #define AGGREGATE_H |
6 | |
7 | #include "pagenode.h" |
8 | |
9 | #include <optional> |
10 | |
11 | #include <QtCore/qglobal.h> |
12 | #include <QtCore/qstringlist.h> |
13 | |
14 | QT_BEGIN_NAMESPACE |
15 | |
16 | class FunctionNode; |
17 | class QmlTypeNode; |
18 | class QmlPropertyNode; |
19 | |
20 | class Aggregate : public PageNode |
21 | { |
22 | public: |
23 | [[nodiscard]] Node *findChildNode(const QString &name, Node::Genus genus, |
24 | int findFlags = 0) const; |
25 | Node *findNonfunctionChild(const QString &name, bool (Node::*)() const); |
26 | void findChildren(const QString &name, NodeVector &nodes) const; |
27 | FunctionNode *findFunctionChild(const QString &name, const Parameters ¶meters); |
28 | FunctionNode *findFunctionChild(const FunctionNode *clone); |
29 | |
30 | void normalizeOverloads(); |
31 | void markUndocumentedChildrenInternal(); |
32 | |
33 | [[nodiscard]] bool isAggregate() const override { return true; } |
34 | [[nodiscard]] const EnumNode *findEnumNodeForValue(const QString &enumValue) const; |
35 | |
36 | [[nodiscard]] qsizetype count() const { return m_children.size(); } |
37 | [[nodiscard]] const NodeList &childNodes() const { return m_children; } |
38 | const NodeList &nonfunctionList(); |
39 | [[nodiscard]] NodeList::ConstIterator constBegin() const { return m_children.constBegin(); } |
40 | [[nodiscard]] NodeList::ConstIterator constEnd() const { return m_children.constEnd(); } |
41 | |
42 | inline void setIncludeFile(const QString& include) { m_includeFile.emplace(args: include); } |
43 | // REMARK: Albeit not enforced at the API boundaries, |
44 | // downstream-user can assume that if there is a QString that was |
45 | // set, then that string is not empty. |
46 | [[nodiscard]] inline const std::optional<QString>& includeFile() const { return m_includeFile; } |
47 | |
48 | [[nodiscard]] QmlPropertyNode *hasQmlProperty(const QString &) const; |
49 | [[nodiscard]] QmlPropertyNode *hasQmlProperty(const QString &, bool attached) const; |
50 | virtual QmlTypeNode *qmlBaseNode() const { return nullptr; } |
51 | void addChildByTitle(Node *child, const QString &title); |
52 | void addChild(Node *child); |
53 | void adoptChild(Node *child); |
54 | void setOutputSubdirectory(const QString &t) override; |
55 | |
56 | FunctionMap &functionMap() { return m_functionMap; } |
57 | void findAllFunctions(NodeMapMap &functionIndex); |
58 | void findAllNamespaces(NodeMultiMap &namespaces); |
59 | void findAllAttributions(NodeMultiMap &attributions); |
60 | [[nodiscard]] bool hasObsoleteMembers() const; |
61 | void findAllObsoleteThings(); |
62 | void findAllClasses(); |
63 | void findAllSince(); |
64 | void resolveQmlInheritance(); |
65 | bool hasOverloads(const FunctionNode *fn) const; |
66 | void appendToRelatedByProxy(const NodeList &t) { m_relatedByProxy.append(l: t); } |
67 | NodeList &relatedByProxy() { return m_relatedByProxy; } |
68 | [[nodiscard]] QString typeWord(bool cap) const; |
69 | |
70 | protected: |
71 | Aggregate(NodeType type, Aggregate *parent, const QString &name) |
72 | : PageNode(type, parent, name) {} |
73 | ~Aggregate() override; |
74 | |
75 | private: |
76 | friend class Node; |
77 | void addFunction(FunctionNode *fn); |
78 | void adoptFunction(FunctionNode *fn, Aggregate *firstParent); |
79 | static bool isSameSignature(const FunctionNode *f1, const FunctionNode *f2); |
80 | void dropNonRelatedMembers(); |
81 | |
82 | protected: |
83 | NodeList m_children {}; |
84 | NodeList m_relatedByProxy {}; |
85 | FunctionMap m_functionMap {}; |
86 | |
87 | private: |
88 | // REMARK: The member indicates the name of a file where the |
89 | // aggregate can be found from, for example, an header file that |
90 | // declares a class. |
91 | // For aggregates such as classes we expect this to always be set |
92 | // to a non-empty string after the code-parsing phase. |
93 | // Indeed, currently, by default, QDoc always generates such a |
94 | // string using the name of the aggregate if no include file can |
95 | // be propagated from some of the parents. |
96 | // |
97 | // Nonetheless, we are still forced to make this an optional, as |
98 | // this will not be true for all Aggregates. |
99 | // |
100 | // For example, for namespaces, we don't seem to set an include |
101 | // file and indeed doing so wouldn't be particularly meaningful. |
102 | // |
103 | // It is possible to assume in later code, especially the |
104 | // generation phase, that at least some classes of aggregates |
105 | // always have a value set here but we should, for the moment, |
106 | // still check for the possibility of something not to be there, |
107 | // or warn if we decide to ignore that, to be compliant with the |
108 | // current interface, whose change would require deep changes to |
109 | // QDoc internal structures. |
110 | std::optional<QString> m_includeFile{}; |
111 | NodeList m_enumChildren {}; |
112 | NodeMultiMap m_nonfunctionMap {}; |
113 | NodeList m_nonfunctionList {}; |
114 | }; |
115 | |
116 | QT_END_NAMESPACE |
117 | |
118 | #endif // AGGREGATE_H |
119 | |