clang-tools 19.0.0git
Representation.cpp
Go to the documentation of this file.
1///===-- Representation.cpp - ClangDoc Representation -----------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file defines the merging of different types of infos. The data in the
10// calling Info is preserved during a merge unless that field is empty or
11// default. In that case, the data from the parameter Info is used to replace
12// the empty or default data.
13//
14// For most fields, the first decl seen provides the data. Exceptions to this
15// include the location and description fields, which are collections of data on
16// all decls related to a given definition. All other fields are ignored in new
17// decls unless the first seen decl didn't, for whatever reason, incorporate
18// data on that field (e.g. a forward declared class wouldn't have information
19// on members on the forward declaration, but would have the class name).
20//
21//===----------------------------------------------------------------------===//
22#include "Representation.h"
23#include "llvm/Support/Error.h"
24#include "llvm/Support/Path.h"
25
26namespace clang {
27namespace doc {
28
29namespace {
30
31const SymbolID EmptySID = SymbolID();
32
33template <typename T>
34llvm::Expected<std::unique_ptr<Info>>
35reduce(std::vector<std::unique_ptr<Info>> &Values) {
36 if (Values.empty() || !Values[0])
37 return llvm::createStringError(llvm::inconvertibleErrorCode(),
38 "no value to reduce");
39 std::unique_ptr<Info> Merged = std::make_unique<T>(Values[0]->USR);
40 T *Tmp = static_cast<T *>(Merged.get());
41 for (auto &I : Values)
42 Tmp->merge(std::move(*static_cast<T *>(I.get())));
43 return std::move(Merged);
44}
45
46// Return the index of the matching child in the vector, or -1 if merge is not
47// necessary.
48template <typename T>
49int getChildIndexIfExists(std::vector<T> &Children, T &ChildToMerge) {
50 for (unsigned long I = 0; I < Children.size(); I++) {
51 if (ChildToMerge.USR == Children[I].USR)
52 return I;
53 }
54 return -1;
55}
56
57template <typename T>
58void reduceChildren(std::vector<T> &Children,
59 std::vector<T> &&ChildrenToMerge) {
60 for (auto &ChildToMerge : ChildrenToMerge) {
61 int MergeIdx = getChildIndexIfExists(Children, ChildToMerge);
62 if (MergeIdx == -1) {
63 Children.push_back(std::move(ChildToMerge));
64 continue;
65 }
66 Children[MergeIdx].merge(std::move(ChildToMerge));
67 }
68}
69
70} // namespace
71
72// Dispatch function.
73llvm::Expected<std::unique_ptr<Info>>
74mergeInfos(std::vector<std::unique_ptr<Info>> &Values) {
75 if (Values.empty() || !Values[0])
76 return llvm::createStringError(llvm::inconvertibleErrorCode(),
77 "no info values to merge");
78
79 switch (Values[0]->IT) {
81 return reduce<NamespaceInfo>(Values);
83 return reduce<RecordInfo>(Values);
85 return reduce<EnumInfo>(Values);
87 return reduce<FunctionInfo>(Values);
89 return reduce<TypedefInfo>(Values);
90 default:
91 return llvm::createStringError(llvm::inconvertibleErrorCode(),
92 "unexpected info type");
93 }
94}
95
96bool CommentInfo::operator==(const CommentInfo &Other) const {
97 auto FirstCI = std::tie(Kind, Text, Name, Direction, ParamName, CloseName,
99 auto SecondCI =
100 std::tie(Other.Kind, Other.Text, Other.Name, Other.Direction,
101 Other.ParamName, Other.CloseName, Other.SelfClosing,
102 Other.Explicit, Other.AttrKeys, Other.AttrValues, Other.Args);
103
104 if (FirstCI != SecondCI || Children.size() != Other.Children.size())
105 return false;
106
107 return std::equal(Children.begin(), Children.end(), Other.Children.begin(),
108 llvm::deref<std::equal_to<>>{});
109}
110
111bool CommentInfo::operator<(const CommentInfo &Other) const {
112 auto FirstCI = std::tie(Kind, Text, Name, Direction, ParamName, CloseName,
114 auto SecondCI =
115 std::tie(Other.Kind, Other.Text, Other.Name, Other.Direction,
116 Other.ParamName, Other.CloseName, Other.SelfClosing,
117 Other.Explicit, Other.AttrKeys, Other.AttrValues, Other.Args);
118
119 if (FirstCI < SecondCI)
120 return true;
121
122 if (FirstCI == SecondCI) {
123 return std::lexicographical_compare(
124 Children.begin(), Children.end(), Other.Children.begin(),
125 Other.Children.end(), llvm::deref<std::less<>>());
126 }
127
128 return false;
129}
130
131static llvm::SmallString<64>
133 const StringRef &Name, const StringRef &CurrentPath) {
134 llvm::SmallString<64> FilePath;
135
136 if (CurrentPath != Path) {
137 // iterate back to the top
138 for (llvm::sys::path::const_iterator I =
139 llvm::sys::path::begin(CurrentPath);
140 I != llvm::sys::path::end(CurrentPath); ++I)
141 llvm::sys::path::append(FilePath, "..");
142 llvm::sys::path::append(FilePath, Path);
143 }
144
145 // Namespace references have a Path to the parent namespace, but
146 // the file is actually in the subdirectory for the namespace.
148 llvm::sys::path::append(FilePath, Name);
149
150 return llvm::sys::path::relative_path(FilePath);
151}
152
153llvm::SmallString<64>
154Reference::getRelativeFilePath(const StringRef &CurrentPath) const {
155 return calculateRelativeFilePath(RefType, Path, Name, CurrentPath);
156}
157
158llvm::SmallString<16> Reference::getFileBaseName() const {
160 return llvm::SmallString<16>("index");
161
162 return Name;
163}
164
165llvm::SmallString<64>
166Info::getRelativeFilePath(const StringRef &CurrentPath) const {
167 return calculateRelativeFilePath(IT, Path, extractName(), CurrentPath);
168}
169
170llvm::SmallString<16> Info::getFileBaseName() const {
172 return llvm::SmallString<16>("index");
173
174 return extractName();
175}
176
177bool Reference::mergeable(const Reference &Other) {
178 return RefType == Other.RefType && USR == Other.USR;
179}
180
182 assert(mergeable(Other));
183 if (Name.empty())
184 Name = Other.Name;
185 if (Path.empty())
186 Path = Other.Path;
187}
188
189void Info::mergeBase(Info &&Other) {
190 assert(mergeable(Other));
191 if (USR == EmptySID)
192 USR = Other.USR;
193 if (Name == "")
194 Name = Other.Name;
195 if (Path == "")
196 Path = Other.Path;
197 if (Namespace.empty())
198 Namespace = std::move(Other.Namespace);
199 // Unconditionally extend the description, since each decl may have a comment.
200 std::move(Other.Description.begin(), Other.Description.end(),
201 std::back_inserter(Description));
202 llvm::sort(Description);
203 auto Last = std::unique(Description.begin(), Description.end());
204 Description.erase(Last, Description.end());
205}
206
207bool Info::mergeable(const Info &Other) {
208 return IT == Other.IT && USR == Other.USR;
209}
210
211void SymbolInfo::merge(SymbolInfo &&Other) {
212 assert(mergeable(Other));
213 if (!DefLoc)
214 DefLoc = std::move(Other.DefLoc);
215 // Unconditionally extend the list of locations, since we want all of them.
216 std::move(Other.Loc.begin(), Other.Loc.end(), std::back_inserter(Loc));
217 llvm::sort(Loc);
218 auto Last = std::unique(Loc.begin(), Loc.end());
219 Loc.erase(Last, Loc.end());
220 mergeBase(std::move(Other));
221}
222
225
227 assert(mergeable(Other));
228 // Reduce children if necessary.
229 reduceChildren(Children.Namespaces, std::move(Other.Children.Namespaces));
230 reduceChildren(Children.Records, std::move(Other.Children.Records));
231 reduceChildren(Children.Functions, std::move(Other.Children.Functions));
232 reduceChildren(Children.Enums, std::move(Other.Children.Enums));
233 reduceChildren(Children.Typedefs, std::move(Other.Children.Typedefs));
234 mergeBase(std::move(Other));
235}
236
239
241 assert(mergeable(Other));
242 if (!llvm::to_underlying(TagType))
243 TagType = Other.TagType;
244 IsTypeDef = IsTypeDef || Other.IsTypeDef;
245 if (Members.empty())
246 Members = std::move(Other.Members);
247 if (Bases.empty())
248 Bases = std::move(Other.Bases);
249 if (Parents.empty())
250 Parents = std::move(Other.Parents);
251 if (VirtualParents.empty())
252 VirtualParents = std::move(Other.VirtualParents);
253 // Reduce children if necessary.
254 reduceChildren(Children.Records, std::move(Other.Children.Records));
255 reduceChildren(Children.Functions, std::move(Other.Children.Functions));
256 reduceChildren(Children.Enums, std::move(Other.Children.Enums));
257 reduceChildren(Children.Typedefs, std::move(Other.Children.Typedefs));
258 SymbolInfo::merge(std::move(Other));
259 if (!Template)
260 Template = Other.Template;
261}
262
264 assert(mergeable(Other));
265 if (!Scoped)
266 Scoped = Other.Scoped;
267 if (Members.empty())
268 Members = std::move(Other.Members);
269 SymbolInfo::merge(std::move(Other));
270}
271
273 assert(mergeable(Other));
274 if (!IsMethod)
275 IsMethod = Other.IsMethod;
276 if (!Access)
277 Access = Other.Access;
279 ReturnType = std::move(Other.ReturnType);
280 if (Parent.USR == EmptySID && Parent.Name == "")
281 Parent = std::move(Other.Parent);
282 if (Params.empty())
283 Params = std::move(Other.Params);
284 SymbolInfo::merge(std::move(Other));
285 if (!Template)
286 Template = Other.Template;
287}
288
290 assert(mergeable(Other));
291 if (!IsUsing)
292 IsUsing = Other.IsUsing;
293 if (Underlying.Type.Name == "")
294 Underlying = Other.Underlying;
295 SymbolInfo::merge(std::move(Other));
296}
297
299
301 bool IsVirtual, AccessSpecifier Access,
302 bool IsParent)
303 : RecordInfo(USR, Name, Path), IsVirtual(IsVirtual), Access(Access),
304 IsParent(IsParent) {}
305
306llvm::SmallString<16> Info::extractName() const {
307 if (!Name.empty())
308 return Name;
309
310 switch (IT) {
312 // Cover the case where the project contains a base namespace called
313 // 'GlobalNamespace' (i.e. a namespace at the same level as the global
314 // namespace, which would conflict with the hard-coded global namespace name
315 // below.)
316 if (Name == "GlobalNamespace" && Namespace.empty())
317 return llvm::SmallString<16>("@GlobalNamespace");
318 // The case of anonymous namespaces is taken care of in serialization,
319 // so here we can safely assume an unnamed namespace is the global
320 // one.
321 return llvm::SmallString<16>("GlobalNamespace");
323 return llvm::SmallString<16>("@nonymous_record_" +
324 toHex(llvm::toStringRef(USR)));
326 return llvm::SmallString<16>("@nonymous_enum_" +
327 toHex(llvm::toStringRef(USR)));
329 return llvm::SmallString<16>("@nonymous_typedef_" +
330 toHex(llvm::toStringRef(USR)));
332 return llvm::SmallString<16>("@nonymous_function_" +
333 toHex(llvm::toStringRef(USR)));
335 return llvm::SmallString<16>("@nonymous_" + toHex(llvm::toStringRef(USR)));
336 }
337 llvm_unreachable("Invalid InfoType.");
338 return llvm::SmallString<16>("");
339}
340
341// Order is based on the Name attribute: case insensitive order
342bool Index::operator<(const Index &Other) const {
343 // Loop through each character of both strings
344 for (unsigned I = 0; I < Name.size() && I < Other.Name.size(); ++I) {
345 // Compare them after converting both to lower case
346 int D = tolower(Name[I]) - tolower(Other.Name[I]);
347 if (D == 0)
348 continue;
349 return D < 0;
350 }
351 // If both strings have the size it means they would be equal if changed to
352 // lower case. In here, lower case will be smaller than upper case
353 // Example: string < stRing = true
354 // This is the opposite of how operator < handles strings
355 if (Name.size() == Other.Name.size())
356 return Name > Other.Name;
357 // If they are not the same size; the shorter string is smaller
358 return Name.size() < Other.Name.size();
359}
360
362 llvm::sort(Children);
363 for (auto &C : Children)
364 C.sort();
365}
366
367ClangDocContext::ClangDocContext(tooling::ExecutionContext *ECtx,
368 StringRef ProjectName, bool PublicOnly,
369 StringRef OutDirectory, StringRef SourceRoot,
370 StringRef RepositoryUrl,
371 std::vector<std::string> UserStylesheets)
374 llvm::SmallString<128> SourceRootDir(SourceRoot);
375 if (SourceRoot.empty())
376 // If no SourceRoot was provided the current path is used as the default
377 llvm::sys::fs::current_path(SourceRootDir);
378 this->SourceRoot = std::string(SourceRootDir);
379 if (!RepositoryUrl.empty()) {
380 this->RepositoryUrl = std::string(RepositoryUrl);
381 if (!RepositoryUrl.empty() && !RepositoryUrl.starts_with("http://") &&
382 !RepositoryUrl.starts_with("https://"))
383 this->RepositoryUrl->insert(0, "https://");
384 }
385}
386
387} // namespace doc
388} // namespace clang
llvm::SmallString< 256U > Name
static llvm::cl::opt< bool > PublicOnly("public", llvm::cl::desc("Document only public declarations."), llvm::cl::init(false), llvm::cl::cat(ClangDocCategory))
static llvm::cl::opt< std::string > ProjectName("project-name", llvm::cl::desc("Name of project."), llvm::cl::cat(ClangDocCategory))
static llvm::cl::list< std::string > UserStylesheets("stylesheets", llvm::cl::CommaSeparated, llvm::cl::desc("CSS stylesheets to extend the default styles."), llvm::cl::cat(ClangDocCategory))
static llvm::cl::opt< std::string > SourceRoot("source-root", llvm::cl::desc(R"( Directory where processed files are stored. Links to definition locations will only be generated if the file is in this dir.)"), llvm::cl::cat(ClangDocCategory))
static llvm::cl::opt< std::string > OutDirectory("output", llvm::cl::desc("Directory for outputting generated files."), llvm::cl::init("docs"), llvm::cl::cat(ClangDocCategory))
static llvm::cl::opt< std::string > RepositoryUrl("repository", llvm::cl::desc(R"( URL of repository that hosts code. Used for links to definition locations.)"), llvm::cl::cat(ClangDocCategory))
const Criteria C
std::vector< std::unique_ptr< HTMLNode > > Children
NodeType Type
std::vector< HeaderHandle > Path
std::string USR
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info > > &Values)
static llvm::SmallString< 64 > calculateRelativeFilePath(const InfoType &Type, const StringRef &Path, const StringRef &Name, const StringRef &CurrentPath)
std::array< uint8_t, 20 > SymbolID
static const SymbolID EmptySID
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
std::optional< std::string > RepositoryUrl
SmallString< 8 > Direction
SmallString< 16 > Kind
std::vector< std::unique_ptr< CommentInfo > > Children
bool operator<(const CommentInfo &Other) const
llvm::SmallVector< SmallString< 16 >, 4 > AttrValues
SmallString< 16 > CloseName
bool operator==(const CommentInfo &Other) const
SmallString< 16 > Name
SmallString< 64 > Text
llvm::SmallVector< SmallString< 16 >, 4 > AttrKeys
llvm::SmallVector< SmallString< 16 >, 4 > Args
SmallString< 16 > ParamName
llvm::SmallVector< EnumValueInfo, 4 > Members
void merge(EnumInfo &&I)
llvm::SmallVector< FieldTypeInfo, 4 > Params
void merge(FunctionInfo &&I)
std::optional< TemplateInfo > Template
std::vector< Index > Children
bool operator<(const Index &Other) const
A base struct for Infos.
bool mergeable(const Info &Other)
SmallString< 16 > Name
llvm::SmallString< 16 > getFileBaseName() const
Returns the basename that should be used for this Info.
std::vector< CommentInfo > Description
llvm::SmallString< 128 > Path
void mergeBase(Info &&I)
llvm::SmallString< 16 > extractName() const
llvm::SmallString< 64 > getRelativeFilePath(const StringRef &CurrentPath) const
Returns the file path for this Info relative to CurrentPath.
const InfoType IT
llvm::SmallVector< Reference, 4 > Namespace
NamespaceInfo(SymbolID USR=SymbolID(), StringRef Name=StringRef(), StringRef Path=StringRef())
void merge(NamespaceInfo &&I)
llvm::SmallVector< MemberTypeInfo, 4 > Members
RecordInfo(SymbolID USR=SymbolID(), StringRef Name=StringRef(), StringRef Path=StringRef())
std::optional< TemplateInfo > Template
llvm::SmallVector< Reference, 4 > VirtualParents
llvm::SmallVector< Reference, 4 > Parents
void merge(RecordInfo &&I)
std::vector< BaseRecordInfo > Bases
void merge(Reference &&I)
bool mergeable(const Reference &Other)
llvm::SmallString< 128 > Path
llvm::SmallString< 64 > getRelativeFilePath(const StringRef &CurrentPath) const
Returns the path for this Reference relative to CurrentPath.
llvm::SmallString< 16 > getFileBaseName() const
Returns the basename that should be used for this Reference.
SmallString< 16 > Name
std::vector< Reference > Records
std::vector< TypedefInfo > Typedefs
std::vector< FunctionInfo > Functions
std::vector< Reference > Namespaces
std::vector< EnumInfo > Enums
llvm::SmallVector< Location, 2 > Loc
std::optional< Location > DefLoc
void merge(TypedefInfo &&I)