1eea56dee6223e3726c57ce338f07ae3a8b4625b
[lldb.git] / clang / include / clang / AST / RawCommentList.h
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 "clang/Basic/SourceManager.h"
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<>
178 class BeforeThanCompare<RawComment> {
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.
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