clang 17.0.0git
RawCommentList.h
Go to the documentation of this file.
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
14#include "llvm/ADT/ArrayRef.h"
15#include "llvm/ADT/DenseMap.h"
16#include "llvm/Support/Allocator.h"
17#include <map>
18
19namespace clang {
20
21class ASTContext;
22class ASTReader;
23class Decl;
24class DiagnosticsEngine;
25class Preprocessor;
26class SourceManager;
27
28namespace comments {
29 class FullComment;
30} // end namespace comments
31
33public:
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 RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
46
47 RawComment(const SourceManager &SourceMgr, SourceRange SR,
48 const CommentOptions &CommentOpts, bool Merged);
49
50 CommentKind getKind() const LLVM_READONLY {
51 return (CommentKind) Kind;
52 }
53
54 bool isInvalid() const LLVM_READONLY {
55 return Kind == RCK_Invalid;
56 }
57
58 bool isMerged() const LLVM_READONLY {
59 return Kind == RCK_Merged;
60 }
61
62 /// Is this comment attached to any declaration?
63 bool isAttached() const LLVM_READONLY {
64 return IsAttached;
65 }
66
67 void setAttached() {
68 IsAttached = true;
69 }
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 bool isTrailingComment() const LLVM_READONLY {
77 return IsTrailingComment;
78 }
79
80 /// Returns true if it is a probable typo:
81 /// \code //< stuff \endcode
82 /// \code /*< stuff */ \endcode
83 bool isAlmostTrailingComment() const LLVM_READONLY {
84 return IsAlmostTrailingComment;
85 }
86
87 /// Returns true if this comment is not a documentation comment.
88 bool isOrdinary() const LLVM_READONLY {
89 return ((Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC));
90 }
91
92 /// Returns true if this comment any kind of a documentation comment.
93 bool isDocumentation() const LLVM_READONLY {
94 return !isInvalid() && !isOrdinary();
95 }
96
97 /// Returns raw comment text with comment markers.
98 StringRef getRawText(const SourceManager &SourceMgr) const {
99 if (RawTextValid)
100 return RawText;
101
102 RawText = getRawTextSlow(SourceMgr);
103 RawTextValid = true;
104 return RawText;
105 }
106
107 SourceRange getSourceRange() const LLVM_READONLY { return Range; }
108 SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }
109 SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }
110
111 const char *getBriefText(const ASTContext &Context) const {
112 if (BriefTextValid)
113 return BriefText;
114
115 return extractBriefText(Context);
116 }
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;
146
148 : 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
161private:
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 { }
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.
196public:
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
209 unsigned Offset) const;
210 unsigned getCommentEndOffset(RawComment *C) const;
211
212private:
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
Defines the clang::CommentOptions interface.
unsigned Offset
Definition: Format.cpp:2778
Defines the clang::SourceLocation class and associated facilities.
Holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic ...
Definition: ASTContext.h:182
Reads an AST files chain containing the contents of a translation unit.
Definition: ASTReader.h:366
Writes an AST file containing the contents of a translation unit.
Definition: ASTWriter.h:86
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:83
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:192
An opaque identifier used by SourceManager which refers to a source file (MemoryBuffer) along with it...
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:128
Represents an unpacked "presumed" location which can be presented to the user.
This class represents all comments included in the translation unit, sorted in order of appearance in...
RawCommentList(SourceManager &SourceMgr)
unsigned getCommentBeginLine(RawComment *C, FileID File, unsigned Offset) const
const std::map< unsigned, RawComment * > * getCommentsInFile(FileID File) const
unsigned getCommentEndOffset(RawComment *C) const
void addComment(const RawComment &RC, const CommentOptions &CommentOpts, llvm::BumpPtrAllocator &Allocator)
@ RCK_OrdinaryC
Any normal C comment.
@ RCK_Merged
Two or more documentation comments merged together.
@ RCK_Invalid
Invalid comment.
@ RCK_OrdinaryBCPL
Any normal BCPL comments.
bool isOrdinary() const LLVM_READONLY
Returns true if this comment is not a documentation comment.
bool isTrailingComment() const LLVM_READONLY
Returns true if it is a comment that should be put after a member:
StringRef getRawText(const SourceManager &SourceMgr) const
Returns raw comment text with comment markers.
SourceLocation getEndLoc() const LLVM_READONLY
std::vector< CommentLine > getFormattedLines(const SourceManager &SourceMgr, DiagnosticsEngine &Diags) const
Returns sanitized comment text as separated lines with locations in source, suitable for further proc...
bool isInvalid() const LLVM_READONLY
std::string getFormattedText(const SourceManager &SourceMgr, DiagnosticsEngine &Diags) const
Returns sanitized comment text, suitable for presentation in editor UIs.
bool isAlmostTrailingComment() const LLVM_READONLY
Returns true if it is a probable typo:
bool isAttached() const LLVM_READONLY
Is this comment attached to any declaration?
CommentKind getKind() const LLVM_READONLY
SourceRange getSourceRange() const LLVM_READONLY
bool isMerged() const LLVM_READONLY
SourceLocation getBeginLoc() const LLVM_READONLY
bool isDocumentation() const LLVM_READONLY
Returns true if this comment any kind of a documentation comment.
const char * getBriefText(const ASTContext &Context) const
comments::FullComment * parse(const ASTContext &Context, const Preprocessor *PP, const Decl *D) const
Parse the comment, assuming it is attached to decl D.
Encodes a location in the source.
This class handles loading and caching of source files into memory.
A trivial tuple used to represent a source range.
SourceLocation getEnd() const
SourceLocation getBegin() const
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1077
@ Decl
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
@ C
Languages that the frontend can parse and compile.
#define false
Definition: stdbool.h:22
Options for controlling comment parsing.
CommentLine(StringRef Text, PresumedLoc Begin, PresumedLoc End)