1 //===--- RawCommentList.h - Classes for processing raw comments -*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 #ifndef LLVM_CLANG_AST_RAWCOMMENTLIST_H
10 #define LLVM_CLANG_AST_RAWCOMMENTLIST_H
12 #include "clang/Basic/CommentOptions.h"
13 #include "clang/Basic/SourceLocation.h"
14 #include "clang/Basic/SourceManager.h"
15 #include "llvm/ADT/ArrayRef.h"
16 #include "llvm/ADT/DenseMap.h"
28 } // end namespace comments
33 RCK_Invalid, ///< Invalid comment
34 RCK_OrdinaryBCPL, ///< Any normal BCPL comments
35 RCK_OrdinaryC, ///< Any normal C comment
36 RCK_BCPLSlash, ///< \code /// stuff \endcode
37 RCK_BCPLExcl, ///< \code //! stuff \endcode
38 RCK_JavaDoc, ///< \code /** stuff */ \endcode
39 RCK_Qt, ///< \code /*! stuff */ \endcode, also used by HeaderDoc
40 RCK_Merged ///< Two or more documentation comments merged together
43 RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
45 RawComment(const SourceManager &SourceMgr, SourceRange SR,
46 const CommentOptions &CommentOpts, bool Merged);
48 CommentKind getKind() const LLVM_READONLY {
49 return (CommentKind) Kind;
52 bool isInvalid() const LLVM_READONLY {
53 return Kind == RCK_Invalid;
56 bool isMerged() const LLVM_READONLY {
57 return Kind == RCK_Merged;
60 /// Is this comment attached to any declaration?
61 bool isAttached() const LLVM_READONLY {
69 /// Returns true if it is a comment that should be put after a member:
70 /// \code ///< stuff \endcode
71 /// \code //!< stuff \endcode
72 /// \code /**< stuff */ \endcode
73 /// \code /*!< stuff */ \endcode
74 bool isTrailingComment() const LLVM_READONLY {
75 return IsTrailingComment;
78 /// Returns true if it is a probable typo:
79 /// \code //< stuff \endcode
80 /// \code /*< stuff */ \endcode
81 bool isAlmostTrailingComment() const LLVM_READONLY {
82 return IsAlmostTrailingComment;
85 /// Returns true if this comment is not a documentation comment.
86 bool isOrdinary() const LLVM_READONLY {
87 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 raw comment text with comment markers.
96 StringRef getRawText(const SourceManager &SourceMgr) const {
100 RawText = getRawTextSlow(SourceMgr);
105 SourceRange getSourceRange() const LLVM_READONLY { return Range; }
106 SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }
107 SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }
109 const char *getBriefText(const ASTContext &Context) const {
113 return extractBriefText(Context);
116 /// Returns sanitized comment text, suitable for presentation in editor UIs.
117 /// E.g. will transform:
118 /// // This is a long multiline comment.
119 /// // Parts of it might be indented.
120 /// /* The comments styles might be mixed. */
122 /// "This is a long multiline comment.\n"
123 /// " Parts of it might be indented.\n"
124 /// "The comments styles might be mixed."
125 /// Also removes leading indentation and sanitizes some common cases:
126 /// /* This is a first line.
127 /// * This is a second line. It is indented.
128 /// * This is a third line. */
130 /// /* This is a first line.
131 /// This is a second line. It is indented.
132 /// This is a third line. */
133 /// will both turn into:
134 /// "This is a first line.\n"
135 /// " This is a second line. It is indented.\n"
136 /// "This is a third line."
137 std::string getFormattedText(const SourceManager &SourceMgr,
138 DiagnosticsEngine &Diags) const;
140 /// Parse the comment, assuming it is attached to decl \c D.
141 comments::FullComment *parse(const ASTContext &Context,
142 const Preprocessor *PP, const Decl *D) const;
147 mutable StringRef RawText;
148 mutable const char *BriefText;
150 mutable bool RawTextValid : 1; ///< True if RawText is valid
151 mutable bool BriefTextValid : 1; ///< True if BriefText is valid
155 /// True if comment is attached to a declaration in ASTContext.
158 bool IsTrailingComment : 1;
159 bool IsAlmostTrailingComment : 1;
161 /// Constructor for AST deserialization.
162 RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,
163 bool IsAlmostTrailingComment) :
164 Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),
165 IsAttached(false), IsTrailingComment(IsTrailingComment),
166 IsAlmostTrailingComment(IsAlmostTrailingComment)
169 StringRef getRawTextSlow(const SourceManager &SourceMgr) const;
171 const char *extractBriefText(const ASTContext &Context) const;
173 friend class ASTReader;
176 /// Compare comments' source locations.
178 class BeforeThanCompare<RawComment> {
179 const SourceManager &SM;
182 explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
184 bool operator()(const RawComment &LHS, const RawComment &RHS) {
185 return SM.isBeforeInTranslationUnit(LHS.getBeginLoc(), RHS.getBeginLoc());
188 bool operator()(const RawComment *LHS, const RawComment *RHS) {
189 return operator()(*LHS, *RHS);
193 /// This class represents all comments included in the translation unit,
194 /// sorted in order of appearance in the translation unit.
195 class RawCommentList {
197 RawCommentList(SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}
199 void addComment(const RawComment &RC, const CommentOptions &CommentOpts,
200 llvm::BumpPtrAllocator &Allocator);
202 /// \returns A mapping from an offset of the start of the comment to the
203 /// comment itself, or nullptr in case there are no comments in \p File.
204 const std::map<unsigned, RawComment *> *getCommentsInFile(FileID File) const;
208 unsigned getCommentBeginLine(RawComment *C, FileID File,
209 unsigned Offset) const;
210 unsigned getCommentEndOffset(RawComment *C) const;
213 SourceManager &SourceMgr;
214 // mapping: FileId -> comment begin offset -> comment
215 llvm::DenseMap<FileID, std::map<unsigned, RawComment *>> OrderedComments;
216 mutable llvm::DenseMap<RawComment *, unsigned> CommentBeginLine;
217 mutable llvm::DenseMap<RawComment *, unsigned> CommentEndOffset;
219 friend class ASTReader;
220 friend class ASTWriter;
223 } // end namespace clang