clang  16.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 
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 {
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 
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.
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:636
Offset
unsigned Offset
Definition: Format.cpp:2717
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:209
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:129
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