/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/AST/RawCommentList.h
Line | Count | Source (jump to first uncovered line) |
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 "llvm/ADT/ArrayRef.h" |
15 | | #include "llvm/ADT/DenseMap.h" |
16 | | #include "llvm/Support/Allocator.h" |
17 | | #include <map> |
18 | | |
19 | | namespace clang { |
20 | | |
21 | | class ASTContext; |
22 | | class ASTReader; |
23 | | class Decl; |
24 | | class DiagnosticsEngine; |
25 | | class Preprocessor; |
26 | | class SourceManager; |
27 | | |
28 | | namespace comments { |
29 | | class FullComment; |
30 | | } // end namespace comments |
31 | | |
32 | | class RawComment { |
33 | | public: |
34 | | enum CommentKind { |
35 | | RCK_Invalid, ///< Invalid comment |
36 | | RCK_OrdinaryBCPL, ///< Any normal BCPL comments |
37 | | RCK_OrdinaryC, ///< Any normal C comment |
38 | | RCK_BCPLSlash, ///< \code /// stuff \endcode |
39 | | RCK_BCPLExcl, ///< \code //! stuff \endcode |
40 | | RCK_JavaDoc, ///< \code /** stuff */ \endcode |
41 | | RCK_Qt, ///< \code /*! stuff */ \endcode, also used by HeaderDoc |
42 | | RCK_Merged ///< Two or more documentation comments merged together |
43 | | }; |
44 | | |
45 | 0 | RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { } |
46 | | |
47 | | RawComment(const SourceManager &SourceMgr, SourceRange SR, |
48 | | const CommentOptions &CommentOpts, bool Merged); |
49 | | |
50 | 7.14k | CommentKind getKind() const LLVM_READONLY { |
51 | 7.14k | return (CommentKind) Kind; |
52 | 7.14k | } |
53 | | |
54 | 38.4M | bool isInvalid() const LLVM_READONLY { |
55 | 38.4M | return Kind == RCK_Invalid; |
56 | 38.4M | } |
57 | | |
58 | 0 | bool isMerged() const LLVM_READONLY { |
59 | 0 | return Kind == RCK_Merged; |
60 | 0 | } |
61 | | |
62 | | /// Is this comment attached to any declaration? |
63 | 4.69k | bool isAttached() const LLVM_READONLY { |
64 | 4.69k | return IsAttached; |
65 | 4.69k | } |
66 | | |
67 | 0 | void setAttached() { |
68 | 0 | IsAttached = true; |
69 | 0 | } |
70 | | |
71 | | /// Returns true if it is a comment that should be put after a member: |
72 | | /// \code ///< stuff \endcode |
73 | | /// \code //!< stuff \endcode |
74 | | /// \code /**< stuff */ \endcode |
75 | | /// \code /*!< stuff */ \endcode |
76 | 308k | bool isTrailingComment() const LLVM_READONLY { |
77 | 308k | return IsTrailingComment; |
78 | 308k | } |
79 | | |
80 | | /// Returns true if it is a probable typo: |
81 | | /// \code //< stuff \endcode |
82 | | /// \code /*< stuff */ \endcode |
83 | 38.4M | bool isAlmostTrailingComment() const LLVM_READONLY { |
84 | 38.4M | return IsAlmostTrailingComment; |
85 | 38.4M | } |
86 | | |
87 | | /// Returns true if this comment is not a documentation comment. |
88 | 37.7M | bool isOrdinary() const LLVM_READONLY { |
89 | 37.7M | return ((Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC)21.6M ); |
90 | 37.7M | } |
91 | | |
92 | | /// Returns true if this comment any kind of a documentation comment. |
93 | 11.0k | bool isDocumentation() const LLVM_READONLY { |
94 | 11.0k | return !isInvalid() && !isOrdinary(); |
95 | 11.0k | } |
96 | | |
97 | | /// Returns raw comment text with comment markers. |
98 | 38.5M | StringRef getRawText(const SourceManager &SourceMgr) const { |
99 | 38.5M | if (RawTextValid) |
100 | 4.86k | return RawText; |
101 | | |
102 | 38.5M | RawText = getRawTextSlow(SourceMgr); |
103 | 38.5M | RawTextValid = true; |
104 | 38.5M | return RawText; |
105 | 38.5M | } |
106 | | |
107 | 38.3M | SourceRange getSourceRange() const LLVM_READONLY { return Range; } |
108 | 418k | SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); } |
109 | 269k | SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); } |
110 | | |
111 | 1.02k | const char *getBriefText(const ASTContext &Context) const { |
112 | 1.02k | if (BriefTextValid) |
113 | 121 | return BriefText; |
114 | | |
115 | 901 | return extractBriefText(Context); |
116 | 1.02k | } |
117 | | |
118 | | /// Returns sanitized comment text, suitable for presentation in editor UIs. |
119 | | /// E.g. will transform: |
120 | | /// // This is a long multiline comment. |
121 | | /// // Parts of it might be indented. |
122 | | /// /* The comments styles might be mixed. */ |
123 | | /// into |
124 | | /// "This is a long multiline comment.\n" |
125 | | /// " Parts of it might be indented.\n" |
126 | | /// "The comments styles might be mixed." |
127 | | /// Also removes leading indentation and sanitizes some common cases: |
128 | | /// /* This is a first line. |
129 | | /// * This is a second line. It is indented. |
130 | | /// * This is a third line. */ |
131 | | /// and |
132 | | /// /* This is a first line. |
133 | | /// This is a second line. It is indented. |
134 | | /// This is a third line. */ |
135 | | /// will both turn into: |
136 | | /// "This is a first line.\n" |
137 | | /// " This is a second line. It is indented.\n" |
138 | | /// "This is a third line." |
139 | | std::string getFormattedText(const SourceManager &SourceMgr, |
140 | | DiagnosticsEngine &Diags) const; |
141 | | |
142 | | struct CommentLine { |
143 | | std::string Text; |
144 | | PresumedLoc Begin; |
145 | | PresumedLoc End; |
146 | | |
147 | | CommentLine(StringRef Text, PresumedLoc Begin, PresumedLoc End) |
148 | 45 | : Text(Text), Begin(Begin), End(End) {} |
149 | | }; |
150 | | |
151 | | /// Returns sanitized comment text as separated lines with locations in |
152 | | /// source, suitable for further processing and rendering requiring source |
153 | | /// locations. |
154 | | std::vector<CommentLine> getFormattedLines(const SourceManager &SourceMgr, |
155 | | DiagnosticsEngine &Diags) const; |
156 | | |
157 | | /// Parse the comment, assuming it is attached to decl \c D. |
158 | | comments::FullComment *parse(const ASTContext &Context, |
159 | | const Preprocessor *PP, const Decl *D) const; |
160 | | |
161 | | private: |
162 | | SourceRange Range; |
163 | | |
164 | | mutable StringRef RawText; |
165 | | mutable const char *BriefText; |
166 | | |
167 | | mutable bool RawTextValid : 1; ///< True if RawText is valid |
168 | | mutable bool BriefTextValid : 1; ///< True if BriefText is valid |
169 | | |
170 | | unsigned Kind : 3; |
171 | | |
172 | | /// True if comment is attached to a declaration in ASTContext. |
173 | | bool IsAttached : 1; |
174 | | |
175 | | bool IsTrailingComment : 1; |
176 | | bool IsAlmostTrailingComment : 1; |
177 | | |
178 | | /// Constructor for AST deserialization. |
179 | | RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment, |
180 | | bool IsAlmostTrailingComment) : |
181 | | Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K), |
182 | | IsAttached(false), IsTrailingComment(IsTrailingComment), |
183 | | IsAlmostTrailingComment(IsAlmostTrailingComment) |
184 | 213 | { } |
185 | | |
186 | | StringRef getRawTextSlow(const SourceManager &SourceMgr) const; |
187 | | |
188 | | const char *extractBriefText(const ASTContext &Context) const; |
189 | | |
190 | | friend class ASTReader; |
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 | 96.6k | 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 |