RawCommentList.cpp revision 245431 
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/CommentLexer.h"
14#include "clang/AST/CommentBriefParser.h"
15#include "clang/AST/CommentSema.h"
16#include "clang/AST/CommentParser.h"
17#include "clang/AST/CommentCommandTraits.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  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
60bool mergedCommentIsTrailingComment(StringRef Comment) {
61  return (Comment.size() > 3) && (Comment[3] == '<');
62}
63} // unnamed namespace
64
65RawComment::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
90unsigned 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
100unsigned 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
110StringRef 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
137const 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
161comments::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
182namespace {
183bool containsOnlyWhitespace(StringRef Str) {
184  return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos;
185}
186
187bool 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
206void 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