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 "node.h"
5
6#include "aggregate.h"
7#include "codemarker.h"
8#include "config.h"
9#include "enumnode.h"
10#include "functionnode.h"
11#include "generator.h"
12#include "qdocdatabase.h"
13#include "qmltypenode.h"
14#include "qmlpropertynode.h"
15#include "relatedclass.h"
16#include "sharedcommentnode.h"
17#include "tokenizer.h"
18#include "tree.h"
19
20#include <QtCore/quuid.h>
21#include <QtCore/qversionnumber.h>
22
23#include <utility>
24
25QT_BEGIN_NAMESPACE
26
27/*!
28 \class Node
29 \brief The Node class is the base class for all the nodes in QDoc's parse tree.
30
31 Class Node is the base class of all the node subclasses. There is a subclass of Node
32 for each type of entity that QDoc can document. The types of entities that QDoc can
33 document are listed in the enum type NodeType.
34
35 After ClangCodeParser has parsed all the header files to build its precompiled header,
36 it then visits the clang Abstract Syntax Tree (AST). For each node in the AST that it
37 determines is in the public API and must be documented, it creates an instance of one
38 of the Node subclasses and adds it to the QDoc Tree.
39
40 Each instance of a sublass of Node has a parent pointer to link it into the Tree. The
41 parent pointer is obtained by calling \l {parent()}, which returns a pointer to an
42 instance of the Node subclass, Aggregate, which is never instantiated directly, but
43 as the base class for certain subclasses of Node that can have children. For example,
44 ClassNode and QmlTypeNode can have children, so they both inherit Aggregate, while
45 PropertyNode and QmlPropertyNode can not have children, so they both inherit Node.
46
47 \sa Aggregate, ClassNode, PropertyNode
48 */
49
50/*!
51 Returns \c true if the node \a n1 is less than node \a n2. The
52 comparison is performed by comparing properties of the nodes
53 in order of increasing complexity.
54 */
55bool Node::nodeNameLessThan(const Node *n1, const Node *n2)
56{
57#define LT_RETURN_IF_NOT_EQUAL(a, b) \
58 if ((a) != (b)) \
59 return (a) < (b);
60
61 if (n1->isPageNode() && n2->isPageNode()) {
62 LT_RETURN_IF_NOT_EQUAL(n1->fullName(), n2->fullName());
63 LT_RETURN_IF_NOT_EQUAL(n1->fullTitle(), n2->fullTitle());
64 }
65
66 if (n1->isFunction() && n2->isFunction()) {
67 const auto *f1 = static_cast<const FunctionNode *>(n1);
68 const auto *f2 = static_cast<const FunctionNode *>(n2);
69
70 LT_RETURN_IF_NOT_EQUAL(f1->isConst(), f2->isConst());
71 LT_RETURN_IF_NOT_EQUAL(f1->signature(Node::SignatureReturnType),
72 f2->signature(Node::SignatureReturnType));
73 }
74
75 LT_RETURN_IF_NOT_EQUAL(n1->nodeType(), n2->nodeType());
76 LT_RETURN_IF_NOT_EQUAL(n1->name(), n2->name());
77 LT_RETURN_IF_NOT_EQUAL(n1->access(), n2->access());
78 LT_RETURN_IF_NOT_EQUAL(n1->location().filePath(), n2->location().filePath());
79
80 return false;
81}
82
83/*!
84 \enum Node::NodeType
85
86 An unsigned char value that identifies an object as a
87 particular subclass of Node.
88
89 \value NoType The node type has not been set yet.
90 \value Namespace The Node subclass is NamespaceNode, which represents a C++
91 namespace.
92 \value Class The Node subclass is ClassNode, which represents a C++ class.
93 \value Struct The Node subclass is ClassNode, which represents a C struct.
94 \value Union The Node subclass is ClassNode, which represents a C union
95 (currently no known uses).
96 \value HeaderFile The Node subclass is HeaderNode, which represents a header
97 file.
98 \value Page The Node subclass is PageNode, which represents a text page from
99 a .qdoc file.
100 \value Enum The Node subclass is EnumNode, which represents an enum type or
101 enum class.
102 \value Example The Node subclass is ExampleNode, which represents an example
103 subdirectory.
104 \value ExternalPage The Node subclass is ExternalPageNode, which is for
105 linking to an external page.
106 \value Function The Node subclass is FunctionNode, which can represent C++,
107 and QML functions.
108 \value Typedef The Node subclass is TypedefNode, which represents a C++
109 typedef.
110 \value Property The Node subclass is PropertyNode, which represents a use of
111 Q_Property.
112 \value Variable The Node subclass is VariableNode, which represents a global
113 variable or class data member.
114 \value Group The Node subclass is CollectionNode, which represents a group of
115 documents.
116 \value Module The Node subclass is CollectionNode, which represents a C++
117 module.
118 \value QmlType The Node subclass is QmlTypeNode, which represents a QML type.
119 \value QmlModule The Node subclass is CollectionNode, which represents a QML
120 module.
121 \value QmlProperty The Node subclass is QmlPropertyNode, which represents a
122 property in a QML type.
123 \value QmlBasicType The Node subclass is QmlTypeNode, which represents a
124 value type like int, etc.
125 \value SharedComment The Node subclass is SharedCommentNode, which represents
126 a collection of nodes that share the same documentation comment.
127 \omitvalue Collection
128 \value Proxy The Node subclass is ProxyNode, which represents one or more
129 entities that are documented in the current module but which actually
130 reside in a different module.
131 \omitvalue LastType
132*/
133
134/*!
135 \enum Node::Genus
136
137 An unsigned char value that specifies whether the Node represents a
138 C++ element, a QML element, or a text document.
139 The Genus values are also passed to search functions to specify the
140 Genus of Tree Node that can satisfy the search.
141
142 \value DontCare The Genus is not specified. Used when calling Tree search functions to indicate
143 the search can accept any Genus of Node.
144 \value CPP The Node represents a C++ element.
145 \value QML The Node represents a QML element.
146 \value DOC The Node represents a text document.
147*/
148
149/*!
150 \enum Access
151
152 An unsigned char value that indicates the C++ access level.
153
154 \value Public The element has public access.
155 \value Protected The element has protected access.
156 \value Private The element has private access.
157*/
158
159/*!
160 \enum Node::Status
161
162 An unsigned char that specifies the status of the documentation element in
163 the documentation set.
164
165 \value Deprecated The element has been deprecated.
166 \value Preliminary The element is new; the documentation is preliminary.
167 \value Active The element is current.
168 \value Internal The element is for internal use only, not to be published.
169 \value DontDocument The element is not to be documented.
170*/
171
172/*!
173 \enum Node::ThreadSafeness
174
175 An unsigned char that specifies the degree of thread-safeness of the element.
176
177 \value UnspecifiedSafeness The thread-safeness is not specified.
178 \value NonReentrant The element is not reentrant.
179 \value Reentrant The element is reentrant.
180 \value ThreadSafe The element is threadsafe.
181*/
182
183/*!
184 \enum Node::LinkType
185
186 An unsigned char value that probably should be moved out of the Node base class.
187
188 \value StartLink
189 \value NextLink
190 \value PreviousLink
191 \value ContentsLink
192 */
193
194/*!
195 \enum Node::FlagValue
196
197 A value used in PropertyNode and QmlPropertyNode that can be -1, 0, or +1.
198 Properties and QML properties have flags, which can be 0 or 1, false or true,
199 or not set. FlagValueDefault is the not set value. In other words, if a flag
200 is set to FlagValueDefault, the meaning is the flag has not been set.
201
202 \value FlagValueDefault -1 Not set.
203 \value FlagValueFalse 0 False.
204 \value FlagValueTrue 1 True.
205*/
206
207/*!
208 \fn Node::~Node()
209
210 The default destructor is virtual so any subclass of Node can be
211 deleted by deleting a pointer to Node.
212 */
213
214/*! \fn bool Node::isActive() const
215 Returns true if this node's status is \c Active.
216 */
217
218/*! \fn bool Node::isClass() const
219 Returns true if the node type is \c Class.
220 */
221
222/*! \fn bool Node::isCppNode() const
223 Returns true if this node's Genus value is \c CPP.
224 */
225
226/*! \fn bool Node::isDeprecated() const
227 Returns true if this node's status is \c Deprecated.
228 */
229
230/*! \fn bool Node::isDontDocument() const
231 Returns true if this node's status is \c DontDocument.
232 */
233
234/*! \fn bool Node::isEnumType() const
235 Returns true if the node type is \c Enum.
236 */
237
238/*! \fn bool Node::isExample() const
239 Returns true if the node type is \c Example.
240 */
241
242/*! \fn bool Node::isExternalPage() const
243 Returns true if the node type is \c ExternalPage.
244 */
245
246/*! \fn bool Node::isFunction(Genus g = DontCare) const
247 Returns true if this is a FunctionNode and its Genus is set to \a g.
248 */
249
250/*! \fn bool Node::isGroup() const
251 Returns true if the node type is \c Group.
252 */
253
254/*! \fn bool Node::isHeader() const
255 Returns true if the node type is \c HeaderFile.
256 */
257
258/*! \fn bool Node::isIndexNode() const
259 Returns true if this node was created from something in an index file.
260 */
261
262/*! \fn bool Node::isModule() const
263 Returns true if the node type is \c Module.
264 */
265
266/*! \fn bool Node::isNamespace() const
267 Returns true if the node type is \c Namespace.
268 */
269
270/*! \fn bool Node::isPage() const
271 Returns true if the node type is \c Page.
272 */
273
274/*! \fn bool Node::isPreliminary() const
275 Returns true if this node's status is \c Preliminary.
276 */
277
278/*! \fn bool Node::isPrivate() const
279 Returns true if this node's access is \c Private.
280 */
281
282/*! \fn bool Node::isProperty() const
283 Returns true if the node type is \c Property.
284 */
285
286/*! \fn bool Node::isProxyNode() const
287 Returns true if the node type is \c Proxy.
288 */
289
290/*! \fn bool Node::isPublic() const
291 Returns true if this node's access is \c Public.
292 */
293
294/*! \fn bool Node::isProtected() const
295 Returns true if this node's access is \c Protected.
296 */
297
298/*! \fn bool Node::isQmlBasicType() const
299 Returns true if the node type is \c QmlBasicType.
300 */
301
302/*! \fn bool Node::isQmlModule() const
303 Returns true if the node type is \c QmlModule.
304 */
305
306/*! \fn bool Node::isQmlNode() const
307 Returns true if this node's Genus value is \c QML.
308 */
309
310/*! \fn bool Node::isQmlProperty() const
311 Returns true if the node type is \c QmlProperty.
312 */
313
314/*! \fn bool Node::isQmlType() const
315 Returns true if the node type is \c QmlType or \c QmlValueType.
316 */
317
318/*! \fn bool Node::isRelatedNonmember() const
319 Returns true if this is a related nonmember of something.
320 */
321
322/*! \fn bool Node::isStruct() const
323 Returns true if the node type is \c Struct.
324 */
325
326/*! \fn bool Node::isSharedCommentNode() const
327 Returns true if the node type is \c SharedComment.
328 */
329
330/*! \fn bool Node::isTypeAlias() const
331 Returns true if the node type is \c Typedef.
332 */
333
334/*! \fn bool Node::isTypedef() const
335 Returns true if the node type is \c Typedef.
336 */
337
338/*! \fn bool Node::isUnion() const
339 Returns true if the node type is \c Union.
340 */
341
342/*! \fn bool Node::isVariable() const
343 Returns true if the node type is \c Variable.
344 */
345
346/*! \fn bool Node::isGenericCollection() const
347 Returns true if the node type is \c Collection.
348 */
349
350/*! \fn bool Node::isAbstract() const
351 Returns true if the ClassNode or QmlTypeNode is marked abstract.
352*/
353
354/*! \fn bool Node::isAggregate() const
355 Returns true if this node is an aggregate, which means it
356 inherits Aggregate and can therefore have children.
357*/
358
359/*! \fn bool Node::isFirstClassAggregate() const
360 Returns true if this Node is an Aggregate but not a ProxyNode.
361*/
362
363/*! \fn bool Node::isAlias() const
364 Returns true if this QML property is marked as an alias.
365*/
366
367/*! \fn bool Node::isAttached() const
368 Returns true if the QML property or QML method node is marked as attached.
369*/
370
371/*! \fn bool Node::isClassNode() const
372 Returns true if this is an instance of ClassNode.
373*/
374
375/*! \fn bool Node::isCollectionNode() const
376 Returns true if this is an instance of CollectionNode.
377*/
378
379/*! \fn bool Node::isDefault() const
380 Returns true if the QML property node is marked as default.
381*/
382
383/*! \fn bool Node::isMacro() const
384 returns true if either FunctionNode::isMacroWithParams() or
385 FunctionNode::isMacroWithoutParams() returns true.
386*/
387
388/*! \fn bool Node::isPageNode() const
389 Returns true if this node represents something that generates a documentation
390 page. In other words, if this Node's subclass inherits PageNode, then this
391 function will return \e true.
392*/
393
394/*! \fn bool Node::isQtQuickNode() const
395 Returns true if this node represents a QML element in the QtQuick module.
396*/
397
398/*! \fn bool Node::isRelatableType() const
399 Returns true if this node is something you can relate things to with
400 the \e relates command. NamespaceNode, ClassNode, HeaderNode, and
401 ProxyNode are relatable types.
402*/
403
404/*! \fn bool Node::isMarkedReimp() const
405 Returns true if the FunctionNode is marked as a reimplemented function.
406 That means it is virtual in the base class and it is reimplemented in
407 the subclass.
408*/
409
410/*! \fn bool Node::isPropertyGroup() const
411 Returns true if the node is a SharedCommentNode for documenting
412 multiple C++ properties or multiple QML properties.
413*/
414
415/*! \fn bool Node::isStatic() const
416 Returns true if the FunctionNode represents a static function.
417*/
418
419/*! \fn bool Node::isTextPageNode() const
420 Returns true if the node is a PageNode but not an Aggregate.
421*/
422
423/*!
424 Returns this node's name member. Appends "()" to the returned
425 name if this node is a function node, but not if it is a macro
426 because macro names normally appear without parentheses.
427 */
428QString Node::plainName() const
429{
430 if (isFunction() && !isMacro())
431 return m_name + QLatin1String("()");
432 return m_name;
433}
434
435/*!
436 Constructs and returns the node's fully qualified name by
437 recursively ascending the parent links and prepending each
438 parent name + "::". Breaks out when reaching a HeaderNode,
439 or when the parent pointer is \a relative. Typically, calls
440 to this function pass \c nullptr for \a relative.
441 */
442QString Node::plainFullName(const Node *relative) const
443{
444 if (m_name.isEmpty())
445 return QLatin1String("global");
446 if (isHeader())
447 return plainName();
448
449 QStringList parts;
450 const Node *node = this;
451 while (node && !node->isHeader()) {
452 parts.prepend(t: node->plainName());
453 if (node->parent() == relative || node->parent()->name().isEmpty())
454 break;
455 node = node->parent();
456 }
457 return parts.join(sep: QLatin1String("::"));
458}
459
460/*!
461 Constructs and returns the node's fully qualified signature
462 by recursively ascending the parent links and prepending each
463 parent name + "::" to the plain signature. The return type is
464 not included.
465 */
466QString Node::plainSignature() const
467{
468 if (m_name.isEmpty())
469 return QLatin1String("global");
470
471 QString fullName;
472 const Node *node = this;
473 while (node) {
474 fullName.prepend(s: node->signature(Node::SignaturePlain));
475 if (node->parent()->name().isEmpty())
476 break;
477 fullName.prepend(s: QLatin1String("::"));
478 node = node->parent();
479 }
480 return fullName;
481}
482
483/*!
484 Constructs and returns this node's full name. The full name is
485 often just the title(). When it is not the title, it is the
486 plainFullName().
487 */
488QString Node::fullName(const Node *relative) const
489{
490 if ((isTextPageNode() || isGroup()) && !title().isEmpty())
491 return title();
492 return plainFullName(relative);
493}
494
495/*!
496 Sets this Node's Doc to \a doc. If \a replace is false and
497 this Node already has a Doc, and if this doc is not marked
498 with the \\reimp command, a warning is reported that the
499 existing Doc is being overridden, and it reports where the
500 previous Doc was found. If \a replace is true, the Doc is
501 replaced silently.
502 */
503void Node::setDoc(const Doc &doc, bool replace)
504{
505 if (!m_doc.isEmpty() && !replace && !doc.isMarkedReimp()) {
506 doc.location().warning(QStringLiteral("Overrides a previous doc"),
507 QStringLiteral("from here: %1").arg(a: m_doc.location().toString()));
508 }
509 m_doc = doc;
510}
511
512/*!
513 Sets the node's status to \a t.
514
515 \sa Status
516*/
517void Node::setStatus(Status t)
518{
519 m_status = t;
520
521 // Set non-null, empty URL to nodes that are ignored as
522 // link targets
523 switch (t) {
524 case Internal:
525 if (Config::instance().showInternal())
526 break;
527 Q_FALLTHROUGH();
528 case DontDocument:
529 m_url = QStringLiteral("");
530 break;
531 default:
532 break;
533 }
534}
535
536/*!
537 Construct a node with the given \a type and having the
538 given \a parent and \a name. The new node is added to the
539 parent's child list.
540 */
541Node::Node(NodeType type, Aggregate *parent, QString name)
542 : m_nodeType(type),
543 m_indexNodeFlag(false),
544 m_relatedNonmember(false),
545 m_hadDoc(false),
546 m_parent(parent),
547 m_name(std::move(name))
548{
549 if (m_parent)
550 m_parent->addChild(child: this);
551
552 m_outSubDir = Generator::outputSubdir();
553
554 setGenus(getGenus(t: type));
555}
556
557/*!
558 Determines the appropriate Genus value for the NodeType
559 value \a t and returns that Genus value. Note that this
560 function is called in the Node() constructor. It always
561 returns Node::CPP when \a t is Node::Function, which
562 means the FunctionNode() constructor must determine its
563 own Genus value separately, because class FunctionNode
564 is a subclass of Node.
565 */
566Node::Genus Node::getGenus(Node::NodeType t)
567{
568 switch (t) {
569 case Node::Enum:
570 case Node::Class:
571 case Node::Struct:
572 case Node::Union:
573 case Node::Module:
574 case Node::TypeAlias:
575 case Node::Typedef:
576 case Node::Property:
577 case Node::Variable:
578 case Node::Function:
579 case Node::Namespace:
580 case Node::HeaderFile:
581 return Node::CPP;
582 case Node::QmlType:
583 case Node::QmlModule:
584 case Node::QmlProperty:
585 case Node::QmlValueType:
586 return Node::QML;
587 case Node::Page:
588 case Node::Group:
589 case Node::Example:
590 case Node::ExternalPage:
591 return Node::DOC;
592 case Node::Collection:
593 case Node::SharedComment:
594 case Node::Proxy:
595 default:
596 return Node::DontCare;
597 }
598}
599
600/*! \fn QString Node::url() const
601 Returns the node's URL, which is the url of the documentation page
602 created for the node or the url of an external page if the node is
603 an ExternalPageNode. The url is used for generating a link to the
604 page the node represents.
605
606 \sa Node::setUrl()
607 */
608
609/*! \fn void Node::setUrl(const QString &url)
610 Sets the node's URL to \a url, which is the url to the page that the
611 node represents. This function is only called when an index file is
612 read. In other words, a node's url is set when qdoc decides where its
613 page will be and what its name will be, which happens when qdoc writes
614 the index file for the module being documented.
615
616 \sa QDocIndexFiles
617 */
618
619/*!
620 Returns this node's type as a string for use as an
621 attribute value in XML or HTML.
622 */
623QString Node::nodeTypeString() const
624{
625 if (isFunction()) {
626 const auto *fn = static_cast<const FunctionNode *>(this);
627 return fn->kindString();
628 }
629 return nodeTypeString(t: nodeType());
630}
631
632/*!
633 Returns the node type \a t as a string for use as an
634 attribute value in XML or HTML.
635 */
636QString Node::nodeTypeString(NodeType t)
637{
638 switch (t) {
639 case Namespace:
640 return QLatin1String("namespace");
641 case Class:
642 return QLatin1String("class");
643 case Struct:
644 return QLatin1String("struct");
645 case Union:
646 return QLatin1String("union");
647 case HeaderFile:
648 return QLatin1String("header");
649 case Page:
650 return QLatin1String("page");
651 case Enum:
652 return QLatin1String("enum");
653 case Example:
654 return QLatin1String("example");
655 case ExternalPage:
656 return QLatin1String("external page");
657 case TypeAlias:
658 case Typedef:
659 return QLatin1String("typedef");
660 case Function:
661 return QLatin1String("function");
662 case Property:
663 return QLatin1String("property");
664 case Proxy:
665 return QLatin1String("proxy");
666 case Variable:
667 return QLatin1String("variable");
668 case Group:
669 return QLatin1String("group");
670 case Module:
671 return QLatin1String("module");
672
673 case QmlType:
674 return QLatin1String("QML type");
675 case QmlValueType:
676 return QLatin1String("QML value type");
677 case QmlModule:
678 return QLatin1String("QML module");
679 case QmlProperty:
680 return QLatin1String("QML property");
681
682 case SharedComment:
683 return QLatin1String("shared comment");
684 case Collection:
685 return QLatin1String("collection");
686 default:
687 break;
688 }
689 return QString();
690}
691
692/*! Converts the boolean value \a b to an enum representation
693 of the boolean type, which includes an enum value for the
694 \e {default value} of the item, i.e. true, false, or default.
695 */
696Node::FlagValue Node::toFlagValue(bool b)
697{
698 return b ? FlagValueTrue : FlagValueFalse;
699}
700
701/*!
702 Converts the enum \a fv back to a boolean value.
703 If \a fv is neither the true enum value nor the
704 false enum value, the boolean value returned is
705 \a defaultValue.
706 */
707bool Node::fromFlagValue(FlagValue fv, bool defaultValue)
708{
709 switch (fv) {
710 case FlagValueTrue:
711 return true;
712 case FlagValueFalse:
713 return false;
714 default:
715 return defaultValue;
716 }
717}
718
719/*!
720 This function creates a pair that describes a link.
721 The pair is composed from \a link and \a desc. The
722 \a linkType is the map index the pair is filed under.
723 */
724void Node::setLink(LinkType linkType, const QString &link, const QString &desc)
725{
726 std::pair<QString, QString> linkPair;
727 linkPair.first = link;
728 linkPair.second = desc;
729 m_linkMap[linkType] = linkPair;
730}
731
732/*!
733 Sets the information about the project and version a node was introduced
734 in, unless the version is lower than the 'ignoresince.<project>'
735 configuration variable.
736 */
737void Node::setSince(const QString &since)
738{
739 QStringList parts = since.split(sep: QLatin1Char(' '));
740 QString project;
741 if (parts.size() > 1)
742 project = Config::dot + parts.first();
743
744 QVersionNumber cutoff =
745 QVersionNumber::fromString(string: Config::instance().get(CONFIG_IGNORESINCE + project).asString())
746 .normalized();
747
748 if (!cutoff.isNull() && QVersionNumber::fromString(string: parts.last()).normalized() < cutoff)
749 return;
750
751 m_since = parts.join(sep: QLatin1Char(' '));
752}
753
754/*!
755 Extract a class name from the type \a string and return it.
756 */
757QString Node::extractClassName(const QString &string) const
758{
759 QString result;
760 for (int i = 0; i <= string.size(); ++i) {
761 QChar ch;
762 if (i != string.size())
763 ch = string.at(i);
764
765 QChar lower = ch.toLower();
766 if ((lower >= QLatin1Char('a') && lower <= QLatin1Char('z')) || ch.digitValue() >= 0
767 || ch == QLatin1Char('_') || ch == QLatin1Char(':')) {
768 result += ch;
769 } else if (!result.isEmpty()) {
770 if (result != QLatin1String("const"))
771 return result;
772 result.clear();
773 }
774 }
775 return result;
776}
777
778/*!
779 Returns the thread safeness value for whatever this node
780 represents. But if this node has a parent and the thread
781 safeness value of the parent is the same as the thread
782 safeness value of this node, what is returned is the
783 value \c{UnspecifiedSafeness}. Why?
784 */
785Node::ThreadSafeness Node::threadSafeness() const
786{
787 if (m_parent && m_safeness == m_parent->inheritedThreadSafeness())
788 return UnspecifiedSafeness;
789 return m_safeness;
790}
791
792/*!
793 If this node has a parent, the parent's thread safeness
794 value is returned. Otherwise, this node's thread safeness
795 value is returned. Why?
796 */
797Node::ThreadSafeness Node::inheritedThreadSafeness() const
798{
799 if (m_parent && m_safeness == UnspecifiedSafeness)
800 return m_parent->inheritedThreadSafeness();
801 return m_safeness;
802}
803
804/*!
805 Returns \c true if the node's status is \c Internal, or if
806 its parent is a class with \c Internal status.
807 */
808bool Node::isInternal() const
809{
810 if (status() == Internal)
811 return true;
812 return parent() && parent()->status() == Internal && !parent()->isAbstract();
813}
814
815/*! \fn void Node::markInternal()
816 Sets the node's access to Private and its status to Internal.
817 */
818
819/*!
820 Returns a pointer to the root of the Tree this node is in.
821 */
822Aggregate *Node::root() const
823{
824 if (parent() == nullptr)
825 return (this->isAggregate() ? static_cast<Aggregate *>(const_cast<Node *>(this)) : nullptr);
826 Aggregate *t = parent();
827 while (t->parent() != nullptr)
828 t = t->parent();
829 return t;
830}
831
832/*!
833 Returns a pointer to the Tree this node is in.
834 */
835Tree *Node::tree() const
836{
837 return root()->tree();
838}
839
840/*!
841 Sets the node's declaration location, its definition
842 location, or both, depending on the suffix of the file
843 name from the file path in location \a t.
844 */
845void Node::setLocation(const Location &t)
846{
847 QString suffix = t.fileSuffix();
848 if (suffix == "h")
849 m_declLocation = t;
850 else if (suffix == "cpp")
851 m_defLocation = t;
852 else {
853 m_declLocation = t;
854 m_defLocation = t;
855 }
856}
857
858/*!
859 Returns true if this node is sharing a comment and the
860 shared comment is not empty.
861 */
862bool Node::hasSharedDoc() const
863{
864 return (m_sharedCommentNode && m_sharedCommentNode->hasDoc());
865}
866
867/*!
868 Returns the CPP node's qualified name by prepending the
869 namespaces name + "::" if there isw a namespace.
870 */
871QString Node::qualifyCppName()
872{
873 if (m_parent && m_parent->isNamespace() && !m_parent->name().isEmpty())
874 return m_parent->name() + "::" + m_name;
875 return m_name;
876}
877
878/*!
879 Return the name of this node qualified with the parent name
880 and "::" if there is a parent name.
881 */
882QString Node::qualifyWithParentName()
883{
884 if (m_parent && !m_parent->name().isEmpty())
885 return m_parent->name() + "::" + m_name;
886 return m_name;
887}
888
889/*!
890 Returns the QML node's qualified name by prepending the logical
891 module name.
892 */
893QString Node::qualifyQmlName()
894{
895 return logicalModuleName() + "::" + m_name;
896}
897
898/*!
899 Returns \c true if the node is a class node or a QML type node
900 that is marked as being a wrapper class or wrapper QML type,
901 or if it is a member of a wrapper class or type.
902 */
903bool Node::isWrapper() const
904{
905 return m_parent != nullptr && m_parent->isWrapper();
906}
907
908/*!
909 Construct the full document name for this node and return it.
910 */
911QString Node::fullDocumentName() const
912{
913 QStringList pieces;
914 const Node *n = this;
915
916 do {
917 if (!n->name().isEmpty())
918 pieces.insert(i: 0, t: n->name());
919
920 if (n->isQmlType() && !n->logicalModuleName().isEmpty()) {
921 pieces.insert(i: 0, t: n->logicalModuleName());
922 break;
923 }
924
925 if (n->isTextPageNode())
926 break;
927
928 // Examine the parent if the node is a member
929 if (!n->parent() || n->isRelatedNonmember())
930 break;
931
932 n = n->parent();
933 } while (true);
934
935 // Create a name based on the type of the ancestor node.
936 QString concatenator = "::";
937 if (n->isQmlType())
938 concatenator = QLatin1Char('.');
939
940 if (n->isTextPageNode())
941 concatenator = QLatin1Char('#');
942
943 return pieces.join(sep: concatenator);
944}
945
946void Node::setDeprecatedSince(const QString &sinceVersion)
947{
948 if (!m_deprecatedSince.isEmpty())
949 qCWarning(lcQdoc) << QStringLiteral(
950 "Setting deprecated since version for %1 to %2 even though it "
951 "was already set to %3. This is very unexpected.")
952 .arg(args&: this->m_name, args: sinceVersion, args&: this->m_deprecatedSince);
953 m_deprecatedSince = sinceVersion;
954}
955
956/*! \fn Node *Node::clone(Aggregate *parent)
957
958 When reimplemented in a subclass, this function creates a
959 clone of this node on the heap and makes the clone a child
960 of \a parent. A pointer to the clone is returned.
961
962 Here in the base class, this function does nothing and returns
963 nullptr.
964 */
965
966/*! \fn NodeType Node::nodeType() const
967 Returns this node's type.
968
969 \sa NodeType
970*/
971
972/*! \fn Genus Node::genus() const
973 Returns this node's Genus.
974
975 \sa Genus
976*/
977
978/*! void Node::setGenus(Genus t)
979 Sets this node's Genus to \a t.
980*/
981
982/*! \fn QString Node::signature(Node::SignatureOptions options) const
983
984 Specific parts of the signature are included according to flags in
985 \a options.
986
987 If this node is not a FunctionNode, this function returns plainName().
988
989 \sa FunctionNode::signature()
990*/
991
992/*! \fn const QString &Node::fileNameBase() const
993 Returns the node's file name base string, which is built once, when
994 Generator::fileBase() is called and stored in the Node.
995*/
996
997/*! \fn bool Node::hasFileNameBase() const
998 Returns true if the node's file name base has been set.
999
1000 \sa Node::fileNameBase()
1001*/
1002
1003/*! \fn void Node::setFileNameBase(const QString &t)
1004 Sets the node's file name base to \a t. Only called by
1005 Generator::fileBase().
1006*/
1007
1008/*! \fn void Node::setAccess(Access t)
1009 Sets the node's access type to \a t.
1010
1011 \sa Access
1012*/
1013
1014/*! \fn void Node::setThreadSafeness(ThreadSafeness t)
1015 Sets the node's thread safeness to \a t.
1016
1017 \sa ThreadSafeness
1018*/
1019
1020/*! \fn void Node::setPhysicalModuleName(const QString &name)
1021 Sets the node's physical module \a name.
1022*/
1023
1024/*! \fn void Node::setReconstitutedBrief(const QString &t)
1025 When reading an index file, this function is called with the
1026 reconstituted brief clause \a t to set the node's brief clause.
1027 I think this is needed for linking to something in the brief clause.
1028*/
1029
1030/*! \fn void Node::setParent(Aggregate *n)
1031 Sets the node's parent pointer to \a n. Such a thing
1032 is not lightly done. All the calls to this function
1033 are in other member functions of Node subclasses. See
1034 the code in the subclass implementations to understand
1035 when this function can be called safely and why it is called.
1036*/
1037
1038/*! \fn void Node::setIndexNodeFlag(bool isIndexNode = true)
1039 Sets a flag in this Node that indicates the node was created
1040 for something in an index file. This is important to know
1041 because an index node is not to be documented in the current
1042 module. When the index flag is set, it means the Node
1043 represents something in another module, and it will be
1044 documented in that module's documentation.
1045*/
1046
1047/*! \fn void Node::setRelatedNonmember(bool b)
1048 Sets a flag in the node indicating whether this node is a related nonmember
1049 of something. This function is called when the \c relates command is seen.
1050 */
1051
1052/*! \fn void Node::addMember(Node *node)
1053 In a CollectionNode, this function adds \a node to the collection
1054 node's members list. It does nothing if this node is not a CollectionNode.
1055 */
1056
1057/*! \fn bool Node::hasNamespaces() const
1058 Returns \c true if this is a CollectionNode and its members list
1059 contains namespace nodes. Otherwise it returns \c false.
1060 */
1061
1062/*! \fn bool Node::hasClasses() const
1063 Returns \c true if this is a CollectionNode and its members list
1064 contains class nodes. Otherwise it returns \c false.
1065 */
1066
1067/*! \fn void Node::setAbstract(bool b)
1068 If this node is a ClassNode or a QmlTypeNode, the node's abstract flag
1069 data member is set to \a b.
1070 */
1071
1072/*! \fn void Node::setWrapper()
1073 If this node is a ClassNode or a QmlTypeNode, the node's wrapper flag
1074 data member is set to \c true.
1075 */
1076
1077/*! \fn void Node::setDataType(const QString &dataType)
1078 If this node is a PropertyNode or a QmlPropertyNode, its
1079 data type data member is set to \a dataType. Otherwise,
1080 this function does nothing.
1081 */
1082
1083/*! \fn bool Node::wasSeen() const
1084 Returns the \c seen flag data member of this node if it is a NamespaceNode
1085 or a CollectionNode. Otherwise it returns \c false. If \c true is returned,
1086 it means that the location where the namespace or collection is to be
1087 documented has been found.
1088 */
1089
1090/*! \fn void appendGroupName(const QString &t)
1091 If this node is a PageNode, the group name \a t is appended to the node's
1092 list of group names. It is not clear to me what this list of group names
1093 is used for, but it is written to the index file, and it is used in the
1094 navigation bar.
1095 */
1096
1097/*! \fn QString Node::element() const
1098 If this node is a QmlPropertyNode or a FunctionNode, this function
1099 returns the name of the parent node. Otherwise it returns an empty
1100 string.
1101 */
1102
1103/*! \fn bool Node::docMustBeGenerated() const
1104 This function is called to perform a test to decide if the node must have
1105 documentation generated. In the Node base class, it always returns \c false.
1106
1107 In the ProxyNode class it always returns \c true. There aren't many proxy
1108 nodes, but when one appears, it must generate documentation. In the overrides
1109 in NamespaceNode and ClassNode, a meaningful test is performed to decide if
1110 documentation must be generated.
1111 */
1112
1113/*! \fn QString Node::title() const
1114 Returns a string that can be used to print a title in the documentation for
1115 whatever this Node is. In the Node base class, the node's name() is returned.
1116 In a PageNode, the function returns the title data member. In a HeaderNode,
1117 if the title() is empty, the name() is returned.
1118 */
1119
1120/*! \fn QString Node::subtitle() const { return QString(); }
1121 Returns a string that can be used to print a subtitle in the documentation for
1122 whatever this Node is. In the Node base class, the empty string is returned.
1123 In a PageNode, the function returns the subtitle data member. In a HeaderNode,
1124 the subtitle data member is returned.
1125 */
1126
1127/*! \fn QString Node::fullTitle() const
1128 Returns a string that can be used as the full title for the documentation of
1129 this node. In this base class, the name() is returned. In a PageNode, title()
1130 is returned. In a HeaderNode, if the title() is empty, the name() is returned.
1131 If the title() is not empty then name-title is returned. In a CollectionNode,
1132 the title() is returned.
1133 */
1134
1135/*! \fn bool Node::setTitle(const QString &title)
1136 Sets the node's \a title, which is used for the title of
1137 the documentation page, if one is generated for this node.
1138 Returns \c true if the title is set. In this base class,
1139 there is no title string stored, so in the base class,
1140 nothing happens and \c false is returned. The override in
1141 the PageNode class is where the title is set.
1142 */
1143
1144/*! \fn bool Node::setSubtitle(const QString &subtitle)
1145 Sets the node's \a subtitle, which is used for the subtitle
1146 of the documentation page, if one is generated for this node.
1147 Returns \c true if the subtitle is set. In this base class,
1148 there is no subtitle string stored, so in the base class,
1149 nothing happens and \c false is returned. The override in
1150 the PageNode and HeaderNode classes is where the subtitle is
1151 set.
1152 */
1153
1154/*! \fn void Node::markDefault()
1155 If this node is a QmlPropertyNode, it is marked as the default property.
1156 Otherwise the function does nothing.
1157 */
1158
1159/*! \fn void Node::markReadOnly(bool flag)
1160 If this node is a QmlPropertyNode, then the property's read-only
1161 flag is set to \a flag.
1162 */
1163
1164/*! \fn Aggregate *Node::parent() const
1165 Returns the node's parent pointer.
1166*/
1167
1168/*! \fn const QString &Node::name() const
1169 Returns the node's name data member.
1170*/
1171
1172/*! \fn void Node::setQtVariable(const QString &v)
1173 If this node is a CollectionNode, its QT variable is set to \a v.
1174 Otherwise the function does nothing. I don't know what the QT variable
1175 is used for.
1176 */
1177
1178/*! \fn QString Node::qtVariable() const
1179 If this node is a CollectionNode, its QT variable is returned.
1180 Otherwise an empty string is returned. I don't know what the QT
1181 variable is used for.
1182 */
1183
1184/*! \fn bool Node::hasTag(const QString &t) const
1185 If this node is a FunctionNode, the function returns \c true if
1186 the function has the tag \a t. Otherwise the function returns
1187 \c false. I don't know what the tag is used for.
1188 */
1189
1190/*! \fn const QMap<LinkType, std::pair<QString, QString> > &Node::links() const
1191 Returns a reference to this node's link map. The link map should
1192 probably be moved to the PageNode, because it contains links to the
1193 start page, next page, previous page, and contents page, and these
1194 are only used in PageNode, I think.
1195 */
1196
1197/*! \fn Access Node::access() const
1198 Returns the node's Access setting, which can be \c Public,
1199 \c Protected, or \c Private.
1200 */
1201
1202/*! \fn const Location& Node::declLocation() const
1203 Returns the Location where this node's declaration was seen.
1204 Normally the declaration location is in an \e include file.
1205 The declaration location is used in qdoc error/warning messages
1206 about the declaration.
1207 */
1208
1209/*! \fn const Location& Node::defLocation() const
1210 Returns the Location where this node's dedefinition was seen.
1211 Normally the definition location is in a \e .cpp file.
1212 The definition location is used in qdoc error/warning messages
1213 when the error is discovered at the location of the definition,
1214 although the way to correct the problem often requires changing
1215 the declaration.
1216 */
1217
1218/*! \fn const Location& Node::location() const
1219 If this node's definition location is empty, this function
1220 returns this node's declaration location. Otherwise it
1221 returns the definition location.
1222
1223 \sa Location
1224 */
1225
1226/*! \fn const Doc &Node::doc() const
1227 Returns a reference to the node's Doc data member.
1228
1229 \sa Doc
1230 */
1231
1232/*! \fn bool Node::hasDoc() const
1233 Returns \c true if the node has documentation, i.e. if its Doc
1234 data member is not empty.
1235
1236 \sa Doc
1237 */
1238
1239/*! \fn Status Node::status() const
1240 Returns the node's status value.
1241
1242 \sa Status
1243 */
1244
1245/*! \fn QString Node::since() const
1246 Returns the node's since string, which can be empty.
1247 */
1248
1249/*! \fn QString Node::templateStuff() const
1250 Returns the node's template parameters string, if this node
1251 represents a templated element.
1252 */
1253
1254/*! \fn bool Node::isSharingComment() const
1255 This function returns \c true if the node is sharing a comment
1256 with other nodes. For example, multiple functions can be documented
1257 with a single qdoc comment by listing the \c {\\fn} signatures for
1258 all the functions in the single qdoc comment.
1259 */
1260
1261/*! \fn QString Node::qmlTypeName() const
1262 If this is a QmlPropertyNode or a FunctionNode representing a QML
1263 method, this function returns the qmlTypeName() of
1264 the parent() node. Otherwise it returns the name data member.
1265 */
1266
1267/*! \fn QString Node::qmlFullBaseName() const
1268 If this is a QmlTypeNode, this function returns the QML full
1269 base name. Otherwise it returns an empty string.
1270 */
1271
1272/*! \fn QString Node::logicalModuleName() const
1273 If this is a CollectionNode, this function returns the logical
1274 module name. Otherwise it returns an empty string.
1275 */
1276
1277/*! \fn QString Node::logicalModuleVersion() const
1278 If this is a CollectionNode, this function returns the logical
1279 module version number. Otherwise it returns an empty string.
1280 */
1281
1282/*! \fn QString Node::logicalModuleIdentifier() const
1283 If this is a CollectionNode, this function returns the logical
1284 module identifier. Otherwise it returns an empty string.
1285 */
1286
1287/*! \fn void Node::setLogicalModuleInfo(const QString &arg)
1288 If this node is a CollectionNode, this function splits \a arg
1289 on the blank character to get a logical module name and version
1290 number. If the version number is present, it splits the version
1291 number on the '.' character to get a major version number and a
1292 minor version number. If the version number is present, both the
1293 major and minor version numbers should be there, but the minor
1294 version number is not absolutely necessary.
1295
1296 The strings are stored in the appropriate data members for use
1297 when the QML module page is generated.
1298 */
1299
1300/*! \fn void Node::setLogicalModuleInfo(const QStringList &info)
1301 If this node is a CollectionNode, this function accepts the
1302 logical module \a info as a string list. If the logical module
1303 info contains the version number, it splits the version number
1304 on the '.' character to get the major and minor version numbers.
1305 Both major and minor version numbers should be provided, but
1306 the minor version number is not strictly necessary.
1307
1308 The strings are stored in the appropriate data members for use
1309 when the QML module page is generated. This overload
1310 of the function is called when qdoc is reading an index file.
1311 */
1312
1313/*! \fn CollectionNode *Node::logicalModule() const
1314 If this is a QmlTypeNode, a pointer to its QML module is returned,
1315 which is a pointer to a CollectionNode. Otherwise the \c nullptr
1316 is returned.
1317 */
1318
1319/*! \fn void Node::setQmlModule(CollectionNode *t)
1320 If this is a QmlTypeNode, this function sets the QML type's QML module
1321 pointer to the CollectionNode \a t. Otherwise the function does nothing.
1322 */
1323
1324/*! \fn ClassNode *Node::classNode()
1325 If this is a QmlTypeNode, this function returns the pointer to
1326 the C++ ClassNode that this QML type represents. Otherwise the
1327 \c nullptr is returned.
1328 */
1329
1330/*! \fn void Node::setClassNode(ClassNode *cn)
1331 If this is a QmlTypeNode, this function sets the C++ class node
1332 to \a cn. The C++ ClassNode is the C++ implementation of the QML
1333 type.
1334 */
1335
1336/*! \fn const QString &Node::outputSubdirectory() const
1337 Returns the node's output subdirector, which is the subdirectory
1338 of the output directory where the node's documentation file is
1339 written.
1340 */
1341
1342/*! \fn void Node::setOutputSubdirectory(const QString &t)
1343 Sets the node's output subdirectory to \a t. This is the subdirector
1344 of the output directory where the node's documentation file will be
1345 written.
1346 */
1347
1348/*! \fn NodeType Node::goal(const QString &t)
1349 When a square-bracket parameter is used in a qdoc command, this
1350 function might be called to convert the text string \a t obtained
1351 from inside the square brackets to be a Goal value, which is returned.
1352
1353 \sa Goal
1354 */
1355
1356QT_END_NAMESPACE
1357

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