1 //===--- RawCommentList.h - Classes for processing raw comments -*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef LLVM_CLANG_AST_RAW_COMMENT_LIST_H
11 #define LLVM_CLANG_AST_RAW_COMMENT_LIST_H
13 #include "clang/Basic/CommentOptions.h"
14 #include "clang/Basic/SourceManager.h"
15 #include "llvm/ADT/ArrayRef.h"
26 } // end namespace comments
31 RCK_Invalid, ///< Invalid comment
32 RCK_OrdinaryBCPL, ///< Any normal BCPL comments
33 RCK_OrdinaryC, ///< Any normal C comment
34 RCK_BCPLSlash, ///< \code /// stuff \endcode
35 RCK_BCPLExcl, ///< \code //! stuff \endcode
36 RCK_JavaDoc, ///< \code /** stuff */ \endcode
37 RCK_Qt, ///< \code /*! stuff */ \endcode, also used by HeaderDoc
38 RCK_Merged ///< Two or more documentation comments merged together
41 RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
43 RawComment(const SourceManager &SourceMgr, SourceRange SR,
44 bool Merged, bool ParseAllComments);
46 CommentKind getKind() const LLVM_READONLY {
47 return (CommentKind) Kind;
50 bool isInvalid() const LLVM_READONLY {
51 return Kind == RCK_Invalid;
54 bool isMerged() const LLVM_READONLY {
55 return Kind == RCK_Merged;
58 /// Is this comment attached to any declaration?
59 bool isAttached() const LLVM_READONLY {
67 /// Returns true if it is a comment that should be put after a member:
68 /// \code ///< stuff \endcode
69 /// \code //!< stuff \endcode
70 /// \code /**< stuff */ \endcode
71 /// \code /*!< stuff */ \endcode
72 bool isTrailingComment() const LLVM_READONLY {
73 assert(isDocumentation());
74 return IsTrailingComment;
77 /// Returns true if it is a probable typo:
78 /// \code //< stuff \endcode
79 /// \code /*< stuff */ \endcode
80 bool isAlmostTrailingComment() const LLVM_READONLY {
81 return IsAlmostTrailingComment;
84 /// Returns true if this comment is not a documentation comment.
85 bool isOrdinary() const LLVM_READONLY {
86 return ((Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC)) &&
90 /// Returns true if this comment any kind of a documentation comment.
91 bool isDocumentation() const LLVM_READONLY {
92 return !isInvalid() && !isOrdinary();
95 /// Returns whether we are parsing all comments.
96 bool isParseAllComments() const LLVM_READONLY {
97 return ParseAllComments;
100 /// Returns raw comment text with comment markers.
101 StringRef getRawText(const SourceManager &SourceMgr) const {
105 RawText = getRawTextSlow(SourceMgr);
110 SourceRange getSourceRange() const LLVM_READONLY {
114 unsigned getBeginLine(const SourceManager &SM) const;
115 unsigned getEndLine(const SourceManager &SM) const;
117 const char *getBriefText(const ASTContext &Context) const {
121 return extractBriefText(Context);
124 /// Parse the comment, assuming it is attached to decl \c D.
125 comments::FullComment *parse(const ASTContext &Context,
126 const Preprocessor *PP, const Decl *D) const;
131 mutable StringRef RawText;
132 mutable const char *BriefText;
134 mutable bool RawTextValid : 1; ///< True if RawText is valid
135 mutable bool BriefTextValid : 1; ///< True if BriefText is valid
139 /// True if comment is attached to a declaration in ASTContext.
142 bool IsTrailingComment : 1;
143 bool IsAlmostTrailingComment : 1;
145 /// When true, ordinary comments starting with "//" and "/*" will be
146 /// considered as documentation comments.
147 bool ParseAllComments : 1;
149 mutable bool BeginLineValid : 1; ///< True if BeginLine is valid
150 mutable bool EndLineValid : 1; ///< True if EndLine is valid
151 mutable unsigned BeginLine; ///< Cached line number
152 mutable unsigned EndLine; ///< Cached line number
154 /// \brief Constructor for AST deserialization.
155 RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,
156 bool IsAlmostTrailingComment,
157 bool ParseAllComments) :
158 Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),
159 IsAttached(false), IsTrailingComment(IsTrailingComment),
160 IsAlmostTrailingComment(IsAlmostTrailingComment),
161 ParseAllComments(ParseAllComments),
162 BeginLineValid(false), EndLineValid(false)
165 StringRef getRawTextSlow(const SourceManager &SourceMgr) const;
167 const char *extractBriefText(const ASTContext &Context) const;
169 friend class ASTReader;
172 /// \brief Compare comments' source locations.
174 class BeforeThanCompare<RawComment> {
175 const SourceManager &SM;
178 explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
180 bool operator()(const RawComment &LHS, const RawComment &RHS) {
181 return SM.isBeforeInTranslationUnit(LHS.getSourceRange().getBegin(),
182 RHS.getSourceRange().getBegin());
185 bool operator()(const RawComment *LHS, const RawComment *RHS) {
186 return operator()(*LHS, *RHS);
190 /// \brief This class represents all comments included in the translation unit,
191 /// sorted in order of appearance in the translation unit.
192 class RawCommentList {
194 RawCommentList(SourceManager &SourceMgr) :
195 SourceMgr(SourceMgr), OnlyWhitespaceSeen(true) { }
197 void addComment(const RawComment &RC, llvm::BumpPtrAllocator &Allocator);
199 ArrayRef<RawComment *> getComments() const {
204 SourceManager &SourceMgr;
205 std::vector<RawComment *> Comments;
206 SourceLocation PrevCommentEndLoc;
207 bool OnlyWhitespaceSeen;
209 void addCommentsToFront(const std::vector<RawComment *> &C) {
210 size_t OldSize = Comments.size();
211 Comments.resize(C.size() + OldSize);
212 std::copy_backward(Comments.begin(), Comments.begin() + OldSize,
214 std::copy(C.begin(), C.end(), Comments.begin());
217 friend class ASTReader;
220 } // end namespace clang