clang
15.0.0git
include
clang
AST
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
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
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
;
144
PresumedLoc
Begin
;
145
PresumedLoc
End
;
146
147
CommentLine
(StringRef
Text
,
PresumedLoc
Begin
,
PresumedLoc
End
)
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
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
{ }
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
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
clang::RawComment::CommentKind
CommentKind
Definition:
RawCommentList.h:34
clang::SourceRange
A trivial tuple used to represent a source range.
Definition:
SourceLocation.h:210
string
string(SUBSTRING ${CMAKE_CURRENT_BINARY_DIR} 0 ${PATH_LIB_START} PATH_HEAD) string(SUBSTRING $
Definition:
CMakeLists.txt:22
clang::SourceLocation
Encodes a location in the source.
Definition:
SourceLocation.h:86
clang::RawComment::setAttached
void setAttached()
Definition:
RawCommentList.h:67
clang::SourceRange::getBegin
SourceLocation getBegin() const
Definition:
SourceLocation.h:219
clang::DiagnosticsEngine
Concrete class used by the front-end to report problems and issues.
Definition:
Diagnostic.h:192
clang::RawComment::getKind
CommentKind getKind() const LLVM_READONLY
Definition:
RawCommentList.h:50
clang::RawComment::getSourceRange
SourceRange getSourceRange() const LLVM_READONLY
Definition:
RawCommentList.h:107
clang::RawCommentList::getCommentEndOffset
unsigned getCommentEndOffset(RawComment *C) const
Definition:
RawCommentList.cpp:350
clang::RawComment::isTrailingComment
bool isTrailingComment() const LLVM_READONLY
Returns true if it is a comment that should be put after a member:
Definition:
RawCommentList.h:76
clang::RawComment::RCK_Invalid
@ RCK_Invalid
Invalid comment.
Definition:
RawCommentList.h:35
clang::RawComment::parse
comments::FullComment * parse(const ASTContext &Context, const Preprocessor *PP, const Decl *D) const
Parse the comment, assuming it is attached to decl D.
Definition:
RawCommentList.cpp:204
clang::RawComment::getFormattedLines
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...
Definition:
RawCommentList.cpp:378
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition:
SourceManager.h:627
Offset
unsigned Offset
Definition:
Format.cpp:2574
clang::CodeGen::AlignmentSource::Decl
@ Decl
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
clang::RawCommentList
This class represents all comments included in the translation unit, sorted in order of appearance in...
Definition:
RawCommentList.h:195
clang::RawComment::CommentLine
Definition:
RawCommentList.h:142
clang::RawCommentList::addComment
void addComment(const RawComment &RC, const CommentOptions &CommentOpts, llvm::BumpPtrAllocator &Allocator)
Definition:
RawCommentList.cpp:274
clang::RawComment::getEndLoc
SourceLocation getEndLoc() const LLVM_READONLY
Definition:
RawCommentList.h:109
clang::RawCommentList::RawCommentList
RawCommentList(SourceManager &SourceMgr)
Definition:
RawCommentList.h:197
clang::RawComment::getRawText
StringRef getRawText(const SourceManager &SourceMgr) const
Returns raw comment text with comment markers.
Definition:
RawCommentList.h:98
clang::RawCommentList::empty
bool empty() const
Definition:
RawCommentList.cpp:338
clang::RawComment::getFormattedText
std::string getFormattedText(const SourceManager &SourceMgr, DiagnosticsEngine &Diags) const
Returns sanitized comment text, suitable for presentation in editor UIs.
Definition:
RawCommentList.cpp:360
clang::SourceRange::getEnd
SourceLocation getEnd() const
Definition:
SourceLocation.h:220
clang::ASTContext
Holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic ...
Definition:
ASTContext.h:208
clang::comments::FullComment
A full comment attached to a declaration, contains block content.
Definition:
Comment.h:1077
clang::RawComment::CommentLine::Text
std::string Text
Definition:
RawCommentList.h:143
clang::RawComment
Definition:
RawCommentList.h:32
clang::RawComment::isAttached
bool isAttached() const LLVM_READONLY
Is this comment attached to any declaration?
Definition:
RawCommentList.h:63
clang::ASTWriter
Writes an AST file containing the contents of a translation unit.
Definition:
ASTWriter.h:85
clang::RawComment::isOrdinary
bool isOrdinary() const LLVM_READONLY
Returns true if this comment is not a documentation comment.
Definition:
RawCommentList.h:88
clang::RawCommentList::getCommentBeginLine
unsigned getCommentBeginLine(RawComment *C, FileID File, unsigned Offset) const
Definition:
RawCommentList.cpp:340
clang::RawComment::isInvalid
bool isInvalid() const LLVM_READONLY
Definition:
RawCommentList.h:54
clang::RawComment::CommentLine::CommentLine
CommentLine(StringRef Text, PresumedLoc Begin, PresumedLoc End)
Definition:
RawCommentList.h:147
clang::RawCommentList::getCommentsInFile
const std::map< unsigned, RawComment * > * getCommentsInFile(FileID File) const
Definition:
RawCommentList.cpp:330
clang::RawComment::CommentLine::End
PresumedLoc End
Definition:
RawCommentList.h:145
SourceLocation.h
clang::RawComment::RCK_OrdinaryC
@ RCK_OrdinaryC
Any normal C comment.
Definition:
RawCommentList.h:37
false
#define false
Definition:
stdbool.h:22
clang::CommentOptions
Options for controlling comment parsing.
Definition:
CommentOptions.h:23
clang::RawComment::getBeginLoc
SourceLocation getBeginLoc() const LLVM_READONLY
Definition:
RawCommentList.h:108
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition:
DeclBase.h:83
clang::RawComment::RawComment
RawComment()
Definition:
RawCommentList.h:45
clang::RawComment::RCK_Qt
@ RCK_Qt
Definition:
RawCommentList.h:41
clang::ASTReader
Reads an AST files chain containing the contents of a translation unit.
Definition:
ASTReader.h:341
clang::RawComment::CommentLine::Begin
PresumedLoc Begin
Definition:
RawCommentList.h:144
clang
Definition:
CalledOnceCheck.h:17
clang::RawComment::isAlmostTrailingComment
bool isAlmostTrailingComment() const LLVM_READONLY
Returns true if it is a probable typo:
Definition:
RawCommentList.h:83
clang::RawComment::RCK_BCPLExcl
@ RCK_BCPLExcl
Definition:
RawCommentList.h:39
clang::FileID
An opaque identifier used by SourceManager which refers to a source file (MemoryBuffer) along with it...
Definition:
SourceLocation.h:38
CommentOptions.h
clang::RawComment::RCK_JavaDoc
@ RCK_JavaDoc
Definition:
RawCommentList.h:40
clang::RawComment::isDocumentation
bool isDocumentation() const LLVM_READONLY
Returns true if this comment any kind of a documentation comment.
Definition:
RawCommentList.h:93
clang::RawComment::RCK_BCPLSlash
@ RCK_BCPLSlash
Definition:
RawCommentList.h:38
clang::RawComment::getBriefText
const char * getBriefText(const ASTContext &Context) const
Definition:
RawCommentList.h:111
clang::PresumedLoc
Represents an unpacked "presumed" location which can be presented to the user.
Definition:
SourceLocation.h:302
clang::Preprocessor
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition:
Preprocessor.h:130
clang::RawComment::RCK_Merged
@ RCK_Merged
Two or more documentation comments merged together.
Definition:
RawCommentList.h:42
clang::RawComment::isMerged
bool isMerged() const LLVM_READONLY
Definition:
RawCommentList.h:58
clang::RawComment::RCK_OrdinaryBCPL
@ RCK_OrdinaryBCPL
Any normal BCPL comments.
Definition:
RawCommentList.h:36
Generated on Sat Jun 25 2022 12:41:46 for clang by
1.8.17