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 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 93unsigned 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 103unsigned 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 113StringRef 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 140const 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 165comments::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 187namespace { 188bool containsOnlyWhitespace(StringRef Str) { 189 return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos; 190} 191 192bool 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 211void 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