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
14QT_BEGIN_NAMESPACE
15
16class FunctionNode;
17class QmlTypeNode;
18class QmlPropertyNode;
19
20class Aggregate : public PageNode
21{
22public:
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 &parameters);
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
70protected:
71 Aggregate(NodeType type, Aggregate *parent, const QString &name)
72 : PageNode(type, parent, name) {}
73 ~Aggregate() override;
74
75private:
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
82protected:
83 NodeList m_children {};
84 NodeList m_relatedByProxy {};
85 FunctionMap m_functionMap {};
86
87private:
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
116QT_END_NAMESPACE
117
118#endif // AGGREGATE_H
119

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