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
19namespace clang {
20
21class ASTContext;
22class ASTReader;
23class Decl;
24class Preprocessor;
25
26namespace comments {
27  class FullComment;
28} // end namespace comments
29
30class RawComment {
31public:
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
144private:
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.
177template<>
178class BeforeThanCompare<RawComment> {
179  const SourceManager &SM;
180
181public:
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.
195class RawCommentList {
196public:
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
212private:
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
226