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