clang-tools 8.0.0

Representation.h
Go to the documentation of this file.
1 ///===-- Representation.h - ClangDoc Representation -------------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file defines the internal representations of different declaration
11 // types for the clang-doc tool.
12 //
13 //===----------------------------------------------------------------------===//
14
15 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
16 #define LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
17
18 #include "clang/AST/Type.h"
19 #include "clang/Basic/Specifiers.h"
20 #include "clang/Tooling/StandaloneExecution.h"
21 #include "llvm/ADT/Optional.h"
22 #include "llvm/ADT/SmallVector.h"
23 #include "llvm/ADT/StringExtras.h"
24 #include <array>
25 #include <string>
26
27 namespace clang {
28 namespace doc {
29
30 // SHA1'd hash of a USR.
31 using SymbolID = std::array<uint8_t, 20>;
32
33 struct Info;
34 struct FunctionInfo;
35 struct EnumInfo;
36
37 enum class InfoType {
38 IT_default,
39 IT_namespace,
40 IT_record,
41 IT_function,
42 IT_enum
43 };
44
45 // A representation of a parsed comment.
46 struct CommentInfo {
47 CommentInfo() = default;
48 CommentInfo(CommentInfo &Other) = delete;
49 CommentInfo(CommentInfo &&Other) = default;
50
51 SmallString<16>
52 Kind; // Kind of comment (FullComment, ParagraphComment, TextComment,
53 // InlineCommandComment, HTMLStartTagComment, HTMLEndTagComment,
54 // BlockCommandComment, ParamCommandComment,
55 // TParamCommandComment, VerbatimBlockComment,
56 // VerbatimBlockLineComment, VerbatimLineComment).
57 SmallString<64> Text; // Text of the comment.
58 SmallString<16> Name; // Name of the comment (for Verbatim and HTML).
59 SmallString<8> Direction; // Parameter direction (for (T)ParamCommand).
60 SmallString<16> ParamName; // Parameter name (for (T)ParamCommand).
61 SmallString<16> CloseName; // Closing tag name (for VerbatimBlock).
62 bool SelfClosing = false; // Indicates if tag is self-closing (for HTML).
63 bool Explicit = false; // Indicates if the direction of a param is explicit
64 // (for (T)ParamCommand).
65 llvm::SmallVector<SmallString<16>, 4>
66 AttrKeys; // List of attribute keys (for HTML).
67 llvm::SmallVector<SmallString<16>, 4>
68 AttrValues; // List of attribute values for each key (for HTML).
69 llvm::SmallVector<SmallString<16>, 4>
70 Args; // List of arguments to commands (for InlineCommand).
71 std::vector<std::unique_ptr<CommentInfo>>
72 Children; // List of child comments for this CommentInfo.
73 };
74
75 struct Reference {
76 Reference() = default;
77 Reference(llvm::StringRef Name) : Name(Name) {}
78 Reference(SymbolID USR, StringRef Name, InfoType IT)
79 : USR(USR), Name(Name), RefType(IT) {}
80
81 bool operator==(const Reference &Other) const {
82 return std::tie(USR, Name, RefType) ==
83 std::tie(Other.USR, Other.Name, Other.RefType);
84 }
85
86 SymbolID USR = SymbolID(); // Unique identifer for referenced decl
87 SmallString<16> Name; // Name of type (possibly unresolved).
88 InfoType RefType = InfoType::IT_default; // Indicates the type of this
89 // Reference (namespace, record,
90 // function, enum, default).
91 };
92
93 // A base struct for TypeInfos
94 struct TypeInfo {
95 TypeInfo() = default;
96 TypeInfo(SymbolID Type, StringRef Field, InfoType IT)
97 : Type(Type, Field, IT) {}
98 TypeInfo(llvm::StringRef RefName) : Type(RefName) {}
99
100 bool operator==(const TypeInfo &Other) const { return Type == Other.Type; }
101
102 Reference Type; // Referenced type in this info.
103 };
104
105 // Info for field types.
106 struct FieldTypeInfo : public TypeInfo {
107 FieldTypeInfo() = default;
108 FieldTypeInfo(SymbolID Type, StringRef Field, InfoType IT,
109 llvm::StringRef Name)
110 : TypeInfo(Type, Field, IT), Name(Name) {}
111 FieldTypeInfo(llvm::StringRef RefName, llvm::StringRef Name)
112 : TypeInfo(RefName), Name(Name) {}
113
114 bool operator==(const FieldTypeInfo &Other) const {
115 return std::tie(Type, Name) == std::tie(Other.Type, Other.Name);
116 }
117
118 SmallString<16> Name; // Name associated with this info.
119 };
120
121 // Info for member types.
122 struct MemberTypeInfo : public FieldTypeInfo {
123 MemberTypeInfo() = default;
124 MemberTypeInfo(SymbolID Type, StringRef Field, InfoType IT,
125 llvm::StringRef Name, AccessSpecifier Access)
126 : FieldTypeInfo(Type, Field, IT, Name), Access(Access) {}
127 MemberTypeInfo(llvm::StringRef RefName, llvm::StringRef Name,
128 AccessSpecifier Access)
129 : FieldTypeInfo(RefName, Name), Access(Access) {}
130
131 bool operator==(const MemberTypeInfo &Other) const {
132 return std::tie(Type, Name, Access) ==
133 std::tie(Other.Type, Other.Name, Other.Access);
134 }
135
136 AccessSpecifier Access = AccessSpecifier::AS_none; // Access level associated
137 // with this info (public,
138 // protected, private,
139 // none).
140 };
141
142 struct Location {
143 Location() = default;
144 Location(int LineNumber, SmallString<16> Filename)
145 : LineNumber(LineNumber), Filename(std::move(Filename)) {}
146
147 bool operator==(const Location &Other) const {
148 return std::tie(LineNumber, Filename) ==
149 std::tie(Other.LineNumber, Other.Filename);
150 }
151
152 int LineNumber; // Line number of this Location.
153 SmallString<32> Filename; // File for this Location.
154 };
155
156 /// A base struct for Infos.
157 struct Info {
158 Info() = default;
159 Info(InfoType IT) : IT(IT) {}
160 Info(InfoType IT, SymbolID USR) : USR(USR), IT(IT) {}
161 Info(InfoType IT, SymbolID USR, StringRef Name)
162 : USR(USR), IT(IT), Name(Name) {}
163 Info(const Info &Other) = delete;
164 Info(Info &&Other) = default;
165
166 virtual ~Info() = default;
167
168 SymbolID USR =
169 SymbolID(); // Unique identifier for the decl described by this Info.
170 const InfoType IT = InfoType::IT_default; // InfoType of this particular Info.
171 SmallString<16> Name; // Unqualified name of the decl.
172 llvm::SmallVector<Reference, 4>
173 Namespace; // List of parent namespaces for this decl.
174 std::vector<CommentInfo> Description; // Comment description of this decl.
175
176 void mergeBase(Info &&I);
177 bool mergeable(const Info &Other);
178
179 // Returns a reference to the parent scope (that is, the immediate parent
180 // namespace or class in which this decl resides).
181 llvm::Expected<Reference> getEnclosingScope();
182 };
183
184 // Info for namespaces.
185 struct NamespaceInfo : public Info {
186 NamespaceInfo() : Info(InfoType::IT_namespace) {}
187 NamespaceInfo(SymbolID USR) : Info(InfoType::IT_namespace, USR) {}
188 NamespaceInfo(SymbolID USR, StringRef Name)
189 : Info(InfoType::IT_namespace, USR, Name) {}
190
191 void merge(NamespaceInfo &&I);
192
193 // Namespaces and Records are references because they will be properly
194 // documented in their own info, while the entirety of Functions and Enums are
195 // included here because they should not have separate documentation from
196 // their scope.
197 std::vector<Reference> ChildNamespaces;
198 std::vector<Reference> ChildRecords;
199 std::vector<FunctionInfo> ChildFunctions;
200 std::vector<EnumInfo> ChildEnums;
201 };
202
203 // Info for symbols.
204 struct SymbolInfo : public Info {
205 SymbolInfo(InfoType IT) : Info(IT) {}
206 SymbolInfo(InfoType IT, SymbolID USR) : Info(IT, USR) {}
207 SymbolInfo(InfoType IT, SymbolID USR, StringRef Name) : Info(IT, USR, Name) {}
208
209 void merge(SymbolInfo &&I);
210
211 llvm::Optional<Location> DefLoc; // Location where this decl is defined.
212 llvm::SmallVector<Location, 2> Loc; // Locations where this decl is declared.
213 };
214
215 // TODO: Expand to allow for documenting templating and default args.
216 // Info for functions.
217 struct FunctionInfo : public SymbolInfo {
218 FunctionInfo() : SymbolInfo(InfoType::IT_function) {}
219 FunctionInfo(SymbolID USR) : SymbolInfo(InfoType::IT_function, USR) {}
220
221 void merge(FunctionInfo &&I);
222
223 bool IsMethod = false; // Indicates whether this function is a class method.
224 Reference Parent; // Reference to the parent class decl for this method.
225 TypeInfo ReturnType; // Info about the return type of this function.
226 llvm::SmallVector<FieldTypeInfo, 4> Params; // List of parameters.
227 // Access level for this method (public, private, protected, none).
228 AccessSpecifier Access = AccessSpecifier::AS_none;
229 };
230
231 // TODO: Expand to allow for documenting templating, inheritance access,
232 // friend classes
233 // Info for types.
234 struct RecordInfo : public SymbolInfo {
235 RecordInfo() : SymbolInfo(InfoType::IT_record) {}
236 RecordInfo(SymbolID USR) : SymbolInfo(InfoType::IT_record, USR) {}
237 RecordInfo(SymbolID USR, StringRef Name)
238 : SymbolInfo(InfoType::IT_record, USR, Name) {}
239
240 void merge(RecordInfo &&I);
241
242 TagTypeKind TagType = TagTypeKind::TTK_Struct; // Type of this record
243 // (struct, class, union,
244 // interface).
245 llvm::SmallVector<MemberTypeInfo, 4>
246 Members; // List of info about record members.
247 llvm::SmallVector<Reference, 4> Parents; // List of base/parent records
248 // (does not include virtual
249 // parents).
250 llvm::SmallVector<Reference, 4>
251 VirtualParents; // List of virtual base/parent records.
252
253 // Records are references because they will be properly
254 // documented in their own info, while the entirety of Functions and Enums are
255 // included here because they should not have separate documentation from
256 // their scope.
257 std::vector<Reference> ChildRecords;
258 std::vector<FunctionInfo> ChildFunctions;
259 std::vector<EnumInfo> ChildEnums;
260 };
261
262 // TODO: Expand to allow for documenting templating.
263 // Info for types.
264 struct EnumInfo : public SymbolInfo {
265 EnumInfo() : SymbolInfo(InfoType::IT_enum) {}
266 EnumInfo(SymbolID USR) : SymbolInfo(InfoType::IT_enum, USR) {}
267
268 void merge(EnumInfo &&I);
269
270 bool Scoped =
271 false; // Indicates whether this enum is scoped (e.g. enum class).
272 llvm::SmallVector<SmallString<16>, 4> Members; // List of enum members.
273 };
274
275 // TODO: Add functionality to include separate markdown pages.
276
277 // A standalone function to call to merge a vector of infos into one.
278 // This assumes that all infos in the vector are of the same type, and will fail
279 // if they are different.
280 llvm::Expected<std::unique_ptr<Info>>
281 mergeInfos(std::vector<std::unique_ptr<Info>> &Values);
282
283 struct ClangDocContext {
284 tooling::ExecutionContext *ECtx;
285 bool PublicOnly;
286 };
287
288 } // namespace doc
289 } // namespace clang
290
291 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
clang::doc::Info::Namespace
llvm::SmallVector< Reference, 4 > Namespace
Definition: Representation.h:173
clang::doc::InfoType::IT_default
clang::doc::Info::Info
Info(InfoType IT, SymbolID USR)
Definition: Representation.h:160
clang::doc::InfoType::IT_function
clang::doc::SymbolInfo::SymbolInfo
SymbolInfo(InfoType IT, SymbolID USR)
Definition: Representation.h:206
clang::doc::Reference
Definition: Representation.h:75
clang::doc::TypeInfo::Type
Reference Type
Definition: Representation.h:102
clang::doc::Reference::Name
SmallString< 16 > Name
Definition: Representation.h:87
clang::doc::SymbolInfo::DefLoc
llvm::Optional< Location > DefLoc
Definition: Representation.h:211
clang::doc::NamespaceInfo::NamespaceInfo
NamespaceInfo(SymbolID USR, StringRef Name)
Definition: Representation.h:188
clang::doc::RecordInfo::ChildFunctions
std::vector< FunctionInfo > ChildFunctions
Definition: Representation.h:258
clang::doc::FunctionInfo::Parent
Reference Parent
Definition: Representation.h:224
clang::doc::InfoType::IT_enum
clang::doc::InfoType::IT_record
clang::doc::InfoType::IT_namespace
clang::doc::SymbolInfo::Loc
llvm::SmallVector< Location, 2 > Loc
Definition: Representation.h:212
clang::doc::TypeInfo::operator==
bool operator==(const TypeInfo &Other) const
Definition: Representation.h:100
clang::doc::NamespaceInfo::ChildFunctions
std::vector< FunctionInfo > ChildFunctions
Definition: Representation.h:199
clang::doc::NamespaceInfo::ChildEnums
std::vector< EnumInfo > ChildEnums
Definition: Representation.h:200
clang::doc::MemberTypeInfo::MemberTypeInfo
MemberTypeInfo(SymbolID Type, StringRef Field, InfoType IT, llvm::StringRef Name, AccessSpecifier Access)
Definition: Representation.h:124
clang::doc::Reference::operator==
bool operator==(const Reference &Other) const
Definition: Representation.h:81
clang::doc::RecordInfo::ChildRecords
std::vector< Reference > ChildRecords
Definition: Representation.h:257
clang::doc::FunctionInfo::FunctionInfo
FunctionInfo(SymbolID USR)
Definition: Representation.h:219
clang::doc::Reference::Reference
Reference(llvm::StringRef Name)
Definition: Representation.h:77
clang::doc::MemberTypeInfo::operator==
bool operator==(const MemberTypeInfo &Other) const
Definition: Representation.h:131
clang::doc::RecordInfo::VirtualParents
llvm::SmallVector< Reference, 4 > VirtualParents
Definition: Representation.h:251
clang::doc::RecordInfo::RecordInfo
RecordInfo(SymbolID USR)
Definition: Representation.h:236
clang::doc::MemberTypeInfo::MemberTypeInfo
MemberTypeInfo(llvm::StringRef RefName, llvm::StringRef Name, AccessSpecifier Access)
Definition: Representation.h:127
clang::doc::FunctionInfo
Definition: Representation.h:217
clang::doc::Location::Location
Location(int LineNumber, SmallString< 16 > Filename)
Definition: Representation.h:144
clang::doc::FunctionInfo::Params
llvm::SmallVector< FieldTypeInfo, 4 > Params
Definition: Representation.h:226
clang::doc::SymbolInfo
Definition: Representation.h:204
clang::doc::NamespaceInfo::NamespaceInfo
NamespaceInfo(SymbolID USR)
Definition: Representation.h:187
clang::doc::Reference::USR
SymbolID USR
Definition: Representation.h:86
clang::doc::Reference::RefType
InfoType RefType
Definition: Representation.h:88
Filename
std::string Filename
Filename as a string.
Definition: IncludeOrderCheck.cpp:39
clang::doc::EnumInfo::Members
llvm::SmallVector< SmallString< 16 >, 4 > Members
Definition: Representation.h:272
clang::doc::CommentInfo::AttrValues
llvm::SmallVector< SmallString< 16 >, 4 > AttrValues
Definition: Representation.h:68
clang::doc::SymbolInfo::SymbolInfo
SymbolInfo(InfoType IT, SymbolID USR, StringRef Name)
Definition: Representation.h:207
clang::doc::Info::Description
std::vector< CommentInfo > Description
Definition: Representation.h:174
clang::doc::NamespaceInfo
Definition: Representation.h:185
clang::doc::FunctionInfo::FunctionInfo
FunctionInfo()
Definition: Representation.h:218
clang::doc::InfoType
InfoType
Definition: Representation.h:37
clang::doc::RecordInfo
Definition: Representation.h:234
clang::doc::MemberTypeInfo::Access
AccessSpecifier Access
Definition: Representation.h:136
clang::doc::CommentInfo::Args
llvm::SmallVector< SmallString< 16 >, 4 > Args
Definition: Representation.h:70
clang::doc::mergeInfos
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info >> &Values)
Definition: Representation.cpp:95
clang::doc::RecordInfo::RecordInfo
RecordInfo(SymbolID USR, StringRef Name)
Definition: Representation.h:237
clang::doc::Info::Name
SmallString< 16 > Name
Definition: Representation.h:171
Name
static constexpr llvm::StringLiteral Name
Definition: UppercaseLiteralSuffixCheck.cpp:28
clang::doc::ClangDocContext::PublicOnly
bool PublicOnly
Definition: Representation.h:285
clang::doc::Info
A base struct for Infos.
Definition: Representation.h:157
clang::doc::RecordInfo::Parents
llvm::SmallVector< Reference, 4 > Parents
Definition: Representation.h:247
clang::doc::RecordInfo::RecordInfo
RecordInfo()
Definition: Representation.h:235
clang::doc::Location
Definition: Representation.h:142
clang::doc::Reference::Reference
Reference(SymbolID USR, StringRef Name, InfoType IT)
Definition: Representation.h:78
Info
FunctionInfo Info
Definition: FunctionSizeCheck.cpp:121
clang::doc::Location::operator==
bool operator==(const Location &Other) const
Definition: Representation.h:147
clang::doc::CommentInfo::ParamName
SmallString< 16 > ParamName
Definition: Representation.h:60
clang::doc::EnumInfo
Definition: Representation.h:264
clang::doc::ClangDocContext::ECtx
tooling::ExecutionContext * ECtx
Definition: Representation.h:284
clang::doc::CommentInfo::AttrKeys
llvm::SmallVector< SmallString< 16 >, 4 > AttrKeys
Definition: Representation.h:66
clang::doc::CommentInfo::Name
SmallString< 16 > Name
Definition: Representation.h:58
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ChangeNamespace.cpp:18
clang::doc::FieldTypeInfo::Name
SmallString< 16 > Name
Definition: Representation.h:118
clang::doc::TypeInfo::TypeInfo
TypeInfo(SymbolID Type, StringRef Field, InfoType IT)
Definition: Representation.h:96
clang::doc::TypeInfo
Definition: Representation.h:94
clang::doc::MemberTypeInfo
Definition: Representation.h:122
clang::doc::NamespaceInfo::ChildNamespaces
std::vector< Reference > ChildNamespaces
Definition: Representation.h:197
clang::doc::CommentInfo::CloseName
SmallString< 16 > CloseName
Definition: Representation.h:61
clang::doc::NamespaceInfo::ChildRecords
std::vector< Reference > ChildRecords
Definition: Representation.h:198
clang::doc::Location::Filename
SmallString< 32 > Filename
Definition: Representation.h:153
clang::doc::EnumInfo::EnumInfo
EnumInfo()
Definition: Representation.h:265
clang::doc::CommentInfo::Direction
SmallString< 8 > Direction
Definition: Representation.h:59
clang::doc::RecordInfo::ChildEnums
std::vector< EnumInfo > ChildEnums
Definition: Representation.h:259
clang::doc::FunctionInfo::ReturnType
TypeInfo ReturnType
Definition: Representation.h:225
clang::doc::FieldTypeInfo::operator==
bool operator==(const FieldTypeInfo &Other) const
Definition: Representation.h:114
clang::doc::FieldTypeInfo
Definition: Representation.h:106
clang::doc::EnumInfo::EnumInfo
EnumInfo(SymbolID USR)
Definition: Representation.h:266
clang::doc::RecordInfo::Members
llvm::SmallVector< MemberTypeInfo, 4 > Members
Definition: Representation.h:246
clang::doc::SymbolInfo::SymbolInfo
SymbolInfo(InfoType IT)
Definition: Representation.h:205
clang::doc::CommentInfo::Kind
SmallString< 16 > Kind
Definition: Representation.h:52
clang::doc::FieldTypeInfo::FieldTypeInfo
FieldTypeInfo(SymbolID Type, StringRef Field, InfoType IT, llvm::StringRef Name)
Definition: Representation.h:108
clang::doc::CommentInfo::Children
std::vector< std::unique_ptr< CommentInfo > > Children
Definition: Representation.h:72
clang::doc::CommentInfo::Text
SmallString< 64 > Text
Definition: Representation.h:57
clang::doc::SymbolID
std::array< uint8_t, 20 > SymbolID
Definition: Representation.h:31
clang::doc::ClangDocContext
Definition: Representation.h:283
clang::doc::Info::Info
Info(InfoType IT, SymbolID USR, StringRef Name)
Definition: Representation.h:161
clang::doc::FieldTypeInfo::FieldTypeInfo
FieldTypeInfo(llvm::StringRef RefName, llvm::StringRef Name)
Definition: Representation.h:111
clang::doc::CommentInfo
Definition: Representation.h:46
clang::doc::TypeInfo::TypeInfo
TypeInfo(llvm::StringRef RefName)
Definition: Representation.h:98
clang::doc::NamespaceInfo::NamespaceInfo
NamespaceInfo()
Definition: Representation.h:186
clang::doc::Info::Info
Info(InfoType IT)
Definition: Representation.h:159
clang::doc::Location::LineNumber
int LineNumber
Definition: Representation.h:152