contrib/llvm/tools/clang/lib/AST/RawCommentList.cpp

   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
  20 using namespace clang;
  21
  22 namespace {
  23 /// Get comment kind and bool describing if it is a trailing 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
  60 bool mergedCommentIsTrailingComment(StringRef Comment) {
  61   return (Comment.size() > 3) && (Comment[3] == '<');
  62 }
  63 } // unnamed namespace
  64
  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
  90 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
 100 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
 110 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
 137 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
 161 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 {
 183 bool containsOnlyWhitespace(StringRef Str) {
 184   return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos;
 185 }
 186
 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
 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