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/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.
  24 std::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
  62 bool mergedCommentIsTrailingComment(StringRef Comment) {
  63   return (Comment.size() > 3) && (Comment[3] == '<');
  64 }
  65 } // unnamed namespace
  66
  67 RawComment::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
  93 unsigned 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
 103 unsigned 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
 113 StringRef 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
 140 const 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
 165 comments::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
 187 namespace {
 188 bool containsOnlyWhitespace(StringRef Str) {
 189   return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos;
 190 }
 191
 192 bool 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
 211 void 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 }