RawCommentList.cpp revision 263508
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 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 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 62bool mergedCommentIsTrailingComment(StringRef Comment) { 63 return (Comment.size() > 3) && (Comment[3] == '<'); 64} 65} // unnamed namespace 66 67RawComment::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 // Extract raw comment text, if possible. 73 if (SR.getBegin() == SR.getEnd() || getRawText(SourceMgr).empty()) { 74 Kind = RCK_Invalid; 75 return; 76 } 77 78 if (!Merged) { 79 // Guess comment kind. 80 std::pair<CommentKind, bool> K = getCommentKind(RawText, ParseAllComments); 81 Kind = K.first; 82 IsTrailingComment = K.second; 83 84 IsAlmostTrailingComment = RawText.startswith("//<") || 85 RawText.startswith("/*<"); 86 } else { 87 Kind = RCK_Merged; 88 IsTrailingComment = mergedCommentIsTrailingComment(RawText); 89 } 90} 91 92StringRef RawComment::getRawTextSlow(const SourceManager &SourceMgr) const { 93 FileID BeginFileID; 94 FileID EndFileID; 95 unsigned BeginOffset; 96 unsigned EndOffset; 97 98 llvm::tie(BeginFileID, BeginOffset) = 99 SourceMgr.getDecomposedLoc(Range.getBegin()); 100 llvm::tie(EndFileID, EndOffset) = 101 SourceMgr.getDecomposedLoc(Range.getEnd()); 102 103 const unsigned Length = EndOffset - BeginOffset; 104 if (Length < 2) 105 return StringRef(); 106 107 // The comment can't begin in one file and end in another. 108 assert(BeginFileID == EndFileID); 109 110 bool Invalid = false; 111 const char *BufferStart = SourceMgr.getBufferData(BeginFileID, 112 &Invalid).data(); 113 if (Invalid) 114 return StringRef(); 115 116 return StringRef(BufferStart + BeginOffset, Length); 117} 118 119const char *RawComment::extractBriefText(const ASTContext &Context) const { 120 // Make sure that RawText is valid. 121 getRawText(Context.getSourceManager()); 122 123 // Since we will be copying the resulting text, all allocations made during 124 // parsing are garbage after resulting string is formed. Thus we can use 125 // a separate allocator for all temporary stuff. 126 llvm::BumpPtrAllocator Allocator; 127 128 comments::Lexer L(Allocator, Context.getDiagnostics(), 129 Context.getCommentCommandTraits(), 130 Range.getBegin(), 131 RawText.begin(), RawText.end()); 132 comments::BriefParser P(L, Context.getCommentCommandTraits()); 133 134 const std::string Result = P.Parse(); 135 const unsigned BriefTextLength = Result.size(); 136 char *BriefTextPtr = new (Context) char[BriefTextLength + 1]; 137 memcpy(BriefTextPtr, Result.c_str(), BriefTextLength + 1); 138 BriefText = BriefTextPtr; 139 BriefTextValid = true; 140 141 return BriefTextPtr; 142} 143 144comments::FullComment *RawComment::parse(const ASTContext &Context, 145 const Preprocessor *PP, 146 const Decl *D) const { 147 // Make sure that RawText is valid. 148 getRawText(Context.getSourceManager()); 149 150 comments::Lexer L(Context.getAllocator(), Context.getDiagnostics(), 151 Context.getCommentCommandTraits(), 152 getSourceRange().getBegin(), 153 RawText.begin(), RawText.end()); 154 comments::Sema S(Context.getAllocator(), Context.getSourceManager(), 155 Context.getDiagnostics(), 156 Context.getCommentCommandTraits(), 157 PP); 158 S.setDecl(D); 159 comments::Parser P(L, S, Context.getAllocator(), Context.getSourceManager(), 160 Context.getDiagnostics(), 161 Context.getCommentCommandTraits()); 162 163 return P.parseFullComment(); 164} 165 166static bool onlyWhitespaceBetween(SourceManager &SM, 167 SourceLocation Loc1, SourceLocation Loc2, 168 unsigned MaxNewlinesAllowed) { 169 std::pair<FileID, unsigned> Loc1Info = SM.getDecomposedLoc(Loc1); 170 std::pair<FileID, unsigned> Loc2Info = SM.getDecomposedLoc(Loc2); 171 172 // Question does not make sense if locations are in different files. 173 if (Loc1Info.first != Loc2Info.first) 174 return false; 175 176 bool Invalid = false; 177 const char *Buffer = SM.getBufferData(Loc1Info.first, &Invalid).data(); 178 if (Invalid) 179 return false; 180 181 unsigned NumNewlines = 0; 182 assert(Loc1Info.second <= Loc2Info.second && "Loc1 after Loc2!"); 183 // Look for non-whitespace characters and remember any newlines seen. 184 for (unsigned I = Loc1Info.second; I != Loc2Info.second; ++I) { 185 switch (Buffer[I]) { 186 default: 187 return false; 188 case ' ': 189 case '\t': 190 case '\f': 191 case '\v': 192 break; 193 case '\r': 194 case '\n': 195 ++NumNewlines; 196 197 // Check if we have found more than the maximum allowed number of 198 // newlines. 199 if (NumNewlines > MaxNewlinesAllowed) 200 return false; 201 202 // Collapse \r\n and \n\r into a single newline. 203 if (I + 1 != Loc2Info.second && 204 (Buffer[I + 1] == '\n' || Buffer[I + 1] == '\r') && 205 Buffer[I] != Buffer[I + 1]) 206 ++I; 207 break; 208 } 209 } 210 211 return true; 212} 213 214void RawCommentList::addComment(const RawComment &RC, 215 llvm::BumpPtrAllocator &Allocator) { 216 if (RC.isInvalid()) 217 return; 218 219 // Check if the comments are not in source order. 220 while (!Comments.empty() && 221 !SourceMgr.isBeforeInTranslationUnit(Comments.back()->getLocStart(), 222 RC.getLocStart())) { 223 // If they are, just pop a few last comments that don't fit. 224 // This happens if an \#include directive contains comments. 225 Comments.pop_back(); 226 } 227 228 // Ordinary comments are not interesting for us. 229 if (RC.isOrdinary()) 230 return; 231 232 // If this is the first Doxygen comment, save it (because there isn't 233 // anything to merge it with). 234 if (Comments.empty()) { 235 Comments.push_back(new (Allocator) RawComment(RC)); 236 return; 237 } 238 239 const RawComment &C1 = *Comments.back(); 240 const RawComment &C2 = RC; 241 242 // Merge comments only if there is only whitespace between them. 243 // Can't merge trailing and non-trailing comments. 244 // Merge comments if they are on same or consecutive lines. 245 if (C1.isTrailingComment() == C2.isTrailingComment() && 246 onlyWhitespaceBetween(SourceMgr, C1.getLocEnd(), C2.getLocStart(), 247 /*MaxNewlinesAllowed=*/1)) { 248 SourceRange MergedRange(C1.getLocStart(), C2.getLocEnd()); 249 *Comments.back() = RawComment(SourceMgr, MergedRange, true, 250 RC.isParseAllComments()); 251 } else { 252 Comments.push_back(new (Allocator) RawComment(RC)); 253 } 254} 255