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/CommentLexer.h" 14 #include "clang/AST/CommentBriefParser.h" 15 #include "clang/AST/CommentSema.h" 16 #include "clang/AST/CommentParser.h" 17 #include "clang/AST/CommentCommandTraits.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 Decl *D) const { 163 // Make sure that RawText is valid. 164 getRawText(Context.getSourceManager()); 165 166 comments::Lexer L(Context.getAllocator(), Context.getCommentCommandTraits(), 167 getSourceRange().getBegin(), 168 RawText.begin(), RawText.end()); 169 comments::Sema S(Context.getAllocator(), Context.getSourceManager(), 170 Context.getDiagnostics(), 171 Context.getCommentCommandTraits()); 172 S.setDecl(D); 173 comments::Parser P(L, S, Context.getAllocator(), Context.getSourceManager(), 174 Context.getDiagnostics(), 175 Context.getCommentCommandTraits()); 176 177 return P.parseFullComment(); 178 } 179 180 namespace { 181 bool containsOnlyWhitespace(StringRef Str) { 182 return Str.find_first_not_of(" \t\f\v\r\n") == StringRef::npos; 183 } 184 185 bool onlyWhitespaceBetween(SourceManager &SM, 186 SourceLocation Loc1, SourceLocation Loc2) { 187 std::pair<FileID, unsigned> Loc1Info = SM.getDecomposedLoc(Loc1); 188 std::pair<FileID, unsigned> Loc2Info = SM.getDecomposedLoc(Loc2); 189 190 // Question does not make sense if locations are in different files. 191 if (Loc1Info.first != Loc2Info.first) 192 return false; 193 194 bool Invalid = false; 195 const char *Buffer = SM.getBufferData(Loc1Info.first, &Invalid).data(); 196 if (Invalid) 197 return false; 198 199 StringRef Text(Buffer + Loc1Info.second, Loc2Info.second - Loc1Info.second); 200 return containsOnlyWhitespace(Text); 201 } 202 } // unnamed namespace 203 204 void RawCommentList::addComment(const RawComment &RC, 205 llvm::BumpPtrAllocator &Allocator) { 206 if (RC.isInvalid()) 207 return; 208 209 // Check if the comments are not in source order. 210 while (!Comments.empty() && 211 !SourceMgr.isBeforeInTranslationUnit( 212 Comments.back()->getSourceRange().getBegin(), 213 RC.getSourceRange().getBegin())) { 214 // If they are, just pop a few last comments that don't fit. 215 // This happens if an \#include directive contains comments. 216 Comments.pop_back(); 217 } 218 219 if (OnlyWhitespaceSeen) { 220 if (!onlyWhitespaceBetween(SourceMgr, 221 PrevCommentEndLoc, 222 RC.getSourceRange().getBegin())) 223 OnlyWhitespaceSeen = false; 224 } 225 226 PrevCommentEndLoc = RC.getSourceRange().getEnd(); 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 OnlyWhitespaceSeen = true; 237 return; 238 } 239 240 const RawComment &C1 = *Comments.back(); 241 const RawComment &C2 = RC; 242 243 // Merge comments only if there is only whitespace between them. 244 // Can't merge trailing and non-trailing comments. 245 // Merge comments if they are on same or consecutive lines. 246 bool Merged = false; 247 if (OnlyWhitespaceSeen && 248 (C1.isTrailingComment() == C2.isTrailingComment())) { 249 unsigned C1EndLine = C1.getEndLine(SourceMgr); 250 unsigned C2BeginLine = C2.getBeginLine(SourceMgr); 251 if (C1EndLine + 1 == C2BeginLine || C1EndLine == C2BeginLine) { 252 SourceRange MergedRange(C1.getSourceRange().getBegin(), 253 C2.getSourceRange().getEnd()); 254 *Comments.back() = RawComment(SourceMgr, MergedRange, true); 255 Merged = true; 256 } 257 } 258 if (!Merged) 259 Comments.push_back(new (Allocator) RawComment(RC)); 260 261 OnlyWhitespaceSeen = true; 262 } 263 264