clang 18.0.0git
Comment.cpp
Go to the documentation of this file.
1//===--- Comment.cpp - Comment AST node implementation --------------------===//
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#include "clang/AST/Comment.h"
11#include "clang/AST/Decl.h"
12#include "clang/AST/DeclObjC.h"
15#include "llvm/Support/ErrorHandling.h"
16#include <type_traits>
17
18namespace clang {
19namespace comments {
20
21// Check that no comment class has a non-trival destructor. They are allocated
22// with a BumpPtrAllocator and therefore their destructor is not executed.
23#define ABSTRACT_COMMENT(COMMENT)
24#define COMMENT(CLASS, PARENT) \
25 static_assert(std::is_trivially_destructible<CLASS>::value, \
26 #CLASS " should be trivially destructible!");
27#include "clang/AST/CommentNodes.inc"
28#undef COMMENT
29#undef ABSTRACT_COMMENT
30
31// DeclInfo is also allocated with a BumpPtrAllocator.
32static_assert(std::is_trivially_destructible_v<DeclInfo>,
33 "DeclInfo should be trivially destructible!");
34
35const char *Comment::getCommentKindName() const {
36 switch (getCommentKind()) {
37 case NoCommentKind: return "NoCommentKind";
38#define ABSTRACT_COMMENT(COMMENT)
39#define COMMENT(CLASS, PARENT) \
40 case CLASS##Kind: \
41 return #CLASS;
42#include "clang/AST/CommentNodes.inc"
43#undef COMMENT
44#undef ABSTRACT_COMMENT
45 }
46 llvm_unreachable("Unknown comment kind!");
47}
48
49namespace {
50struct good {};
51struct bad {};
52
53template <typename T>
54good implements_child_begin_end(Comment::child_iterator (T::*)() const) {
55 return good();
56}
57
58LLVM_ATTRIBUTE_UNUSED
59static inline bad implements_child_begin_end(
60 Comment::child_iterator (Comment::*)() const) {
61 return bad();
62}
63
64#define ASSERT_IMPLEMENTS_child_begin(function) \
65 (void) good(implements_child_begin_end(function))
66
67LLVM_ATTRIBUTE_UNUSED
68static inline void CheckCommentASTNodes() {
69#define ABSTRACT_COMMENT(COMMENT)
70#define COMMENT(CLASS, PARENT) \
71 ASSERT_IMPLEMENTS_child_begin(&CLASS::child_begin); \
72 ASSERT_IMPLEMENTS_child_begin(&CLASS::child_end);
73#include "clang/AST/CommentNodes.inc"
74#undef COMMENT
75#undef ABSTRACT_COMMENT
76}
77
78#undef ASSERT_IMPLEMENTS_child_begin
79
80} // end unnamed namespace
81
83 switch (getCommentKind()) {
84 case NoCommentKind: llvm_unreachable("comment without a kind");
85#define ABSTRACT_COMMENT(COMMENT)
86#define COMMENT(CLASS, PARENT) \
87 case CLASS##Kind: \
88 return static_cast<const CLASS *>(this)->child_begin();
89#include "clang/AST/CommentNodes.inc"
90#undef COMMENT
91#undef ABSTRACT_COMMENT
92 }
93 llvm_unreachable("Unknown comment kind!");
94}
95
97 switch (getCommentKind()) {
98 case NoCommentKind: llvm_unreachable("comment without a kind");
99#define ABSTRACT_COMMENT(COMMENT)
100#define COMMENT(CLASS, PARENT) \
101 case CLASS##Kind: \
102 return static_cast<const CLASS *>(this)->child_end();
103#include "clang/AST/CommentNodes.inc"
104#undef COMMENT
105#undef ABSTRACT_COMMENT
106 }
107 llvm_unreachable("Unknown comment kind!");
108}
109
110bool TextComment::isWhitespaceNoCache() const {
111 return llvm::all_of(Text, clang::isWhitespace);
112}
113
114bool ParagraphComment::isWhitespaceNoCache() const {
115 for (child_iterator I = child_begin(), E = child_end(); I != E; ++I) {
116 if (const TextComment *TC = dyn_cast<TextComment>(*I)) {
117 if (!TC->isWhitespace())
118 return false;
119 } else
120 return false;
121 }
122 return true;
123}
124
126 TypeLoc TL = SrcTL.IgnoreParens();
127
128 // Look through attribute types.
129 if (AttributedTypeLoc AttributeTL = TL.getAs<AttributedTypeLoc>())
130 return AttributeTL.getModifiedLoc();
131 // Look through qualified types.
132 if (QualifiedTypeLoc QualifiedTL = TL.getAs<QualifiedTypeLoc>())
133 return QualifiedTL.getUnqualifiedLoc();
134 // Look through pointer types.
135 if (PointerTypeLoc PointerTL = TL.getAs<PointerTypeLoc>())
136 return PointerTL.getPointeeLoc().getUnqualifiedLoc();
137 // Look through reference types.
138 if (ReferenceTypeLoc ReferenceTL = TL.getAs<ReferenceTypeLoc>())
139 return ReferenceTL.getPointeeLoc().getUnqualifiedLoc();
140 // Look through adjusted types.
141 if (AdjustedTypeLoc ATL = TL.getAs<AdjustedTypeLoc>())
142 return ATL.getOriginalLoc();
143 if (BlockPointerTypeLoc BlockPointerTL = TL.getAs<BlockPointerTypeLoc>())
144 return BlockPointerTL.getPointeeLoc().getUnqualifiedLoc();
145 if (MemberPointerTypeLoc MemberPointerTL = TL.getAs<MemberPointerTypeLoc>())
146 return MemberPointerTL.getPointeeLoc().getUnqualifiedLoc();
148 return ETL.getNamedTypeLoc();
149
150 return TL;
151}
152
154 TypeLoc PrevTL;
155 while (PrevTL != TL) {
156 PrevTL = TL;
158 }
159
160 if (FunctionTypeLoc FTL = TL.getAs<FunctionTypeLoc>()) {
161 ResFTL = FTL;
162 return true;
163 }
164
167 // If we have a typedef to a template specialization with exactly one
168 // template argument of a function type, this looks like std::function,
169 // boost::function, or other function wrapper. Treat these typedefs as
170 // functions.
171 if (STL.getNumArgs() != 1)
172 return false;
173 TemplateArgumentLoc MaybeFunction = STL.getArgLoc(0);
174 if (MaybeFunction.getArgument().getKind() != TemplateArgument::Type)
175 return false;
176 TypeSourceInfo *MaybeFunctionTSI = MaybeFunction.getTypeSourceInfo();
177 TypeLoc TL = MaybeFunctionTSI->getTypeLoc().getUnqualifiedLoc();
178 if (FunctionTypeLoc FTL = TL.getAs<FunctionTypeLoc>()) {
179 ResFTL = FTL;
180 return true;
181 }
182 }
183
184 return false;
185}
186
188 switch (D) {
190 return "[in]";
192 return "[out]";
194 return "[in,out]";
195 }
196 llvm_unreachable("unknown PassDirection");
197}
198
200 assert(!IsFilled);
201
202 // Set defaults.
203 Kind = OtherKind;
205 IsObjCMethod = false;
206 IsInstanceMethod = false;
207 IsClassMethod = false;
208 IsVariadic = false;
209 ParamVars = std::nullopt;
210 TemplateParameters = nullptr;
211
212 if (!CommentDecl) {
213 // If there is no declaration, the defaults is our only guess.
214 IsFilled = true;
215 return;
216 }
218
220 const TypeSourceInfo *TSI = nullptr;
221 switch (K) {
222 default:
223 // Defaults are should be good for declarations we don't handle explicitly.
224 break;
225 case Decl::Function:
226 case Decl::CXXMethod:
227 case Decl::CXXConstructor:
228 case Decl::CXXDestructor:
229 case Decl::CXXConversion: {
230 const FunctionDecl *FD = cast<FunctionDecl>(CommentDecl);
232 ParamVars = FD->parameters();
234 unsigned NumLists = FD->getNumTemplateParameterLists();
235 if (NumLists != 0) {
238 FD->getTemplateParameterList(NumLists - 1);
239 }
240
241 if (K == Decl::CXXMethod || K == Decl::CXXConstructor ||
242 K == Decl::CXXDestructor || K == Decl::CXXConversion) {
243 const CXXMethodDecl *MD = cast<CXXMethodDecl>(CommentDecl);
246 }
247 IsVariadic = FD->isVariadic();
248 assert(involvesFunctionType());
249 break;
250 }
251 case Decl::ObjCMethod: {
252 const ObjCMethodDecl *MD = cast<ObjCMethodDecl>(CommentDecl);
254 ParamVars = MD->parameters();
256 IsObjCMethod = true;
259 IsVariadic = MD->isVariadic();
260 assert(involvesFunctionType());
261 break;
262 }
263 case Decl::FunctionTemplate: {
264 const FunctionTemplateDecl *FTD = cast<FunctionTemplateDecl>(CommentDecl);
267 const FunctionDecl *FD = FTD->getTemplatedDecl();
268 ParamVars = FD->parameters();
271 IsVariadic = FD->isVariadic();
272 assert(involvesFunctionType());
273 break;
274 }
275 case Decl::ClassTemplate: {
276 const ClassTemplateDecl *CTD = cast<ClassTemplateDecl>(CommentDecl);
277 Kind = ClassKind;
280 break;
281 }
282 case Decl::ClassTemplatePartialSpecialization: {
284 cast<ClassTemplatePartialSpecializationDecl>(CommentDecl);
285 Kind = ClassKind;
288 break;
289 }
290 case Decl::ClassTemplateSpecialization:
291 Kind = ClassKind;
293 break;
294 case Decl::Record:
295 case Decl::CXXRecord:
296 Kind = ClassKind;
297 break;
298 case Decl::Var:
299 if (const VarTemplateDecl *VTD =
300 cast<VarDecl>(CommentDecl)->getDescribedVarTemplate()) {
302 TemplateParameters = VTD->getTemplateParameters();
303 }
304 [[fallthrough]];
305 case Decl::Field:
306 case Decl::EnumConstant:
307 case Decl::ObjCIvar:
308 case Decl::ObjCAtDefsField:
309 case Decl::ObjCProperty:
310 if (const auto *VD = dyn_cast<DeclaratorDecl>(CommentDecl))
311 TSI = VD->getTypeSourceInfo();
312 else if (const auto *PD = dyn_cast<ObjCPropertyDecl>(CommentDecl))
313 TSI = PD->getTypeSourceInfo();
315 break;
316 case Decl::VarTemplate: {
317 const VarTemplateDecl *VTD = cast<VarTemplateDecl>(CommentDecl);
321 if (const VarDecl *VD = VTD->getTemplatedDecl())
322 TSI = VD->getTypeSourceInfo();
323 break;
324 }
325 case Decl::Namespace:
327 break;
328 case Decl::TypeAlias:
329 case Decl::Typedef:
331 TSI = cast<TypedefNameDecl>(CommentDecl)->getTypeSourceInfo();
332 break;
333 case Decl::TypeAliasTemplate: {
334 const TypeAliasTemplateDecl *TAT = cast<TypeAliasTemplateDecl>(CommentDecl);
338 if (TypeAliasDecl *TAD = TAT->getTemplatedDecl())
339 TSI = TAD->getTypeSourceInfo();
340 break;
341 }
342 case Decl::Enum:
343 Kind = EnumKind;
344 break;
345 }
346
347 // If the type is a typedef / using to something we consider a function,
348 // extract arguments and return type.
349 if (TSI) {
351 FunctionTypeLoc FTL;
352 if (getFunctionTypeLoc(TL, FTL)) {
353 ParamVars = FTL.getParams();
355 if (const auto *FPT = dyn_cast<FunctionProtoType>(FTL.getTypePtr()))
356 IsVariadic = FPT->isVariadic();
357 assert(involvesFunctionType());
358 }
359 }
360
361 IsFilled = true;
362}
363
365 assert(isParamIndexValid());
366 if (isVarArgParam())
367 return "...";
368 return FC->getDeclInfo()->ParamVars[getParamIndex()]->getName();
369}
370
372 assert(isPositionValid());
374 for (unsigned i = 0, e = getDepth(); i != e; ++i) {
375 assert(TPL && "Unknown TemplateParameterList");
376 if (i == e - 1)
377 return TPL->getParam(getIndex(i))->getName();
378 const NamedDecl *Param = TPL->getParam(getIndex(i));
379 if (auto *TTP = dyn_cast<TemplateTemplateParmDecl>(Param))
380 TPL = TTP->getTemplateParameters();
381 }
382 return "";
383}
384
385} // end namespace comments
386} // end namespace clang
387
Defines the clang::ASTContext interface.
Defines the C++ template declaration subclasses.
Type source information for an attributed type.
Definition: TypeLoc.h:869
Wrapper for source info for block pointers.
Definition: TypeLoc.h:1278
Represents a static or instance method of a struct/union/class.
Definition: DeclCXX.h:2035
bool isInstance() const
Definition: DeclCXX.h:2062
Declaration of a class template.
TemplateParameterList * getTemplateParameters() const
Get the list of template parameters.
const TypeClass * getTypePtr() const
Definition: TypeLoc.h:415
Kind
Lists the kind of concrete classes of Decl.
Definition: DeclBase.h:86
Kind getKind() const
Definition: DeclBase.h:435
TemplateParameterList * getTemplateParameterList(unsigned index) const
Definition: Decl.h:859
unsigned getNumTemplateParameterLists() const
Definition: Decl.h:855
Represents a function declaration or definition.
Definition: Decl.h:1919
QualType getReturnType() const
Definition: Decl.h:2657
ArrayRef< ParmVarDecl * > parameters() const
Definition: Decl.h:2603
bool isVariadic() const
Whether this function is variadic.
Definition: Decl.cpp:3062
Declaration of a template function.
FunctionDecl * getTemplatedDecl() const
Get the underlying function declaration of the template.
Wrapper for source info for functions.
Definition: TypeLoc.h:1392
ArrayRef< ParmVarDecl * > getParams() const
Definition: TypeLoc.h:1455
TypeLoc getReturnLoc() const
Definition: TypeLoc.h:1473
Wrapper for source info for member pointers.
Definition: TypeLoc.h:1296
This represents a decl that may have a name.
Definition: Decl.h:247
StringRef getName() const
Get the name of identifier for this declaration as a StringRef.
Definition: Decl.h:274
ObjCMethodDecl - Represents an instance or class method declaration.
Definition: DeclObjC.h:138
ArrayRef< ParmVarDecl * > parameters() const
Definition: DeclObjC.h:375
bool isVariadic() const
Definition: DeclObjC.h:433
bool isInstanceMethod() const
Definition: DeclObjC.h:428
QualType getReturnType() const
Definition: DeclObjC.h:331
Wrapper for source info for pointers.
Definition: TypeLoc.h:1265
Wrapper of type source information for a type with non-trivial direct qualifiers.
Definition: TypeLoc.h:283
Location wrapper for a TemplateArgument.
Definition: TemplateBase.h:484
const TemplateArgument & getArgument() const
Definition: TemplateBase.h:533
TypeSourceInfo * getTypeSourceInfo() const
Definition: TemplateBase.h:541
@ Type
The template argument is a type.
Definition: TemplateBase.h:69
ArgKind getKind() const
Return the kind of stored template argument.
Definition: TemplateBase.h:263
TemplateParameterList * getTemplateParameters() const
Get the list of template parameters.
Definition: DeclTemplate.h:429
Stores a list of template parameters for a TemplateDecl and its derived classes.
Definition: DeclTemplate.h:73
NamedDecl * getParam(unsigned Idx)
Definition: DeclTemplate.h:140
Represents the declaration of a typedef-name via a C++11 alias-declaration.
Definition: Decl.h:3449
Declaration of an alias template.
TypeAliasDecl * getTemplatedDecl() const
Get the underlying function declaration of the template.
Base wrapper for a particular "section" of type source info.
Definition: TypeLoc.h:59
UnqualTypeLoc getUnqualifiedLoc() const
Skips past any qualifiers, if this is qualified.
Definition: TypeLoc.h:332
QualType getType() const
Get the type for which this source info wrapper provides information.
Definition: TypeLoc.h:133
T getAs() const
Convert to the specified TypeLoc type, returning a null TypeLoc if this TypeLoc is not of the desired...
Definition: TypeLoc.h:89
TypeLoc IgnoreParens() const
Definition: TypeLoc.h:1189
A container of type source information.
Definition: Type.h:6718
TypeLoc getTypeLoc() const
Return the TypeLoc wrapper for the type source info.
Definition: TypeLoc.h:250
Represents a variable declaration or definition.
Definition: Decl.h:915
Declaration of a variable template.
VarDecl * getTemplatedDecl() const
Get the underlying variable declarations of the template.
Comment *const * child_iterator
Definition: Comment.h:227
child_iterator child_end() const
Definition: Comment.cpp:96
child_iterator child_begin() const
Definition: Comment.cpp:82
const char * getCommentKindName() const
Definition: Comment.cpp:35
CommentKind getCommentKind() const
Definition: Comment.h:209
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1077
const DeclInfo * getDeclInfo() const LLVM_READONLY
Definition: Comment.h:1109
child_iterator child_begin() const
Definition: Comment.h:564
child_iterator child_end() const
Definition: Comment.h:568
unsigned getParamIndex() const LLVM_READONLY
Definition: Comment.h:768
static const char * getDirectionAsString(PassDirection D)
Definition: Comment.cpp:187
StringRef getParamName(const FullComment *FC) const
Definition: Comment.cpp:364
bool isParamIndexValid() const LLVM_READONLY
Definition: Comment.h:755
bool isVarArgParam() const LLVM_READONLY
Definition: Comment.h:759
bool isPositionValid() const LLVM_READONLY
Definition: Comment.h:825
StringRef getParamName(const FullComment *FC) const
Definition: Comment.cpp:371
unsigned getIndex(unsigned Depth) const
Definition: Comment.h:834
static bool getFunctionTypeLoc(TypeLoc TL, FunctionTypeLoc &ResFTL)
Definition: Comment.cpp:153
static TypeLoc lookThroughTypedefOrTypeAliasLocs(TypeLoc &SrcTL)
Definition: Comment.cpp:125
LLVM_READONLY bool isWhitespace(unsigned char c)
Return true if this character is horizontal or vertical ASCII whitespace: ' ', '\t',...
Definition: CharInfo.h:93
unsigned TemplateKind
Is CommentDecl a template declaration.
Definition: Comment.h:1045
unsigned IsClassMethod
Is CommentDecl a static member function of C++ class or class method of ObjC class.
Definition: Comment.h:1058
@ FunctionKind
Something that we consider a "function":
Definition: Comment.h:1005
@ EnumKind
An enumeration or scoped enumeration.
Definition: Comment.h:1027
@ OtherKind
Everything else not explicitly mentioned below.
Definition: Comment.h:995
@ NamespaceKind
A C++ namespace.
Definition: Comment.h:1020
@ VariableKind
Something that we consider a "variable":
Definition: Comment.h:1017
@ ClassKind
Something that we consider a "class":
Definition: Comment.h:1011
@ TypedefKind
A C++ typedef-name (a 'typedef' decl specifier or alias-declaration), see TypedefNameDecl.
Definition: Comment.h:1024
unsigned Kind
Simplified kind of CommentDecl, see DeclKind enum.
Definition: Comment.h:1042
unsigned IsObjCMethod
Is CommentDecl an ObjCMethodDecl.
Definition: Comment.h:1048
const TemplateParameterList * TemplateParameters
Template parameters that can be referenced by \tparam if CommentDecl is a template (IsTemplateDecl or...
Definition: Comment.h:989
ArrayRef< const ParmVarDecl * > ParamVars
Parameters that can be referenced by \param if CommentDecl is something that we consider a "function"...
Definition: Comment.h:980
unsigned IsInstanceMethod
Is CommentDecl a non-static member function of C++ class or instance method of ObjC class.
Definition: Comment.h:1053
bool involvesFunctionType() const
Definition: Comment.h:1073
unsigned IsFilled
If false, only CommentDecl is valid.
Definition: Comment.h:1039
const Decl * CommentDecl
Declaration the comment is actually attached to (in the source).
Definition: Comment.h:966
unsigned IsVariadic
Is CommentDecl something we consider a "function" that's variadic.
Definition: Comment.h:1061
const Decl * CurrentDecl
CurrentDecl is the declaration with which the FullComment is associated.
Definition: Comment.h:976
QualType ReturnType
Function return type if CommentDecl is something that we consider a "function".
Definition: Comment.h:984