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

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