clang-tools  7.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 enum class InfoType {
35  IT_default,
37  IT_record,
39  IT_enum
40 };
41 
42 // A representation of a parsed comment.
43 struct CommentInfo {
44  CommentInfo() = default;
45  CommentInfo(CommentInfo &Other) = delete;
46  CommentInfo(CommentInfo &&Other) = default;
47 
48  SmallString<16> Kind; // Kind of comment (TextComment, InlineCommandComment,
49  // HTMLStartTagComment, HTMLEndTagComment,
50  // BlockCommandComment, ParamCommandComment,
51  // TParamCommandComment, VerbatimBlockComment,
52  // VerbatimBlockLineComment, VerbatimLineComment).
53  SmallString<64> Text; // Text of the comment.
54  SmallString<16> Name; // Name of the comment (for Verbatim and HTML).
55  SmallString<8> Direction; // Parameter direction (for (T)ParamCommand).
56  SmallString<16> ParamName; // Parameter name (for (T)ParamCommand).
57  SmallString<16> CloseName; // Closing tag name (for VerbatimBlock).
58  bool SelfClosing = false; // Indicates if tag is self-closing (for HTML).
59  bool Explicit = false; // Indicates if the direction of a param is explicit
60  // (for (T)ParamCommand).
61  llvm::SmallVector<SmallString<16>, 4>
62  AttrKeys; // List of attribute keys (for HTML).
63  llvm::SmallVector<SmallString<16>, 4>
64  AttrValues; // List of attribute values for each key (for HTML).
65  llvm::SmallVector<SmallString<16>, 4>
66  Args; // List of arguments to commands (for InlineCommand).
67  std::vector<std::unique_ptr<CommentInfo>>
68  Children; // List of child comments for this CommentInfo.
69 };
70 
71 struct Reference {
72  Reference() = default;
73  Reference(llvm::StringRef Name) : Name(Name) {}
74  Reference(SymbolID USR, StringRef Name, InfoType IT)
75  : USR(USR), Name(Name), RefType(IT) {}
76 
77  bool operator==(const Reference &Other) const {
78  return std::tie(USR, Name, RefType) ==
79  std::tie(Other.USR, Other.Name, Other.RefType);
80  }
81 
82  SymbolID USR = SymbolID(); // Unique identifer for referenced decl
83  SmallString<16> Name; // Name of type (possibly unresolved).
84  InfoType RefType = InfoType::IT_default; // Indicates the type of this
85  // Reference (namespace, record,
86  // function, enum, default).
87 };
88 
89 // A base struct for TypeInfos
90 struct TypeInfo {
91  TypeInfo() = default;
92  TypeInfo(SymbolID Type, StringRef Field, InfoType IT)
93  : Type(Type, Field, IT) {}
94  TypeInfo(llvm::StringRef RefName) : Type(RefName) {}
95 
96  bool operator==(const TypeInfo &Other) const { return Type == Other.Type; }
97 
98  Reference Type; // Referenced type in this info.
99 };
100 
101 // Info for field types.
102 struct FieldTypeInfo : public TypeInfo {
103  FieldTypeInfo() = default;
104  FieldTypeInfo(SymbolID Type, StringRef Field, InfoType IT,
105  llvm::StringRef Name)
106  : TypeInfo(Type, Field, IT), Name(Name) {}
107  FieldTypeInfo(llvm::StringRef RefName, llvm::StringRef Name)
108  : TypeInfo(RefName), Name(Name) {}
109 
110  bool operator==(const FieldTypeInfo &Other) const {
111  return std::tie(Type, Name) == std::tie(Other.Type, Other.Name);
112  }
113 
114  SmallString<16> Name; // Name associated with this info.
115 };
116 
117 // Info for member types.
118 struct MemberTypeInfo : public FieldTypeInfo {
119  MemberTypeInfo() = default;
120  MemberTypeInfo(SymbolID Type, StringRef Field, InfoType IT,
121  llvm::StringRef Name, AccessSpecifier Access)
122  : FieldTypeInfo(Type, Field, IT, Name), Access(Access) {}
123  MemberTypeInfo(llvm::StringRef RefName, llvm::StringRef Name,
124  AccessSpecifier Access)
125  : FieldTypeInfo(RefName, Name), Access(Access) {}
126 
127  bool operator==(const MemberTypeInfo &Other) const {
128  return std::tie(Type, Name, Access) ==
129  std::tie(Other.Type, Other.Name, Other.Access);
130  }
131 
132  AccessSpecifier Access = AccessSpecifier::AS_none; // Access level associated
133  // with this info (public,
134  // protected, private,
135  // none).
136 };
137 
138 struct Location {
139  Location() = default;
140  Location(int LineNumber, SmallString<16> Filename)
141  : LineNumber(LineNumber), Filename(std::move(Filename)) {}
142 
143  bool operator==(const Location &Other) const {
144  return std::tie(LineNumber, Filename) ==
145  std::tie(Other.LineNumber, Other.Filename);
146  }
147 
148  int LineNumber; // Line number of this Location.
149  SmallString<32> Filename; // File for this Location.
150 };
151 
152 /// A base struct for Infos.
153 struct Info {
154  Info() = default;
155  Info(InfoType IT) : IT(IT) {}
156  Info(const Info &Other) = delete;
157  Info(Info &&Other) = default;
158 
159  SymbolID USR =
160  SymbolID(); // Unique identifier for the decl described by this Info.
161  const InfoType IT = InfoType::IT_default; // InfoType of this particular Info.
162  SmallString<16> Name; // Unqualified name of the decl.
163  llvm::SmallVector<Reference, 4>
164  Namespace; // List of parent namespaces for this decl.
165  std::vector<CommentInfo> Description; // Comment description of this decl.
166 
167  void mergeBase(Info &&I);
168  bool mergeable(const Info &Other);
169 };
170 
171 // Info for namespaces.
172 struct NamespaceInfo : public Info {
174 
175  void merge(NamespaceInfo &&I);
176 };
177 
178 // Info for symbols.
179 struct SymbolInfo : public Info {
180  SymbolInfo(InfoType IT) : Info(IT) {}
181 
182  void merge(SymbolInfo &&I);
183 
184  llvm::Optional<Location> DefLoc; // Location where this decl is defined.
185  llvm::SmallVector<Location, 2> Loc; // Locations where this decl is declared.
186 };
187 
188 // TODO: Expand to allow for documenting templating and default args.
189 // Info for functions.
190 struct FunctionInfo : public SymbolInfo {
192 
193  void merge(FunctionInfo &&I);
194 
195  bool IsMethod = false; // Indicates whether this function is a class method.
196  Reference Parent; // Reference to the parent class decl for this method.
197  TypeInfo ReturnType; // Info about the return type of this function.
198  llvm::SmallVector<FieldTypeInfo, 4> Params; // List of parameters.
199  // Access level for this method (public, private, protected, none).
200  AccessSpecifier Access = AccessSpecifier::AS_none;
201 };
202 
203 // TODO: Expand to allow for documenting templating, inheritance access,
204 // friend classes
205 // Info for types.
206 struct RecordInfo : public SymbolInfo {
208 
209  void merge(RecordInfo &&I);
210 
211  TagTypeKind TagType = TagTypeKind::TTK_Struct; // Type of this record
212  // (struct, class, union,
213  // interface).
214  llvm::SmallVector<MemberTypeInfo, 4>
215  Members; // List of info about record members.
216  llvm::SmallVector<Reference, 4> Parents; // List of base/parent records
217  // (does not include virtual
218  // parents).
219  llvm::SmallVector<Reference, 4>
220  VirtualParents; // List of virtual base/parent records.
221 };
222 
223 // TODO: Expand to allow for documenting templating.
224 // Info for types.
225 struct EnumInfo : public SymbolInfo {
226  EnumInfo() : SymbolInfo(InfoType::IT_enum) {}
227 
228  void merge(EnumInfo &&I);
229 
230  bool Scoped =
231  false; // Indicates whether this enum is scoped (e.g. enum class).
232  llvm::SmallVector<SmallString<16>, 4> Members; // List of enum members.
233 };
234 
235 // TODO: Add functionality to include separate markdown pages.
236 
237 // A standalone function to call to merge a vector of infos into one.
238 // This assumes that all infos in the vector are of the same type, and will fail
239 // if they are different.
240 llvm::Expected<std::unique_ptr<Info>>
241 mergeInfos(std::vector<std::unique_ptr<Info>> &Values);
242 
244  tooling::ExecutionContext *ECtx;
246 };
247 
248 } // namespace doc
249 } // namespace clang
250 
251 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H
llvm::StringRef Name
llvm::SmallVector< Reference, 4 > Namespace
SmallString< 16 > Name
llvm::Optional< Location > DefLoc
llvm::SmallVector< Location, 2 > Loc
bool operator==(const TypeInfo &Other) const
MemberTypeInfo(SymbolID Type, StringRef Field, InfoType IT, llvm::StringRef Name, AccessSpecifier Access)
bool operator==(const Reference &Other) const
Reference(llvm::StringRef Name)
bool operator==(const MemberTypeInfo &Other) const
llvm::SmallVector< Reference, 4 > VirtualParents
MemberTypeInfo(llvm::StringRef RefName, llvm::StringRef Name, AccessSpecifier Access)
Location(int LineNumber, SmallString< 16 > Filename)
llvm::SmallVector< FieldTypeInfo, 4 > Params
std::string Filename
Filename as a string.
llvm::SmallVector< SmallString< 16 >, 4 > Members
llvm::SmallVector< SmallString< 16 >, 4 > AttrValues
std::vector< CommentInfo > Description
llvm::SmallVector< SmallString< 16 >, 4 > Args
llvm::Expected< std::unique_ptr< Info > > mergeInfos(std::vector< std::unique_ptr< Info >> &Values)
SmallString< 16 > Name
A base struct for Infos.
llvm::SmallVector< Reference, 4 > Parents
Reference(SymbolID USR, StringRef Name, InfoType IT)
FunctionInfo Info
bool operator==(const Location &Other) const
SmallString< 16 > ParamName
tooling::ExecutionContext * ECtx
llvm::SmallVector< SmallString< 16 >, 4 > AttrKeys
SmallString< 16 > Name
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
SmallString< 16 > Name
TypeInfo(SymbolID Type, StringRef Field, InfoType IT)
SmallString< 16 > CloseName
SmallString< 32 > Filename
SmallString< 8 > Direction
bool operator==(const FieldTypeInfo &Other) const
llvm::SmallVector< MemberTypeInfo, 4 > Members
SmallString< 16 > Kind
FieldTypeInfo(SymbolID Type, StringRef Field, InfoType IT, llvm::StringRef Name)
std::vector< std::unique_ptr< CommentInfo > > Children
SmallString< 64 > Text
std::array< uint8_t, 20 > SymbolID
FieldTypeInfo(llvm::StringRef RefName, llvm::StringRef Name)
TypeInfo(llvm::StringRef RefName)
Info(InfoType IT)