RawCommentList.cpp revision ad6fd9f93ce0d328397e8d57ef7117ced24fc8e2 
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
20using namespace clang;
21
22namespace {
23/// Get comment kind and bool describing if it is a trailing comment.
24std::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
62bool mergedCommentIsTrailingComment(StringRef Comment) {
63  return (Comment.size() > 3) && (Comment[3] == '<');
64}
65} // unnamed namespace
66
67RawComment::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
93unsigned 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
103unsigned 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
113StringRef 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
140const 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
165comments::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
187namespace {
188bool containsOnlyWhitespace(StringRef Str) {
189  return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos;
190}
191
192bool 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
211void 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