1 //===--- RawCommentList.cpp - Processing raw comments -----------*- 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 #include "clang/AST/RawCommentList.h"
11 #include "clang/AST/ASTContext.h"
12 #include "clang/AST/Comment.h"
13 #include "clang/AST/CommentBriefParser.h"
14 #include "clang/AST/CommentCommandTraits.h"
15 #include "clang/AST/CommentLexer.h"
16 #include "clang/AST/CommentParser.h"
17 #include "clang/AST/CommentSema.h"
18 #include "llvm/ADT/STLExtras.h"
19 
20 using namespace clang;
21 
22 namespace {
23 /// Get comment kind and bool describing if it is a trailing comment.
24 std::pair<RawComment::CommentKind, bool> getCommentKind(StringRef Comment) {
25   if (Comment.size() < 3 || Comment[0] != '/')
26     return std::make_pair(RawComment::RCK_Invalid, false);
27 
28   RawComment::CommentKind K;
29   if (Comment[1] == '/') {
30     if (Comment.size() < 3)
31       return std::make_pair(RawComment::RCK_OrdinaryBCPL, false);
32 
33     if (Comment[2] == '/')
34       K = RawComment::RCK_BCPLSlash;
35     else if (Comment[2] == '!')
36       K = RawComment::RCK_BCPLExcl;
37     else
38       return std::make_pair(RawComment::RCK_OrdinaryBCPL, false);
39   } else {
40     assert(Comment.size() >= 4);
41 
42     // Comment lexer does not understand escapes in comment markers, so pretend
43     // that this is not a comment.
44     if (Comment[1] != '*' ||
45         Comment[Comment.size() - 2] != '*' ||
46         Comment[Comment.size() - 1] != '/')
47       return std::make_pair(RawComment::RCK_Invalid, false);
48 
49     if (Comment[2] == '*')
50       K = RawComment::RCK_JavaDoc;
51     else if (Comment[2] == '!')
52       K = RawComment::RCK_Qt;
53     else
54       return std::make_pair(RawComment::RCK_OrdinaryC, false);
55   }
56   const bool TrailingComment = (Comment.size() > 3) && (Comment[3] == '<');
57   return std::make_pair(K, TrailingComment);
58 }
59 
60 bool mergedCommentIsTrailingComment(StringRef Comment) {
61   return (Comment.size() > 3) && (Comment[3] == '<');
62 }
63 } // unnamed namespace
64 
65 RawComment::RawComment(const SourceManager &SourceMgr, SourceRange SR,
66                        bool Merged, bool ParseAllComments) :
67     Range(SR), RawTextValid(false), BriefTextValid(false),
68     IsAttached(false), IsAlmostTrailingComment(false),
69     ParseAllComments(ParseAllComments),
70     BeginLineValid(false), EndLineValid(false) {
71   // Extract raw comment text, if possible.
72   if (SR.getBegin() == SR.getEnd() || getRawText(SourceMgr).empty()) {
73     Kind = RCK_Invalid;
74     return;
75   }
76 
77   if (!Merged) {
78     // Guess comment kind.
79     std::pair<CommentKind, bool> K = getCommentKind(RawText);
80     Kind = K.first;
81     IsTrailingComment = K.second;
82 
83     IsAlmostTrailingComment = RawText.startswith("//<") ||
84                                  RawText.startswith("/*<");
85   } else {
86     Kind = RCK_Merged;
87     IsTrailingComment = mergedCommentIsTrailingComment(RawText);
88   }
89 }
90 
91 unsigned RawComment::getBeginLine(const SourceManager &SM) const {
92   if (BeginLineValid)
93     return BeginLine;
94 
95   std::pair<FileID, unsigned> LocInfo = SM.getDecomposedLoc(Range.getBegin());
96   BeginLine = SM.getLineNumber(LocInfo.first, LocInfo.second);
97   BeginLineValid = true;
98   return BeginLine;
99 }
100 
101 unsigned RawComment::getEndLine(const SourceManager &SM) const {
102   if (EndLineValid)
103     return EndLine;
104 
105   std::pair<FileID, unsigned> LocInfo = SM.getDecomposedLoc(Range.getEnd());
106   EndLine = SM.getLineNumber(LocInfo.first, LocInfo.second);
107   EndLineValid = true;
108   return EndLine;
109 }
110 
111 StringRef RawComment::getRawTextSlow(const SourceManager &SourceMgr) const {
112   FileID BeginFileID;
113   FileID EndFileID;
114   unsigned BeginOffset;
115   unsigned EndOffset;
116 
117   llvm::tie(BeginFileID, BeginOffset) =
118       SourceMgr.getDecomposedLoc(Range.getBegin());
119   llvm::tie(EndFileID, EndOffset) =
120       SourceMgr.getDecomposedLoc(Range.getEnd());
121 
122   const unsigned Length = EndOffset - BeginOffset;
123   if (Length < 2)
124     return StringRef();
125 
126   // The comment can't begin in one file and end in another.
127   assert(BeginFileID == EndFileID);
128 
129   bool Invalid = false;
130   const char *BufferStart = SourceMgr.getBufferData(BeginFileID,
131                                                     &Invalid).data();
132   if (Invalid)
133     return StringRef();
134 
135   return StringRef(BufferStart + BeginOffset, Length);
136 }
137 
138 const char *RawComment::extractBriefText(const ASTContext &Context) const {
139   // Make sure that RawText is valid.
140   getRawText(Context.getSourceManager());
141 
142   // Since we will be copying the resulting text, all allocations made during
143   // parsing are garbage after resulting string is formed.  Thus we can use
144   // a separate allocator for all temporary stuff.
145   llvm::BumpPtrAllocator Allocator;
146 
147   comments::Lexer L(Allocator, Context.getCommentCommandTraits(),
148                     Range.getBegin(),
149                     RawText.begin(), RawText.end());
150   comments::BriefParser P(L, Context.getCommentCommandTraits());
151 
152   const std::string Result = P.Parse();
153   const unsigned BriefTextLength = Result.size();
154   char *BriefTextPtr = new (Context) char[BriefTextLength + 1];
155   memcpy(BriefTextPtr, Result.c_str(), BriefTextLength + 1);
156   BriefText = BriefTextPtr;
157   BriefTextValid = true;
158 
159   return BriefTextPtr;
160 }
161 
162 comments::FullComment *RawComment::parse(const ASTContext &Context,
163                                          const Preprocessor *PP,
164                                          const Decl *D) const {
165   // Make sure that RawText is valid.
166   getRawText(Context.getSourceManager());
167 
168   comments::Lexer L(Context.getAllocator(), Context.getCommentCommandTraits(),
169                     getSourceRange().getBegin(),
170                     RawText.begin(), RawText.end());
171   comments::Sema S(Context.getAllocator(), Context.getSourceManager(),
172                    Context.getDiagnostics(),
173                    Context.getCommentCommandTraits(),
174                    PP);
175   S.setDecl(D);
176   comments::Parser P(L, S, Context.getAllocator(), Context.getSourceManager(),
177                      Context.getDiagnostics(),
178                      Context.getCommentCommandTraits());
179 
180   return P.parseFullComment();
181 }
182 
183 namespace {
184 bool containsOnlyWhitespace(StringRef Str) {
185   return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos;
186 }
187 
188 bool onlyWhitespaceBetween(SourceManager &SM,
189                            SourceLocation Loc1, SourceLocation Loc2) {
190   std::pair<FileID, unsigned> Loc1Info = SM.getDecomposedLoc(Loc1);
191   std::pair<FileID, unsigned> Loc2Info = SM.getDecomposedLoc(Loc2);
192 
193   // Question does not make sense if locations are in different files.
194   if (Loc1Info.first != Loc2Info.first)
195     return false;
196 
197   bool Invalid = false;
198   const char *Buffer = SM.getBufferData(Loc1Info.first, &Invalid).data();
199   if (Invalid)
200     return false;
201 
202   StringRef Text(Buffer + Loc1Info.second, Loc2Info.second - Loc1Info.second);
203   return containsOnlyWhitespace(Text);
204 }
205 } // unnamed namespace
206 
207 void RawCommentList::addComment(const RawComment &RC,
208                                 llvm::BumpPtrAllocator &Allocator) {
209   if (RC.isInvalid())
210     return;
211 
212   // Check if the comments are not in source order.
213   while (!Comments.empty() &&
214          !SourceMgr.isBeforeInTranslationUnit(
215               Comments.back()->getSourceRange().getBegin(),
216               RC.getSourceRange().getBegin())) {
217     // If they are, just pop a few last comments that don't fit.
218     // This happens if an \#include directive contains comments.
219     Comments.pop_back();
220   }
221 
222   if (OnlyWhitespaceSeen) {
223     if (!onlyWhitespaceBetween(SourceMgr,
224                                PrevCommentEndLoc,
225                                RC.getSourceRange().getBegin()))
226       OnlyWhitespaceSeen = false;
227   }
228 
229   PrevCommentEndLoc = RC.getSourceRange().getEnd();
230 
231   // Ordinary comments are not interesting for us.
232   if (RC.isOrdinary())
233     return;
234 
235   // If this is the first Doxygen comment, save it (because there isn't
236   // anything to merge it with).
237   if (Comments.empty()) {
238     Comments.push_back(new (Allocator) RawComment(RC));
239     OnlyWhitespaceSeen = true;
240     return;
241   }
242 
243   const RawComment &C1 = *Comments.back();
244   const RawComment &C2 = RC;
245 
246   // Merge comments only if there is only whitespace between them.
247   // Can't merge trailing and non-trailing comments.
248   // Merge comments if they are on same or consecutive lines.
249   bool Merged = false;
250   if (OnlyWhitespaceSeen &&
251       (C1.isTrailingComment() == C2.isTrailingComment())) {
252     unsigned C1EndLine = C1.getEndLine(SourceMgr);
253     unsigned C2BeginLine = C2.getBeginLine(SourceMgr);
254     if (C1EndLine + 1 == C2BeginLine || C1EndLine == C2BeginLine) {
255       SourceRange MergedRange(C1.getSourceRange().getBegin(),
256                               C2.getSourceRange().getEnd());
257       *Comments.back() = RawComment(SourceMgr, MergedRange, true,
258                                     RC.isParseAllComments());
259       Merged = true;
260     }
261   }
262   if (!Merged)
263     Comments.push_back(new (Allocator) RawComment(RC));
264 
265   OnlyWhitespaceSeen = true;
266 }
267