1 //===--- Comment.cpp - Comment AST node implementation --------------------===//
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 #include "clang/AST/Comment.h"
11 #include "clang/AST/ASTContext.h"
12 #include "clang/AST/Decl.h"
13 #include "clang/AST/DeclObjC.h"
14 #include "clang/AST/DeclTemplate.h"
15 #include "clang/Basic/CharInfo.h"
16 #include "llvm/Support/ErrorHandling.h"
17 
18 namespace clang {
19 namespace comments {
20 
21 const char *Comment::getCommentKindName() const {
22   switch (getCommentKind()) {
23   case NoCommentKind: return "NoCommentKind";
24 #define ABSTRACT_COMMENT(COMMENT)
25 #define COMMENT(CLASS, PARENT) \
26   case CLASS##Kind: \
27     return #CLASS;
28 #include "clang/AST/CommentNodes.inc"
29 #undef COMMENT
30 #undef ABSTRACT_COMMENT
31   }
32   llvm_unreachable("Unknown comment kind!");
33 }
34 
35 namespace {
36 struct good {};
37 struct bad {};
38 
39 template <typename T>
40 good implements_child_begin_end(Comment::child_iterator (T::*)() const) {
41   return good();
42 }
43 
44 LLVM_ATTRIBUTE_UNUSED
45 static inline bad implements_child_begin_end(
46                       Comment::child_iterator (Comment::*)() const) {
47   return bad();
48 }
49 
50 #define ASSERT_IMPLEMENTS_child_begin(function) \
51   (void) good(implements_child_begin_end(function))
52 
53 LLVM_ATTRIBUTE_UNUSED
54 static inline void CheckCommentASTNodes() {
55 #define ABSTRACT_COMMENT(COMMENT)
56 #define COMMENT(CLASS, PARENT) \
57   ASSERT_IMPLEMENTS_child_begin(&CLASS::child_begin); \
58   ASSERT_IMPLEMENTS_child_begin(&CLASS::child_end);
59 #include "clang/AST/CommentNodes.inc"
60 #undef COMMENT
61 #undef ABSTRACT_COMMENT
62 }
63 
64 #undef ASSERT_IMPLEMENTS_child_begin
65 
66 } // end unnamed namespace
67 
68 Comment::child_iterator Comment::child_begin() const {
69   switch (getCommentKind()) {
70   case NoCommentKind: llvm_unreachable("comment without a kind");
71 #define ABSTRACT_COMMENT(COMMENT)
72 #define COMMENT(CLASS, PARENT) \
73   case CLASS##Kind: \
74     return static_cast<const CLASS *>(this)->child_begin();
75 #include "clang/AST/CommentNodes.inc"
76 #undef COMMENT
77 #undef ABSTRACT_COMMENT
78   }
79   llvm_unreachable("Unknown comment kind!");
80 }
81 
82 Comment::child_iterator Comment::child_end() const {
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_end();
89 #include "clang/AST/CommentNodes.inc"
90 #undef COMMENT
91 #undef ABSTRACT_COMMENT
92   }
93   llvm_unreachable("Unknown comment kind!");
94 }
95 
96 bool TextComment::isWhitespaceNoCache() const {
97   for (StringRef::const_iterator I = Text.begin(), E = Text.end();
98        I != E; ++I) {
99     if (!clang::isWhitespace(*I))
100       return false;
101   }
102   return true;
103 }
104 
105 bool ParagraphComment::isWhitespaceNoCache() const {
106   for (child_iterator I = child_begin(), E = child_end(); I != E; ++I) {
107     if (const TextComment *TC = dyn_cast<TextComment>(*I)) {
108       if (!TC->isWhitespace())
109         return false;
110     } else
111       return false;
112   }
113   return true;
114 }
115 
116 static TypeLoc lookThroughTypedefOrTypeAliasLocs(TypeLoc &SrcTL) {
117   TypeLoc TL = SrcTL.IgnoreParens();
118 
119   // Look through attribute types.
120   if (AttributedTypeLoc AttributeTL = TL.getAs<AttributedTypeLoc>())
121     return AttributeTL.getModifiedLoc();
122   // Look through qualified types.
123   if (QualifiedTypeLoc QualifiedTL = TL.getAs<QualifiedTypeLoc>())
124     return QualifiedTL.getUnqualifiedLoc();
125   // Look through pointer types.
126   if (PointerTypeLoc PointerTL = TL.getAs<PointerTypeLoc>())
127     return PointerTL.getPointeeLoc().getUnqualifiedLoc();
128   // Look through reference types.
129   if (ReferenceTypeLoc ReferenceTL = TL.getAs<ReferenceTypeLoc>())
130     return ReferenceTL.getPointeeLoc().getUnqualifiedLoc();
131   // Look through adjusted types.
132   if (AdjustedTypeLoc ATL = TL.getAs<AdjustedTypeLoc>())
133     return ATL.getOriginalLoc();
134   if (BlockPointerTypeLoc BlockPointerTL = TL.getAs<BlockPointerTypeLoc>())
135     return BlockPointerTL.getPointeeLoc().getUnqualifiedLoc();
136   if (MemberPointerTypeLoc MemberPointerTL = TL.getAs<MemberPointerTypeLoc>())
137     return MemberPointerTL.getPointeeLoc().getUnqualifiedLoc();
138   if (ElaboratedTypeLoc ETL = TL.getAs<ElaboratedTypeLoc>())
139     return ETL.getNamedTypeLoc();
140 
141   return TL;
142 }
143 
144 static bool getFunctionTypeLoc(TypeLoc TL, FunctionTypeLoc &ResFTL) {
145   TypeLoc PrevTL;
146   while (PrevTL != TL) {
147     PrevTL = TL;
148     TL = lookThroughTypedefOrTypeAliasLocs(TL);
149   }
150 
151   if (FunctionTypeLoc FTL = TL.getAs<FunctionTypeLoc>()) {
152     ResFTL = FTL;
153     return true;
154   }
155 
156   if (TemplateSpecializationTypeLoc STL =
157           TL.getAs<TemplateSpecializationTypeLoc>()) {
158     // If we have a typedef to a template specialization with exactly one
159     // template argument of a function type, this looks like std::function,
160     // boost::function, or other function wrapper.  Treat these typedefs as
161     // functions.
162     if (STL.getNumArgs() != 1)
163       return false;
164     TemplateArgumentLoc MaybeFunction = STL.getArgLoc(0);
165     if (MaybeFunction.getArgument().getKind() != TemplateArgument::Type)
166       return false;
167     TypeSourceInfo *MaybeFunctionTSI = MaybeFunction.getTypeSourceInfo();
168     TypeLoc TL = MaybeFunctionTSI->getTypeLoc().getUnqualifiedLoc();
169     if (FunctionTypeLoc FTL = TL.getAs<FunctionTypeLoc>()) {
170       ResFTL = FTL;
171       return true;
172     }
173   }
174 
175   return false;
176 }
177 
178 const char *ParamCommandComment::getDirectionAsString(PassDirection D) {
179   switch (D) {
180   case ParamCommandComment::In:
181     return "[in]";
182   case ParamCommandComment::Out:
183     return "[out]";
184   case ParamCommandComment::InOut:
185     return "[in,out]";
186   }
187   llvm_unreachable("unknown PassDirection");
188 }
189 
190 void DeclInfo::fill() {
191   assert(!IsFilled);
192 
193   // Set defaults.
194   Kind = OtherKind;
195   TemplateKind = NotTemplate;
196   IsObjCMethod = false;
197   IsInstanceMethod = false;
198   IsClassMethod = false;
199   ParamVars = None;
200   TemplateParameters = nullptr;
201 
202   if (!CommentDecl) {
203     // If there is no declaration, the defaults is our only guess.
204     IsFilled = true;
205     return;
206   }
207   CurrentDecl = CommentDecl;
208 
209   Decl::Kind K = CommentDecl->getKind();
210   switch (K) {
211   default:
212     // Defaults are should be good for declarations we don't handle explicitly.
213     break;
214   case Decl::Function:
215   case Decl::CXXMethod:
216   case Decl::CXXConstructor:
217   case Decl::CXXDestructor:
218   case Decl::CXXConversion: {
219     const FunctionDecl *FD = cast<FunctionDecl>(CommentDecl);
220     Kind = FunctionKind;
221     ParamVars = FD->parameters();
222     ReturnType = FD->getReturnType();
223     unsigned NumLists = FD->getNumTemplateParameterLists();
224     if (NumLists != 0) {
225       TemplateKind = TemplateSpecialization;
226       TemplateParameters =
227           FD->getTemplateParameterList(NumLists - 1);
228     }
229 
230     if (K == Decl::CXXMethod || K == Decl::CXXConstructor ||
231         K == Decl::CXXDestructor || K == Decl::CXXConversion) {
232       const CXXMethodDecl *MD = cast<CXXMethodDecl>(CommentDecl);
233       IsInstanceMethod = MD->isInstance();
234       IsClassMethod = !IsInstanceMethod;
235     }
236     break;
237   }
238   case Decl::ObjCMethod: {
239     const ObjCMethodDecl *MD = cast<ObjCMethodDecl>(CommentDecl);
240     Kind = FunctionKind;
241     ParamVars = MD->parameters();
242     ReturnType = MD->getReturnType();
243     IsObjCMethod = true;
244     IsInstanceMethod = MD->isInstanceMethod();
245     IsClassMethod = !IsInstanceMethod;
246     break;
247   }
248   case Decl::FunctionTemplate: {
249     const FunctionTemplateDecl *FTD = cast<FunctionTemplateDecl>(CommentDecl);
250     Kind = FunctionKind;
251     TemplateKind = Template;
252     const FunctionDecl *FD = FTD->getTemplatedDecl();
253     ParamVars = FD->parameters();
254     ReturnType = FD->getReturnType();
255     TemplateParameters = FTD->getTemplateParameters();
256     break;
257   }
258   case Decl::ClassTemplate: {
259     const ClassTemplateDecl *CTD = cast<ClassTemplateDecl>(CommentDecl);
260     Kind = ClassKind;
261     TemplateKind = Template;
262     TemplateParameters = CTD->getTemplateParameters();
263     break;
264   }
265   case Decl::ClassTemplatePartialSpecialization: {
266     const ClassTemplatePartialSpecializationDecl *CTPSD =
267         cast<ClassTemplatePartialSpecializationDecl>(CommentDecl);
268     Kind = ClassKind;
269     TemplateKind = TemplatePartialSpecialization;
270     TemplateParameters = CTPSD->getTemplateParameters();
271     break;
272   }
273   case Decl::ClassTemplateSpecialization:
274     Kind = ClassKind;
275     TemplateKind = TemplateSpecialization;
276     break;
277   case Decl::Record:
278   case Decl::CXXRecord:
279     Kind = ClassKind;
280     break;
281   case Decl::Var:
282   case Decl::Field:
283   case Decl::EnumConstant:
284   case Decl::ObjCIvar:
285   case Decl::ObjCAtDefsField:
286   case Decl::ObjCProperty: {
287     const TypeSourceInfo *TSI;
288     if (const auto *VD = dyn_cast<DeclaratorDecl>(CommentDecl))
289       TSI = VD->getTypeSourceInfo();
290     else if (const auto *PD = dyn_cast<ObjCPropertyDecl>(CommentDecl))
291       TSI = PD->getTypeSourceInfo();
292     else
293       TSI = nullptr;
294     if (TSI) {
295       TypeLoc TL = TSI->getTypeLoc().getUnqualifiedLoc();
296       FunctionTypeLoc FTL;
297       if (getFunctionTypeLoc(TL, FTL)) {
298         ParamVars = FTL.getParams();
299         ReturnType = FTL.getReturnLoc().getType();
300       }
301     }
302     Kind = VariableKind;
303     break;
304   }
305   case Decl::Namespace:
306     Kind = NamespaceKind;
307     break;
308   case Decl::TypeAlias:
309   case Decl::Typedef: {
310     Kind = TypedefKind;
311     // If this is a typedef / using to something we consider a function, extract
312     // arguments and return type.
313     const TypeSourceInfo *TSI =
314         K == Decl::Typedef
315             ? cast<TypedefDecl>(CommentDecl)->getTypeSourceInfo()
316             : cast<TypeAliasDecl>(CommentDecl)->getTypeSourceInfo();
317     if (!TSI)
318       break;
319     TypeLoc TL = TSI->getTypeLoc().getUnqualifiedLoc();
320     FunctionTypeLoc FTL;
321     if (getFunctionTypeLoc(TL, FTL)) {
322       Kind = FunctionKind;
323       ParamVars = FTL.getParams();
324       ReturnType = FTL.getReturnLoc().getType();
325     }
326     break;
327   }
328   case Decl::TypeAliasTemplate: {
329     const TypeAliasTemplateDecl *TAT = cast<TypeAliasTemplateDecl>(CommentDecl);
330     Kind = TypedefKind;
331     TemplateKind = Template;
332     TemplateParameters = TAT->getTemplateParameters();
333     TypeAliasDecl *TAD = TAT->getTemplatedDecl();
334     if (!TAD)
335       break;
336 
337     const TypeSourceInfo *TSI = TAD->getTypeSourceInfo();
338     if (!TSI)
339       break;
340     TypeLoc TL = TSI->getTypeLoc().getUnqualifiedLoc();
341     FunctionTypeLoc FTL;
342     if (getFunctionTypeLoc(TL, FTL)) {
343       Kind = FunctionKind;
344       ParamVars = FTL.getParams();
345       ReturnType = FTL.getReturnLoc().getType();
346     }
347     break;
348   }
349   case Decl::Enum:
350     Kind = EnumKind;
351     break;
352   }
353 
354   IsFilled = true;
355 }
356 
357 StringRef ParamCommandComment::getParamName(const FullComment *FC) const {
358   assert(isParamIndexValid());
359   if (isVarArgParam())
360     return "...";
361   return FC->getDeclInfo()->ParamVars[getParamIndex()]->getName();
362 }
363 
364 StringRef TParamCommandComment::getParamName(const FullComment *FC) const {
365   assert(isPositionValid());
366   const TemplateParameterList *TPL = FC->getDeclInfo()->TemplateParameters;
367   for (unsigned i = 0, e = getDepth(); i != e; ++i) {
368     if (i == e-1)
369       return TPL->getParam(getIndex(i))->getName();
370     const NamedDecl *Param = TPL->getParam(getIndex(i));
371     if (const TemplateTemplateParmDecl *TTP =
372           dyn_cast<TemplateTemplateParmDecl>(Param))
373       TPL = TTP->getTemplateParameters();
374   }
375   return "";
376 }
377 
378 } // end namespace comments
379 } // end namespace clang
380 
381