blob: 881a7d9c61bee88a631357f58067ac32c0bf0a81 [file] [log] [blame]
//===--- RawCommentList.cpp - Processing raw comments -----------*- C++ -*-===//
//
// The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
#include "clang/AST/RawCommentList.h"
#include "clang/AST/ASTContext.h"
#include "clang/AST/Comment.h"
#include "clang/AST/CommentBriefParser.h"
#include "clang/AST/CommentCommandTraits.h"
#include "clang/AST/CommentLexer.h"
#include "clang/AST/CommentParser.h"
#include "clang/AST/CommentSema.h"
#include "clang/Basic/CharInfo.h"
#include "llvm/ADT/STLExtras.h"
using namespace clang;
namespace {
/// Get comment kind and bool describing if it is a trailing comment.
std::pair<RawComment::CommentKind, bool> getCommentKind(StringRef Comment,
bool ParseAllComments) {
const size_t MinCommentLength = ParseAllComments ? 2 : 3;
if ((Comment.size() < MinCommentLength) || Comment[0] != '/')
return std::make_pair(RawComment::RCK_Invalid, false);
RawComment::CommentKind K;
if (Comment[1] == '/') {
if (Comment.size() < 3)
return std::make_pair(RawComment::RCK_OrdinaryBCPL, false);
if (Comment[2] == '/')
K = RawComment::RCK_BCPLSlash;
else if (Comment[2] == '!')
K = RawComment::RCK_BCPLExcl;
else
return std::make_pair(RawComment::RCK_OrdinaryBCPL, false);
} else {
assert(Comment.size() >= 4);
// Comment lexer does not understand escapes in comment markers, so pretend
// that this is not a comment.
if (Comment[1] != '*' ||
Comment[Comment.size() - 2] != '*' ||
Comment[Comment.size() - 1] != '/')
return std::make_pair(RawComment::RCK_Invalid, false);
if (Comment[2] == '*')
K = RawComment::RCK_JavaDoc;
else if (Comment[2] == '!')
K = RawComment::RCK_Qt;
else
return std::make_pair(RawComment::RCK_OrdinaryC, false);
}
const bool TrailingComment = (Comment.size() > 3) && (Comment[3] == '<');
return std::make_pair(K, TrailingComment);
}
bool mergedCommentIsTrailingComment(StringRef Comment) {
return (Comment.size() > 3) && (Comment[3] == '<');
}
/// Returns true if R1 and R2 both have valid locations that start on the same
/// column.
bool commentsStartOnSameColumn(const SourceManager &SM, const RawComment &R1,
const RawComment &R2) {
SourceLocation L1 = R1.getLocStart();
SourceLocation L2 = R2.getLocStart();
bool Invalid = false;
unsigned C1 = SM.getPresumedColumnNumber(L1, &Invalid);
if (!Invalid) {
unsigned C2 = SM.getPresumedColumnNumber(L2, &Invalid);
return !Invalid && (C1 == C2);
}
return false;
}
} // unnamed namespace
/// \brief Determines whether there is only whitespace in `Buffer` between `P`
/// and the previous line.
/// \param Buffer The buffer to search in.
/// \param P The offset from the beginning of `Buffer` to start from.
/// \return true if all of the characters in `Buffer` ranging from the closest
/// line-ending character before `P` (or the beginning of `Buffer`) to `P - 1`
/// are whitespace.
static bool onlyWhitespaceOnLineBefore(const char *Buffer, unsigned P) {
// Search backwards until we see linefeed or carriage return.
for (unsigned I = P; I != 0; --I) {
char C = Buffer[I - 1];
if (isVerticalWhitespace(C))
return true;
if (!isHorizontalWhitespace(C))
return false;
}
// We hit the beginning of the buffer.
return true;
}
/// Returns whether `K` is an ordinary comment kind.
static bool isOrdinaryKind(RawComment::CommentKind K) {
return (K == RawComment::RCK_OrdinaryBCPL) ||
(K == RawComment::RCK_OrdinaryC);
}
RawComment::RawComment(const SourceManager &SourceMgr, SourceRange SR,
bool Merged, bool ParseAllComments) :
Range(SR), RawTextValid(false), BriefTextValid(false),
IsAttached(false), IsTrailingComment(false), IsAlmostTrailingComment(false),
ParseAllComments(ParseAllComments) {
// Extract raw comment text, if possible.
if (SR.getBegin() == SR.getEnd() || getRawText(SourceMgr).empty()) {
Kind = RCK_Invalid;
return;
}
// Guess comment kind.
std::pair<CommentKind, bool> K = getCommentKind(RawText, ParseAllComments);
// Guess whether an ordinary comment is trailing.
if (ParseAllComments && isOrdinaryKind(K.first)) {
FileID BeginFileID;
unsigned BeginOffset;
std::tie(BeginFileID, BeginOffset) =
SourceMgr.getDecomposedLoc(Range.getBegin());
if (BeginOffset != 0) {
bool Invalid = false;
const char *Buffer =
SourceMgr.getBufferData(BeginFileID, &Invalid).data();
IsTrailingComment |=
(!Invalid && !onlyWhitespaceOnLineBefore(Buffer, BeginOffset));
}
}
if (!Merged) {
Kind = K.first;
IsTrailingComment |= K.second;
IsAlmostTrailingComment = RawText.startswith("//<") ||
RawText.startswith("/*<");
} else {
Kind = RCK_Merged;
IsTrailingComment =
IsTrailingComment || mergedCommentIsTrailingComment(RawText);
}
}
StringRef RawComment::getRawTextSlow(const SourceManager &SourceMgr) const {
FileID BeginFileID;
FileID EndFileID;
unsigned BeginOffset;
unsigned EndOffset;
std::tie(BeginFileID, BeginOffset) =
SourceMgr.getDecomposedLoc(Range.getBegin());
std::tie(EndFileID, EndOffset) = SourceMgr.getDecomposedLoc(Range.getEnd());
const unsigned Length = EndOffset - BeginOffset;
if (Length < 2)
return StringRef();
// The comment can't begin in one file and end in another.
assert(BeginFileID == EndFileID);
bool Invalid = false;
const char *BufferStart = SourceMgr.getBufferData(BeginFileID,
&Invalid).data();
if (Invalid)
return StringRef();
return StringRef(BufferStart + BeginOffset, Length);
}
const char *RawComment::extractBriefText(const ASTContext &Context) const {
// Lazily initialize RawText using the accessor before using it.
(void)getRawText(Context.getSourceManager());
// Since we will be copying the resulting text, all allocations made during
// parsing are garbage after resulting string is formed. Thus we can use
// a separate allocator for all temporary stuff.
llvm::BumpPtrAllocator Allocator;
comments::Lexer L(Allocator, Context.getDiagnostics(),
Context.getCommentCommandTraits(),
Range.getBegin(),
RawText.begin(), RawText.end());
comments::BriefParser P(L, Context.getCommentCommandTraits());
const std::string Result = P.Parse();
const unsigned BriefTextLength = Result.size();
char *BriefTextPtr = new (Context) char[BriefTextLength + 1];
memcpy(BriefTextPtr, Result.c_str(), BriefTextLength + 1);
BriefText = BriefTextPtr;
BriefTextValid = true;
return BriefTextPtr;
}
comments::FullComment *RawComment::parse(const ASTContext &Context,
const Preprocessor *PP,
const Decl *D) const {
// Lazily initialize RawText using the accessor before using it.
(void)getRawText(Context.getSourceManager());
comments::Lexer L(Context.getAllocator(), Context.getDiagnostics(),
Context.getCommentCommandTraits(),
getSourceRange().getBegin(),
RawText.begin(), RawText.end());
comments::Sema S(Context.getAllocator(), Context.getSourceManager(),
Context.getDiagnostics(),
Context.getCommentCommandTraits(),
PP);
S.setDecl(D);
comments::Parser P(L, S, Context.getAllocator(), Context.getSourceManager(),
Context.getDiagnostics(),
Context.getCommentCommandTraits());
return P.parseFullComment();
}
static bool onlyWhitespaceBetween(SourceManager &SM,
SourceLocation Loc1, SourceLocation Loc2,
unsigned MaxNewlinesAllowed) {
std::pair<FileID, unsigned> Loc1Info = SM.getDecomposedLoc(Loc1);
std::pair<FileID, unsigned> Loc2Info = SM.getDecomposedLoc(Loc2);
// Question does not make sense if locations are in different files.
if (Loc1Info.first != Loc2Info.first)
return false;
bool Invalid = false;
const char *Buffer = SM.getBufferData(Loc1Info.first, &Invalid).data();
if (Invalid)
return false;
unsigned NumNewlines = 0;
assert(Loc1Info.second <= Loc2Info.second && "Loc1 after Loc2!");
// Look for non-whitespace characters and remember any newlines seen.
for (unsigned I = Loc1Info.second; I != Loc2Info.second; ++I) {
switch (Buffer[I]) {
default:
return false;
case ' ':
case '\t':
case '\f':
case '\v':
break;
case '\r':
case '\n':
++NumNewlines;
// Check if we have found more than the maximum allowed number of
// newlines.
if (NumNewlines > MaxNewlinesAllowed)
return false;
// Collapse \r\n and \n\r into a single newline.
if (I + 1 != Loc2Info.second &&
(Buffer[I + 1] == '\n' || Buffer[I + 1] == '\r') &&
Buffer[I] != Buffer[I + 1])
++I;
break;
}
}
return true;
}
void RawCommentList::addComment(const RawComment &RC,
llvm::BumpPtrAllocator &Allocator) {
if (RC.isInvalid())
return;
// Check if the comments are not in source order.
while (!Comments.empty() &&
!SourceMgr.isBeforeInTranslationUnit(Comments.back()->getLocStart(),
RC.getLocStart())) {
// If they are, just pop a few last comments that don't fit.
// This happens if an \#include directive contains comments.
Comments.pop_back();
}
// Ordinary comments are not interesting for us.
if (RC.isOrdinary())
return;
// If this is the first Doxygen comment, save it (because there isn't
// anything to merge it with).
if (Comments.empty()) {
Comments.push_back(new (Allocator) RawComment(RC));
return;
}
const RawComment &C1 = *Comments.back();
const RawComment &C2 = RC;
// Merge comments only if there is only whitespace between them.
// Can't merge trailing and non-trailing comments unless the second is
// non-trailing ordinary in the same column, as in the case:
// int x; // documents x
// // more text
// versus:
// int x; // documents x
// int y; // documents y
// or:
// int x; // documents x
// // documents y
// int y;
// Merge comments if they are on same or consecutive lines.
if ((C1.isTrailingComment() == C2.isTrailingComment() ||
(C1.isTrailingComment() && !C2.isTrailingComment() &&
isOrdinaryKind(C2.getKind()) &&
commentsStartOnSameColumn(SourceMgr, C1, C2))) &&
onlyWhitespaceBetween(SourceMgr, C1.getLocEnd(), C2.getLocStart(),
/*MaxNewlinesAllowed=*/1)) {
SourceRange MergedRange(C1.getLocStart(), C2.getLocEnd());
*Comments.back() = RawComment(SourceMgr, MergedRange, true,
RC.isParseAllComments());
} else {
Comments.push_back(new (Allocator) RawComment(RC));
}
}
void RawCommentList::addDeserializedComments(ArrayRef<RawComment *> DeserializedComments) {
std::vector<RawComment *> MergedComments;
MergedComments.reserve(Comments.size() + DeserializedComments.size());
std::merge(Comments.begin(), Comments.end(),
DeserializedComments.begin(), DeserializedComments.end(),
std::back_inserter(MergedComments),
BeforeThanCompare<RawComment>(SourceMgr));
std::swap(Comments, MergedComments);
}