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