Home | History | Annotate | Download | only in AST 
      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   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 
    266