clang  10.0.0svn
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 
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<>
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.
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
bool operator()(const RawComment &LHS, const RawComment &RHS)
bool isInvalid() const LLVM_READONLY
Defines the SourceManager interface.
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:88
Any normal BCPL comments.
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
Options for controlling comment parsing.
SourceRange getSourceRange() const LLVM_READONLY
Holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic ...
Definition: ASTContext.h:160
This class represents all comments included in the translation unit, sorted in order of appearance in...
bool operator()(const RawComment *LHS, const RawComment *RHS)
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:149
Comparison function object.
SourceLocation getEndLoc() const LLVM_READONLY
RawCommentList(SourceManager &SourceMgr)
bool isAttached() const LLVM_READONLY
Is this comment attached to any declaration?
unsigned Offset
Definition: Format.cpp:1809
Any normal C comment.
bool isAlmostTrailingComment() const LLVM_READONLY
Returns true if it is a probable typo:
Defines the clang::CommentOptions interface.
SourceLocation getBeginLoc() const LLVM_READONLY
const SourceManager & SM
Definition: Format.cpp:1667
bool isOrdinary() const LLVM_READONLY
Returns true if this comment is not a documentation comment.
#define false
Definition: stdbool.h:17
Kind
Encodes a location in the source.
BeforeThanCompare(const SourceManager &SM)
An opaque identifier used by SourceManager which refers to a source file (MemoryBuffer) along with it...
static bool isInvalid(LocType Loc, bool *Invalid)
Dataflow Directional Tag Classes.
bool isTrailingComment() const LLVM_READONLY
Returns true if it is a comment that should be put after a member:
Reads an AST files chain containing the contents of a translation unit.
Definition: ASTReader.h:354
bool isMerged() const LLVM_READONLY
Defines the clang::SourceLocation class and associated facilities.
StringRef getRawText(const SourceManager &SourceMgr) const
Returns raw comment text with comment markers.
CommentKind getKind() const LLVM_READONLY
Writes an AST file containing the contents of a translation unit.
Definition: ASTWriter.h:103
bool isDocumentation() const LLVM_READONLY
Returns true if this comment any kind of a documentation comment.
const char * getBriefText(const ASTContext &Context) const
A trivial tuple used to represent a source range.
This class handles loading and caching of source files into memory.
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1091
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:125