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