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                                                         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 }
    271