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