clang  8.0.0svn
RawCommentList.h
Go to the documentation of this file.
1 //===--- RawCommentList.h - Classes for processing raw comments -*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #ifndef LLVM_CLANG_AST_RAWCOMMENTLIST_H
11 #define LLVM_CLANG_AST_RAWCOMMENTLIST_H
12 
15 #include "llvm/ADT/ArrayRef.h"
16 
17 namespace clang {
18 
19 class ASTContext;
20 class ASTReader;
21 class Decl;
22 class Preprocessor;
23 
24 namespace comments {
25  class FullComment;
26 } // end namespace comments
27 
28 class RawComment {
29 public:
30  enum CommentKind {
31  RCK_Invalid, ///< Invalid comment
32  RCK_OrdinaryBCPL, ///< Any normal BCPL comments
33  RCK_OrdinaryC, ///< Any normal C comment
34  RCK_BCPLSlash, ///< \code /// stuff \endcode
35  RCK_BCPLExcl, ///< \code //! stuff \endcode
36  RCK_JavaDoc, ///< \code /** stuff */ \endcode
37  RCK_Qt, ///< \code /*! stuff */ \endcode, also used by HeaderDoc
38  RCK_Merged ///< Two or more documentation comments merged together
39  };
40 
41  RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
42 
43  RawComment(const SourceManager &SourceMgr, SourceRange SR,
44  const CommentOptions &CommentOpts, bool Merged);
45 
46  CommentKind getKind() const LLVM_READONLY {
47  return (CommentKind) Kind;
48  }
49 
50  bool isInvalid() const LLVM_READONLY {
51  return Kind == RCK_Invalid;
52  }
53 
54  bool isMerged() const LLVM_READONLY {
55  return Kind == RCK_Merged;
56  }
57 
58  /// Is this comment attached to any declaration?
59  bool isAttached() const LLVM_READONLY {
60  return IsAttached;
61  }
62 
63  void setAttached() {
64  IsAttached = true;
65  }
66 
67  /// Returns true if it is a comment that should be put after a member:
68  /// \code ///< stuff \endcode
69  /// \code //!< stuff \endcode
70  /// \code /**< stuff */ \endcode
71  /// \code /*!< stuff */ \endcode
72  bool isTrailingComment() const LLVM_READONLY {
73  return IsTrailingComment;
74  }
75 
76  /// Returns true if it is a probable typo:
77  /// \code //< stuff \endcode
78  /// \code /*< stuff */ \endcode
79  bool isAlmostTrailingComment() const LLVM_READONLY {
80  return IsAlmostTrailingComment;
81  }
82 
83  /// Returns true if this comment is not a documentation comment.
84  bool isOrdinary() const LLVM_READONLY {
85  return ((Kind == RCK_OrdinaryBCPL) || (Kind == RCK_OrdinaryC));
86  }
87 
88  /// Returns true if this comment any kind of a documentation comment.
89  bool isDocumentation() const LLVM_READONLY {
90  return !isInvalid() && !isOrdinary();
91  }
92 
93  /// Returns raw comment text with comment markers.
94  StringRef getRawText(const SourceManager &SourceMgr) const {
95  if (RawTextValid)
96  return RawText;
97 
98  RawText = getRawTextSlow(SourceMgr);
99  RawTextValid = true;
100  return RawText;
101  }
102 
103  SourceRange getSourceRange() const LLVM_READONLY { return Range; }
104  LLVM_ATTRIBUTE_DEPRECATED(SourceLocation getLocStart() const LLVM_READONLY,
105  "Use getBeginLoc instead") {
106  return getBeginLoc();
107  }
108  SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }
109  LLVM_ATTRIBUTE_DEPRECATED(SourceLocation getLocEnd() const LLVM_READONLY,
110  "Use getEndLoc instead") {
111  return getEndLoc();
112  }
113  SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }
114 
115  const char *getBriefText(const ASTContext &Context) const {
116  if (BriefTextValid)
117  return BriefText;
118 
119  return extractBriefText(Context);
120  }
121 
122  /// Returns sanitized comment text, suitable for presentation in editor UIs.
123  /// E.g. will transform:
124  /// // This is a long multiline comment.
125  /// // Parts of it might be indented.
126  /// /* The comments styles might be mixed. */
127  /// into
128  /// "This is a long multiline comment.\n"
129  /// " Parts of it might be indented.\n"
130  /// "The comments styles might be mixed."
131  /// Also removes leading indentation and sanitizes some common cases:
132  /// /* This is a first line.
133  /// * This is a second line. It is indented.
134  /// * This is a third line. */
135  /// and
136  /// /* This is a first line.
137  /// This is a second line. It is indented.
138  /// This is a third line. */
139  /// will both turn into:
140  /// "This is a first line.\n"
141  /// " This is a second line. It is indented.\n"
142  /// "This is a third line."
143  std::string getFormattedText(const SourceManager &SourceMgr,
144  DiagnosticsEngine &Diags) const;
145 
146  /// Parse the comment, assuming it is attached to decl \c D.
147  comments::FullComment *parse(const ASTContext &Context,
148  const Preprocessor *PP, const Decl *D) const;
149 
150 private:
151  SourceRange Range;
152 
153  mutable StringRef RawText;
154  mutable const char *BriefText;
155 
156  mutable bool RawTextValid : 1; ///< True if RawText is valid
157  mutable bool BriefTextValid : 1; ///< True if BriefText is valid
158 
159  unsigned Kind : 3;
160 
161  /// True if comment is attached to a declaration in ASTContext.
162  bool IsAttached : 1;
163 
164  bool IsTrailingComment : 1;
165  bool IsAlmostTrailingComment : 1;
166 
167  /// Constructor for AST deserialization.
168  RawComment(SourceRange SR, CommentKind K, bool IsTrailingComment,
169  bool IsAlmostTrailingComment) :
170  Range(SR), RawTextValid(false), BriefTextValid(false), Kind(K),
171  IsAttached(false), IsTrailingComment(IsTrailingComment),
172  IsAlmostTrailingComment(IsAlmostTrailingComment)
173  { }
174 
175  StringRef getRawTextSlow(const SourceManager &SourceMgr) const;
176 
177  const char *extractBriefText(const ASTContext &Context) const;
178 
179  friend class ASTReader;
180 };
181 
182 /// Compare comments' source locations.
183 template<>
185  const SourceManager &SM;
186 
187 public:
188  explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
189 
190  bool operator()(const RawComment &LHS, const RawComment &RHS) {
191  return SM.isBeforeInTranslationUnit(LHS.getBeginLoc(), RHS.getBeginLoc());
192  }
193 
194  bool operator()(const RawComment *LHS, const RawComment *RHS) {
195  return operator()(*LHS, *RHS);
196  }
197 };
198 
199 /// This class represents all comments included in the translation unit,
200 /// sorted in order of appearance in the translation unit.
202 public:
203  RawCommentList(SourceManager &SourceMgr) : SourceMgr(SourceMgr) {}
204 
205  void addComment(const RawComment &RC, const CommentOptions &CommentOpts,
206  llvm::BumpPtrAllocator &Allocator);
207 
209  return Comments;
210  }
211 
212 private:
213  SourceManager &SourceMgr;
214  std::vector<RawComment *> Comments;
215 
216  void addDeserializedComments(ArrayRef<RawComment *> DeserializedComments);
217 
218  friend class ASTReader;
219 };
220 
221 } // end namespace clang
222 
223 #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:86
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
ArrayRef< RawComment * > getComments() const
Holds long-lived AST nodes (such as types and decls) that can be referred to throughout the semantic ...
Definition: ASTContext.h:153
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?
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:1475
bool isOrdinary() const LLVM_READONLY
Returns true if this comment is not a documentation comment.
#define false
Definition: stdbool.h:33
Kind
Encodes a location in the source.
LLVM_ATTRIBUTE_DEPRECATED(SourceLocation getLocEnd() const LLVM_READONLY, "Use getEndLoc instead")
BeforeThanCompare(const SourceManager &SM)
static bool isInvalid(LocType Loc, bool *Invalid)
LLVM_ATTRIBUTE_DEPRECATED(SourceLocation getLocStart() const LLVM_READONLY, "Use getBeginLoc instead")
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
StringRef getRawText(const SourceManager &SourceMgr) const
Returns raw comment text with comment markers.
CommentKind getKind() 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
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:1100
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:127