1 //===--- RawCommentList.h - Classes for processing raw comments -*- C++ -*-===// 2 // 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 6 // 7 //===----------------------------------------------------------------------===// 8 9 #ifndef LLVM_CLANG_AST_RAWCOMMENTLIST_H 10 #define LLVM_CLANG_AST_RAWCOMMENTLIST_H 11 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" 17 #include <map> 18 19 namespace clang { 20 21 class ASTContext; 22 class ASTReader; 23 class Decl; 24 class Preprocessor; 25 26 namespace comments { 27 class FullComment; 28 } // end namespace comments 29 30 class RawComment { 31 public: 32 enum CommentKind { 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 41 }; 42 43 RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { } 44 45 RawComment(const SourceManager &SourceMgr, SourceRange SR, 46 const CommentOptions &CommentOpts, bool Merged); 47 48 CommentKind getKind() const LLVM_READONLY { 49 return (CommentKind) Kind; 50 } 51 52 bool isInvalid() const LLVM_READONLY { 53 return Kind == RCK_Invalid; 54 } 55 56 bool isMerged() const LLVM_READONLY { 57 return Kind == RCK_Merged; 58 } 59 60 /// Is this comment attached to any declaration? 61 bool isAttached() const LLVM_READONLY { 62 return IsAttached; 63 } 64 65 void setAttached() { 66 IsAttached = true; 67 } 68 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; 76 } 77 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; 83 } 84 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)); 88 } 89 90 /// Returns true if this comment any kind of a documentation comment. 91 bool isDocumentation() const LLVM_READONLY { 92 return !isInvalid() && !isOrdinary(); 93 } 94 95 /// Returns raw comment text with comment markers. 96 StringRef getRawText(const SourceManager &SourceMgr) const { 97 if (RawTextValid) 98 return RawText; 99 100 RawText = getRawTextSlow(SourceMgr); 101 RawTextValid = true; 102 return RawText; 103 } 104 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(); } 108 109 const char *getBriefText(const ASTContext &Context) const { 110 if (BriefTextValid) 111 return BriefText; 112 113 return extractBriefText(Context); 114 } 115 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. */ 121 /// into 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. */ 129 /// and 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; 139 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; 143 144 private: 145 SourceRange Range; 146 147 mutable StringRef RawText; 148 mutable const char *BriefText; 149 150 mutable bool RawTextValid : 1; ///< True if RawText is valid 151 mutable bool BriefTextValid : 1; ///< True if BriefText is valid 152 153 unsigned Kind : 3; 154 155 /// True if comment is attached to a declaration in ASTContext. 156 bool IsAttached : 1; 157 158 bool IsTrailingComment : 1; 159 bool IsAlmostTrailingComment : 1; 160 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) 167 { } 168 169 StringRef getRawTextSlow(const SourceManager &SourceMgr) const; 170 171 const char *extractBriefText(const ASTContext &Context) const; 172 173 friend class ASTReader; 174 }; 175 176 /// Compare comments' source locations. 177 template<> 178 class BeforeThanCompare<RawComment> { 179 const SourceManager &SM; 180 181 public: 182 explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { } 183 184 bool operator()(const RawComment &LHS, const RawComment &RHS) { 185 return SM.isBeforeInTranslationUnit(LHS.getBeginLoc(), RHS.getBeginLoc()); 186 } 187 188 bool operator()(const RawComment *LHS, const RawComment *RHS) { 189 return operator()(*LHS, *RHS); 190 } 191 }; 192 193 /// This class represents all comments included in the translation unit, 194 /// sorted in order of appearance in the translation unit. 195 class RawCommentList { 196 public: 197 RawCommentList(SourceManager &SourceMgr) : SourceMgr(SourceMgr) {} 198 199 void addComment(const RawComment &RC, const CommentOptions &CommentOpts, 200 llvm::BumpPtrAllocator &Allocator); 201 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; 205 206 bool empty() const; 207 208 unsigned getCommentBeginLine(RawComment *C, FileID File, 209 unsigned Offset) const; 210 unsigned getCommentEndOffset(RawComment *C) const; 211 212 private: 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; 218 219 friend class ASTReader; 220 friend class ASTWriter; 221 }; 222 223 } // end namespace clang 224 225 #endif 226