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
9QT_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 */
33bool 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 */
42bool 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 */
53void 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 */
78bool 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 */
95const 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 */
105void 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
190QT_END_NAMESPACE
191

source code of qttools/src/qdoc/qdoc/src/qdoc/namespacenode.cpp