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 | #include "namespacenode.h" |
5 | |
6 | #include "codeparser.h" |
7 | #include "tree.h" |
8 | |
9 | QT_BEGIN_NAMESPACE |
10 | |
11 | /*! |
12 | \class NamespaceNode |
13 | \brief This class represents a C++ namespace. |
14 | |
15 | A namespace can be used in multiple C++ modules, so there |
16 | can be a NamespaceNode for namespace Xxx in more than one |
17 | Node tree. |
18 | */ |
19 | |
20 | /*! \fn NamespaceNode(Aggregate *parent, const QString &name) |
21 | Constructs a NamespaceNode with the specified \a parent and \a name. |
22 | The node type is Node::Namespace. |
23 | */ |
24 | |
25 | /*! |
26 | Returns true if this namespace is to be documented in the |
27 | current module. There can be elements declared in this |
28 | namespace spread over multiple modules. Those elements are |
29 | documented in the modules where they are declared, but they |
30 | are linked to from the namespace page in the module where |
31 | the namespace itself is documented. |
32 | */ |
33 | bool NamespaceNode::isDocumentedHere() const |
34 | { |
35 | return m_whereDocumented == tree()->camelCaseModuleName(); |
36 | } |
37 | |
38 | /*! |
39 | Returns true if this namespace node contains at least one |
40 | child that has documentation and is not private or internal. |
41 | */ |
42 | bool NamespaceNode::hasDocumentedChildren() const |
43 | { |
44 | return std::any_of(first: m_children.cbegin(), last: m_children.cend(), |
45 | pred: [](Node *child) { return child->isInAPI(); }); |
46 | } |
47 | |
48 | /*! |
49 | Report qdoc warning for each documented child in a namespace |
50 | that is not documented. This function should only be called |
51 | when the namespace is not documented. |
52 | */ |
53 | void NamespaceNode::reportDocumentedChildrenInUndocumentedNamespace() const |
54 | { |
55 | for (const auto *node : std::as_const(t: m_children)) { |
56 | if (node->isInAPI()) { |
57 | QString msg1 = node->name(); |
58 | if (node->isFunction()) |
59 | msg1 += "()" ; |
60 | msg1 += QStringLiteral( |
61 | " is documented, but namespace %1 is not documented in any module." ) |
62 | .arg(a: name()); |
63 | QString msg2 = |
64 | QStringLiteral( |
65 | "Add /*! '\\%1 %2' ... */ or remove the qdoc comment marker (!) at " |
66 | "that line number." ) |
67 | .arg(COMMAND_NAMESPACE, args: name()); |
68 | |
69 | node->doc().location().warning(message: msg1, details: msg2); |
70 | } |
71 | } |
72 | } |
73 | |
74 | /*! |
75 | Returns true if this namespace node is not private and |
76 | contains at least one public child node with documentation. |
77 | */ |
78 | bool NamespaceNode::docMustBeGenerated() const |
79 | { |
80 | if (isInAPI()) |
81 | return true; |
82 | return hasDocumentedChildren(); |
83 | } |
84 | |
85 | /*! |
86 | Returns a const reference to the namespace node's list of |
87 | included children, which contains pointers to all the child |
88 | nodes of other namespace nodes that have the same name as |
89 | this namespace node. The list is built after the prepare |
90 | phase has been run but just before the generate phase. It |
91 | is buils by QDocDatabase::resolveNamespaces(). |
92 | |
93 | \sa QDocDatabase::resolveNamespaces() |
94 | */ |
95 | const NodeList &NamespaceNode::includedChildren() const |
96 | { |
97 | return m_includedChildren; |
98 | } |
99 | |
100 | /*! |
101 | This function is only called from QDocDatabase::resolveNamespaces(). |
102 | |
103 | \sa includedChildren(), QDocDatabase::resolveNamespaces() |
104 | */ |
105 | void NamespaceNode::includeChild(Node *child) |
106 | { |
107 | m_includedChildren.append(t: child); |
108 | } |
109 | |
110 | /*! \fn Tree* NamespaceNode::tree() const |
111 | Returns a pointer to the Tree that contains this NamespaceNode. |
112 | This requires traversing the parent() pointers to the root of |
113 | the Tree, which is the unnamed NamespaceNode. |
114 | */ |
115 | |
116 | /*! \fn bool NamespaceNode::isFirstClassAggregate() const |
117 | Returns \c true. |
118 | */ |
119 | |
120 | /*! \fn bool NamespaceNode::isRelatableType() const |
121 | Returns \c true. |
122 | */ |
123 | |
124 | /*! \fn bool NamespaceNode::wasSeen() const |
125 | Returns \c true if the \c {\\namespace} command that this NamespaceNode |
126 | represents has been parsed by qdoc. When \c false is returned, it means |
127 | that only \c {\\relates} commands have been seen that relate elements to |
128 | this namespace. |
129 | */ |
130 | |
131 | /*! \fn void NamespaceNode::markSeen() |
132 | Sets the data member that indicates that the \c {\\namespace} command this |
133 | NamespaceNode represents has been parsed by qdoc. |
134 | */ |
135 | |
136 | /*! \fn void NamespaceNode::markNotSeen() |
137 | Clears the data member that indicates that the \c {\\namespace} command this |
138 | NamespaceNode represents has been parsed by qdoc. |
139 | */ |
140 | |
141 | /*! \fn void NamespaceNode::setTree(Tree* t) |
142 | Sets the Tree pointer to \a t, which means this NamespaceNode is in the Tree \a t. |
143 | */ |
144 | |
145 | /*! \fn QString NamespaceNode::whereDocumented() const |
146 | Returns the camel case name of the module where this namespace is documented. |
147 | |
148 | \sa setWhereDocumented() |
149 | */ |
150 | |
151 | /*! \fn void NamespaceNode::setWhereDocumented(const QString &t) |
152 | Sets the camel case name of the module where this namespace is documented to |
153 | the module named \a t. |
154 | |
155 | This function is called when the \c {\\namespace} command is processed to let |
156 | qdoc know that this namespace is documented in the current module, so that |
157 | when something in another module is marked as related to this namespace, it |
158 | can be documented there with a ProxyNode for this namespace. |
159 | |
160 | \sa whereDocumented() |
161 | */ |
162 | |
163 | /*! \fn void NamespaceNode::setDocumented() |
164 | Sets the flag indicating that the \c {\\namespace} command for this |
165 | namespace was seen. |
166 | */ |
167 | |
168 | /*! \fn bool NamespaceNode::wasDocumented() const |
169 | Returns \c true if a \c {\\namespace} command for this namespace was seen. |
170 | Otherwise returns \c false. |
171 | */ |
172 | |
173 | /*! \fn void NamespaceNode::setDocNode(NamespaceNode *ns) |
174 | Called in QDocDatabase::resolveNamespaces() to set the pointer to the |
175 | NamespaceNode in which this namespace is documented. |
176 | |
177 | \sa QDocDatabase::resolveNamespaces() |
178 | */ |
179 | |
180 | /*! \fn NamespaceNode *NamespaceNode::docNode() const |
181 | Returns a pointer to the NamespaceNode that represents where the namespace |
182 | documentation is actually generated. API elements in many different modules |
183 | can be included in a single namespace. That namespace is only documented in |
184 | one module. The namespace is documented in the module where the \c {\\namespace} |
185 | command for the namespace appears. |
186 | |
187 | \sa QDocDatabase::resolveNamespaces() |
188 | */ |
189 | |
190 | QT_END_NAMESPACE |
191 | |