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 COLLECTIONNODE_H
5#define COLLECTIONNODE_H
6
7#include "genustypes.h"
8#include "pagenode.h"
9
10#include <QtCore/qglobal.h>
11#include <QtCore/qstring.h>
12
13QT_BEGIN_NAMESPACE
14
15class CollectionNode : public PageNode
16{
17public:
18 CollectionNode(NodeType type, Aggregate *parent, const QString &name)
19 : PageNode(type, parent, name)
20 {
21 }
22
23 [[nodiscard]] bool isCollectionNode() const override { return true; }
24 [[nodiscard]] QString qtVariable() const override { return m_qtVariable; }
25 void setQtVariable(const QString &v) override { m_qtVariable = v; }
26 [[nodiscard]] QString cmakePackage() const override { return m_cmakePackage; }
27 [[nodiscard]] QString cmakeComponent() const override { return m_cmakeComponent; }
28 [[nodiscard]] QString cmakeTargetItem() const override { return m_cmakeTargetItem; }
29 void setCMakePackage(const QString &package) override { m_cmakePackage = package; }
30 void setCMakeComponent(const QString &component) override { m_cmakeComponent = component; }
31 void setCMakeTargetItem(const QString &targetItem) override { m_cmakeTargetItem = targetItem; }
32 void addMember(Node *node) override;
33 [[nodiscard]] bool hasNamespaces() const override;
34 [[nodiscard]] bool hasClasses() const override;
35 [[nodiscard]] bool wasSeen() const override { return m_seen; }
36
37 [[nodiscard]] QString fullTitle() const override { return title(); }
38 [[nodiscard]] QString logicalModuleName() const override { return m_logicalModuleName; }
39 [[nodiscard]] QString logicalModuleVersion() const override;
40 [[nodiscard]] QString logicalModuleIdentifier() const override
41 {
42 return m_logicalModuleName + m_logicalModuleVersionMajor;
43 }
44 [[nodiscard]] QString state() const { return m_state; }
45
46 template <typename F>
47 NodeMap getMembers(F &&predicate) const
48 {
49 NodeMap result;
50 for (const auto &member : std::as_const(t: m_members)) {
51 if (std::invoke(predicate, member) && member->isInAPI())
52 result.insert(key: member->name(), value: member);
53 }
54 return result;
55 }
56
57 NodeMap getMembers(NodeType type) const
58 {
59 return getMembers(predicate: [type](const Node *n) {
60 return n->nodeType() == type;
61 });
62 }
63
64 void setLogicalModuleInfo(const QStringList &info) override;
65 void setState(const QString &state) { m_state = state; }
66
67 // REMARK: Those methods are used by QDocDatabase as a performance
68 // detail to avoid merging a collection node multiple times. They
69 // should not be addressed in any other part of the code nor
70 // should their usage appear more than once in QDocDatabase,
71 // albeit this is not enforced.
72 // More information are provided in the comment for the definition
73 // of m_merged.
74 void markMerged() { m_merged = true; }
75 bool isMerged() { return m_merged; }
76
77 [[nodiscard]] const NodeList &members() const { return m_members; }
78
79 void markSeen() { m_seen = true; }
80 void markNotSeen() { m_seen = false; }
81
82private:
83 bool m_seen { false };
84 // REMARK: This is set by the database when merging the collection
85 // node and is later used to avoid merging the same collection
86 // multiple times.
87 // Currently, collection nodes may come from multiple projects,
88 // such that to have a complete overview of the members of a
89 // collection we need to rejoin all members for all instances of
90 // the "same" collection.
91 // This is done in QDocDatabase, generally through an external
92 // method call that is done ad-hoc when a source-of-truth
93 // collection node is needed.
94 // As each part of the code that need such a source-of-truth will
95 // need to merge the node, to avoid the overhead of a relatively
96 // expensive operation being performed multiple times, we expose
97 // this detail so that QDocDatabase can avoid performing the
98 // operation again.
99 // To avoid the coupling, QDocDatabase could keep track of the
100 // merged nodes itself, this is a bit less trivial that this
101 // implementation and doesn't address the source of the problem
102 // (the multiple merges themselves and the sequencing of the
103 // related operations) and as such was discarded in favor of this
104 // simpler implementation.
105 // Do note that outside the very specific purpose for which this
106 // member was made, no part of the code should refer to it and its
107 // associated methods.
108 // Should this start to be the case, we can switch to the more
109 // complex encapsulation into QDocDatabase without having to touch
110 // the outside user of the merges.
111 // Further down the line, this is expected to go away completely
112 // as other part of the code are streamlined.
113 // KLUDGE: Note that this whole exposure is done as a hackish
114 // solution to QTBUG-104237 and should not be considered final or
115 // dependable.
116 bool m_merged { false };
117 NodeList m_members {};
118 QString m_logicalModuleName {};
119 QString m_logicalModuleVersionMajor {};
120 QString m_logicalModuleVersionMinor {};
121 QString m_qtVariable {};
122 QString m_state {};
123 QString m_cmakePackage = {};
124 QString m_cmakeComponent = {};
125 QString m_cmakeTargetItem = {};
126};
127
128QT_END_NAMESPACE
129
130#endif // COLLECTIONNODE_H
131

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