1// Copyright (C) 2025 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 GENUSTYPES_H
5#define GENUSTYPES_H
6
7#include <QtGlobal>
8
9#include <type_traits>
10
11QT_BEGIN_NAMESPACE
12
13/*!
14 \headerfile genustypes.h
15
16 \title Genus and NodeType enumerations
17
18 This header file defines two main enumerations:
19 - \l {Genus}: An unsigned char type that specifies whether a node in the
20 documentation represents a C++ element, a QML element, a text document,
21 or a combination used to indicate API types.
22 - \l {NodeType}: An unsigned char type that identifies the precise subclass
23 of a node, such as Namespace, Class, Function, etc.
24
25 In addition, the file provides two inline utility functions:
26 - \l hasCommonGenusType(), which performs a bitwise comparison between two
27 \c Genus values to determine if they share any common bits.
28 - \l isApiGenus(), which checks if a given \c Genus value represents an API
29 type by verifying if it contains the C++ or QML flags.
30
31 These enumerations and functions are used in QDoc to facilitate mapping of
32 source elements to node categories, as well as to enable fine-grained search
33 and filtering based on node types.
34*/
35
36/*!
37 \enum Genus
38 \relates genustypes.h
39
40 An unsigned char value that specifies whether the Node represents a C++
41 element, a QML element, or a text document. The Genus values are also passed
42 to search functions to specify the Genus of Tree Node that can satisfy the
43 search.
44
45 \value DontCare The Genus is not specified. Used when calling Tree search
46 functions to indicate the search can accept any Genus of
47 Node.
48 \value CPP The Node represents a C++ element.
49 \value QML The Node represents a QML element.
50 \value DOC The Node represents a text document.
51 \value API The Node represents an API element.
52*/
53enum class Genus : unsigned char {
54 DontCare = 0x0,
55 CPP = 0x1,
56 QML = 0x4,
57 DOC = 0x8,
58 API = CPP | QML
59};
60
61/*!
62 \brief Determines if two genuses share any common bits.
63 \relates genustypes.h
64
65 Performs a bitwise AND operation between the underlying integer values of
66 two Genus enums to determine if they share any common bits. Returns \c true
67 if at least one bit is common between \a searchMask and \a candidate,
68 \c false otherwise.
69
70 \sa isApiGenus()
71*/
72inline constexpr bool hasCommonGenusType(Genus searchMask, Genus candidate)
73{
74 using Underlying = std::underlying_type_t<Genus>;
75 return (static_cast<Underlying>(searchMask) & static_cast<Underlying>(candidate)) != 0;
76}
77
78/*!
79 \brief Determines if a genus represents an API type.
80 \relates genustypes.h
81
82 Checks if the given genus, \a g, has bits in common with either Genus::CPP
83 or Genus::QML, which are considered API types. The function returns \c true
84 if the genus represents an API type (CPP or QML), \c false otherwise.
85
86 \sa hasCommonGenusType()
87*/
88inline constexpr bool isApiGenus(Genus g) {
89 using Underlying = std::underlying_type_t<Genus>;
90 // The API flag is defined as the combination of CPP and QML.
91 constexpr Underlying apiMask = static_cast<Underlying>(Genus::API);
92 return (static_cast<Underlying>(g) & apiMask) != 0;
93}
94
95/*!
96 \enum GenusType
97 \relates genustypes.h
98
99 An unsigned char value that identifies an object as a
100 particular subclass of Node.
101
102 \value NoType The node type has not been set yet.
103 \value Namespace The Node subclass is NamespaceNode, which represents a C++
104 namespace.
105 \value Class The Node subclass is ClassNode, which represents a C++ class.
106 \value Struct The Node subclass is ClassNode, which represents a C struct.
107 \value Union The Node subclass is ClassNode, which represents a C union
108 (currently no known uses).
109 \value HeaderFile The Node subclass is HeaderNode, which represents a header
110 file.
111 \value Page The Node subclass is PageNode, which represents a text page from
112 a .qdoc file.
113 \value Enum The Node subclass is EnumNode, which represents an enum type or
114 enum class.
115 \value Example The Node subclass is ExampleNode, which represents an example
116 subdirectory.
117 \value ExternalPage The Node subclass is ExternalPageNode, which is for
118 linking to an external page.
119 \value Function The Node subclass is FunctionNode, which can represent C++,
120 and QML functions.
121 \value Typedef The Node subclass is TypedefNode, which represents a C++
122 typedef.
123 \value Property The Node subclass is PropertyNode, which represents a use of
124 Q_Property.
125 \value Variable The Node subclass is VariableNode, which represents a global
126 variable or class data member.
127 \value Group The Node subclass is CollectionNode, which represents a group
128 of documents.
129 \value Module The Node subclass is CollectionNode, which represents a C++
130 module.
131 \value QmlEnum The Node subclass is QmlEnumNode, which represents a QML
132 enumeration.
133 \value QmlType The Node subclass is QmlTypeNode, which represents a QML
134 type.
135 \value QmlModule The Node subclass is CollectionNode, which represents a QML
136 module.
137 \value QmlProperty The Node subclass is QmlPropertyNode, which represents a
138 property in a QML type.
139 \value QmlBasicType The Node subclass is QmlTypeNode, which represents a
140 value type like int, etc.
141 \value SharedComment The Node subclass is SharedCommentNode, which
142 represents a collection of nodes that share the same documentation
143 comment.
144 \omitvalue Collection
145 \value Proxy The Node subclass is ProxyNode, which represents one or more
146 entities that are documented in the current module but which actually
147 reside in a different module.
148 \omitvalue LastType
149*/
150enum class NodeType : unsigned char {
151 NoType,
152 Namespace,
153 Class,
154 Struct,
155 Union,
156 HeaderFile,
157 Page,
158 Enum,
159 Example,
160 ExternalPage,
161 Function,
162 Typedef,
163 TypeAlias,
164 Property,
165 Variable,
166 Group,
167 Module,
168 QmlEnum,
169 QmlType,
170 QmlModule,
171 QmlProperty,
172 QmlValueType,
173 SharedComment,
174 Collection,
175 Proxy
176};
177
178QT_END_NAMESPACE
179
180#endif // GENUSTYPES_H
181
182

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