Coverage Report

Created: 2020-02-18 08:44

/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/AST/RawCommentList.h
Line
Count
Source (jump to first uncovered line)
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
0
  RawComment() : Kind(RCK_Invalid), IsAlmostTrailingComment(false) { }
44
45
  RawComment(const SourceManager &SourceMgr, SourceRange SR,
46
             const CommentOptions &CommentOpts, bool Merged);
47
48
7.81k
  CommentKind getKind() const LLVM_READONLY {
49
7.81k
    return (CommentKind) Kind;
50
7.81k
  }
51
52
23.9M
  bool isInvalid() const LLVM_READONLY {
53
23.9M
    return Kind == RCK_Invalid;
54
23.9M
  }
55
56
0
  bool isMerged() const LLVM_READONLY {
57
0
    return Kind == RCK_Merged;
58
0
  }
59
60
  /// Is this comment attached to any declaration?
61
945
  bool isAttached() const LLVM_READONLY {
62
945
    return IsAttached;
63
945
  }
64
65
0
  void setAttached() {
66
0
    IsAttached = true;
67
0
  }
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
228k
  bool isTrailingComment() const LLVM_READONLY {
75
228k
    return IsTrailingComment;
76
228k
  }
77
78
  /// Returns true if it is a probable typo:
79
  /// \code //< stuff \endcode
80
  /// \code /*< stuff */ \endcode
81
23.9M
  bool isAlmostTrailingComment() const LLVM_READONLY {
82
23.9M
    return IsAlmostTrailingComment;
83
23.9M
  }
84
85
  /// Returns true if this comment is not a documentation comment.
86
23.8M
  bool isOrdinary() const LLVM_READONLY {
87
23.8M
    return ((Kind == RCK_OrdinaryBCPL) || 
(Kind == RCK_OrdinaryC)21.5M
);
88
23.8M
  }
89
90
  /// Returns true if this comment any kind of a documentation comment.
91
5.45k
  bool isDocumentation() const LLVM_READONLY {
92
5.45k
    return !isInvalid() && !isOrdinary();
93
5.45k
  }
94
95
  /// Returns raw comment text with comment markers.
96
24.0M
  StringRef getRawText(const SourceManager &SourceMgr) const {
97
24.0M
    if (RawTextValid)
98
3.14k
      return RawText;
99
24.0M
100
24.0M
    RawText = getRawTextSlow(SourceMgr);
101
24.0M
    RawTextValid = true;
102
24.0M
    return RawText;
103
24.0M
  }
104
105
23.9M
  SourceRange getSourceRange() const LLVM_READONLY { return Range; }
106
304k
  SourceLocation getBeginLoc() const LLVM_READONLY { return Range.getBegin(); }
107
194k
  SourceLocation getEndLoc() const LLVM_READONLY { return Range.getEnd(); }
108
109
1.01k
  const char *getBriefText(const ASTContext &Context) const {
110
1.01k
    if (BriefTextValid)
111
121
      return BriefText;
112
890
113
890
    return extractBriefText(Context);
114
890
  }
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
198
  { }
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
0
  explicit BeforeThanCompare(const SourceManager &SM) : SM(SM) { }
183
184
0
  bool operator()(const RawComment &LHS, const RawComment &RHS) {
185
0
    return SM.isBeforeInTranslationUnit(LHS.getBeginLoc(), RHS.getBeginLoc());
186
0
  }
187
188
0
  bool operator()(const RawComment *LHS, const RawComment *RHS) {
189
0
    return operator()(*LHS, *RHS);
190
0
  }
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
61.9k
  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