Coverage Report

Created: 2023-11-11 10:31

/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/AST/CommentSema.h
Line
Count
Source
1
//===--- CommentSema.h - Doxygen comment semantic analysis ------*- 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
//  This file defines the semantic analysis class for Doxygen comments.
10
//
11
//===----------------------------------------------------------------------===//
12
13
#ifndef LLVM_CLANG_AST_COMMENTSEMA_H
14
#define LLVM_CLANG_AST_COMMENTSEMA_H
15
16
#include "clang/AST/Comment.h"
17
#include "clang/Basic/Diagnostic.h"
18
#include "clang/Basic/SourceLocation.h"
19
#include "llvm/ADT/ArrayRef.h"
20
#include "llvm/ADT/StringMap.h"
21
#include "llvm/ADT/StringRef.h"
22
#include "llvm/Support/Allocator.h"
23
24
namespace clang {
25
class Decl;
26
class SourceMgr;
27
class Preprocessor;
28
29
namespace comments {
30
class CommandTraits;
31
32
class Sema {
33
  Sema(const Sema &) = delete;
34
  void operator=(const Sema &) = delete;
35
36
  /// Allocator for AST nodes.
37
  llvm::BumpPtrAllocator &Allocator;
38
39
  /// Source manager for the comment being parsed.
40
  const SourceManager &SourceMgr;
41
42
  DiagnosticsEngine &Diags;
43
44
  CommandTraits &Traits;
45
46
  const Preprocessor *PP;
47
48
  /// Information about the declaration this comment is attached to.
49
  DeclInfo *ThisDeclInfo;
50
51
  /// Comment AST nodes that correspond to parameter names in
52
  /// \c TemplateParameters.
53
  ///
54
  /// Contains a valid value if \c DeclInfo->IsFilled is true.
55
  llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
56
57
  /// AST node for the \command and its aliases.
58
  const BlockCommandComment *BriefCommand;
59
60
  /// AST node for the \\headerfile command.
61
  const BlockCommandComment *HeaderfileCommand;
62
63
1.10k
  DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
64
1.10k
    return Diags.Report(Loc, DiagID);
65
1.10k
  }
66
67
  /// A stack of HTML tags that are currently open (not matched with closing
68
  /// tags).
69
  SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
70
71
public:
72
  Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
73
       DiagnosticsEngine &Diags, CommandTraits &Traits,
74
       const Preprocessor *PP);
75
76
  void setDecl(const Decl *D);
77
78
  /// Returns a copy of array, owned by Sema's allocator.
79
  template<typename T>
80
24.6k
  ArrayRef<T> copyArray(ArrayRef<T> Source) {
81
24.6k
    if (!Source.empty())
82
24.3k
      return Source.copy(Allocator);
83
264
    return std::nullopt;
84
24.6k
  }
llvm::ArrayRef<clang::comments::HTMLStartTagComment::Attribute> clang::comments::Sema::copyArray<clang::comments::HTMLStartTagComment::Attribute>(llvm::ArrayRef<clang::comments::HTMLStartTagComment::Attribute>)
Line
Count
Source
80
174
  ArrayRef<T> copyArray(ArrayRef<T> Source) {
81
174
    if (!Source.empty())
82
57
      return Source.copy(Allocator);
83
117
    return std::nullopt;
84
174
  }
llvm::ArrayRef<clang::comments::InlineContentComment*> clang::comments::Sema::copyArray<clang::comments::InlineContentComment*>(llvm::ArrayRef<clang::comments::InlineContentComment*>)
Line
Count
Source
80
20.0k
  ArrayRef<T> copyArray(ArrayRef<T> Source) {
81
20.0k
    if (!Source.empty())
82
19.8k
      return Source.copy(Allocator);
83
129
    return std::nullopt;
84
20.0k
  }
llvm::ArrayRef<clang::comments::VerbatimBlockLineComment*> clang::comments::Sema::copyArray<clang::comments::VerbatimBlockLineComment*>(llvm::ArrayRef<clang::comments::VerbatimBlockLineComment*>)
Line
Count
Source
80
470
  ArrayRef<T> copyArray(ArrayRef<T> Source) {
81
470
    if (!Source.empty())
82
468
      return Source.copy(Allocator);
83
2
    return std::nullopt;
84
470
  }
llvm::ArrayRef<clang::comments::BlockContentComment*> clang::comments::Sema::copyArray<clang::comments::BlockContentComment*>(llvm::ArrayRef<clang::comments::BlockContentComment*>)
Line
Count
Source
80
3.83k
  ArrayRef<T> copyArray(ArrayRef<T> Source) {
81
3.83k
    if (!Source.empty())
82
3.81k
      return Source.copy(Allocator);
83
16
    return std::nullopt;
84
3.83k
  }
llvm::ArrayRef<unsigned int> clang::comments::Sema::copyArray<unsigned int>(llvm::ArrayRef<unsigned int>)
Line
Count
Source
80
122
  ArrayRef<T> copyArray(ArrayRef<T> Source) {
81
122
    if (!Source.empty())
82
122
      return Source.copy(Allocator);
83
0
    return std::nullopt;
84
122
  }
85
86
  ParagraphComment *actOnParagraphComment(
87
      ArrayRef<InlineContentComment *> Content);
88
89
  BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
90
                                              SourceLocation LocEnd,
91
                                              unsigned CommandID,
92
                                              CommandMarkerKind CommandMarker);
93
94
  void actOnBlockCommandArgs(BlockCommandComment *Command,
95
                             ArrayRef<BlockCommandComment::Argument> Args);
96
97
  void actOnBlockCommandFinish(BlockCommandComment *Command,
98
                               ParagraphComment *Paragraph);
99
100
  ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
101
                                              SourceLocation LocEnd,
102
                                              unsigned CommandID,
103
                                              CommandMarkerKind CommandMarker);
104
105
  void actOnParamCommandDirectionArg(ParamCommandComment *Command,
106
                                     SourceLocation ArgLocBegin,
107
                                     SourceLocation ArgLocEnd,
108
                                     StringRef Arg);
109
110
  void actOnParamCommandParamNameArg(ParamCommandComment *Command,
111
                                     SourceLocation ArgLocBegin,
112
                                     SourceLocation ArgLocEnd,
113
                                     StringRef Arg);
114
115
  void actOnParamCommandFinish(ParamCommandComment *Command,
116
                               ParagraphComment *Paragraph);
117
118
  TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
119
                                                SourceLocation LocEnd,
120
                                                unsigned CommandID,
121
                                                CommandMarkerKind CommandMarker);
122
123
  void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
124
                                      SourceLocation ArgLocBegin,
125
                                      SourceLocation ArgLocEnd,
126
                                      StringRef Arg);
127
128
  void actOnTParamCommandFinish(TParamCommandComment *Command,
129
                                ParagraphComment *Paragraph);
130
131
  InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
132
                                           SourceLocation CommandLocEnd,
133
                                           unsigned CommandID,
134
                                           ArrayRef<Comment::Argument> Args);
135
136
  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
137
                                            SourceLocation LocEnd,
138
                                            StringRef CommandName);
139
140
  InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
141
                                            SourceLocation LocEnd,
142
                                            unsigned CommandID);
143
144
  TextComment *actOnText(SourceLocation LocBegin,
145
                         SourceLocation LocEnd,
146
                         StringRef Text);
147
148
  VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
149
                                                unsigned CommandID);
150
151
  VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
152
                                                   StringRef Text);
153
154
  void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
155
                                SourceLocation CloseNameLocBegin,
156
                                StringRef CloseName,
157
                                ArrayRef<VerbatimBlockLineComment *> Lines);
158
159
  VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
160
                                         unsigned CommandID,
161
                                         SourceLocation TextBegin,
162
                                         StringRef Text);
163
164
  HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
165
                                              StringRef TagName);
166
167
  void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
168
                               ArrayRef<HTMLStartTagComment::Attribute> Attrs,
169
                               SourceLocation GreaterLoc,
170
                               bool IsSelfClosing);
171
172
  HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
173
                                     SourceLocation LocEnd,
174
                                     StringRef TagName);
175
176
  FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
177
178
private:
179
  void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
180
181
  void checkReturnsCommand(const BlockCommandComment *Command);
182
183
  /// Emit diagnostics about duplicate block commands that should be
184
  /// used only once per comment, e.g., \and \\returns.
185
  void checkBlockCommandDuplicate(const BlockCommandComment *Command);
186
187
  void checkDeprecatedCommand(const BlockCommandComment *Comment);
188
189
  void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
190
191
  void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
192
193
  void checkContainerDecl(const BlockCommandComment *Comment);
194
195
  /// Resolve parameter names to parameter indexes in function declaration.
196
  /// Emit diagnostics about unknown parameters.
197
  void resolveParamCommandIndexes(const FullComment *FC);
198
199
  /// \returns \c true if the declaration that this comment is attached to
200
  /// is a pointer to function/method/block type or has such a type.
201
  bool involvesFunctionType();
202
203
  bool isFunctionDecl();
204
  bool isAnyFunctionDecl();
205
206
  /// \returns \c true if declaration that this comment is attached to declares
207
  /// a function pointer.
208
  bool isFunctionPointerVarDecl();
209
  bool isFunctionOrMethodVariadic();
210
  bool isObjCMethodDecl();
211
  bool isObjCPropertyDecl();
212
  bool isTemplateOrSpecialization();
213
  bool isRecordLikeDecl();
214
  bool isClassOrStructDecl();
215
  /// \return \c true if the declaration that this comment is attached to
216
  /// declares either struct, class or tag typedef.
217
  bool isClassOrStructOrTagTypedefDecl();
218
  bool isUnionDecl();
219
  bool isObjCInterfaceDecl();
220
  bool isObjCProtocolDecl();
221
  bool isClassTemplateDecl();
222
  bool isFunctionTemplateDecl();
223
224
  ArrayRef<const ParmVarDecl *> getParamVars();
225
226
  /// Extract all important semantic information from
227
  /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
228
  void inspectThisDecl();
229
230
  /// Returns index of a function parameter with a given name.
231
  unsigned resolveParmVarReference(StringRef Name,
232
                                   ArrayRef<const ParmVarDecl *> ParamVars);
233
234
  /// Returns index of a function parameter with the name closest to a given
235
  /// typo.
236
  unsigned correctTypoInParmVarReference(StringRef Typo,
237
                                         ArrayRef<const ParmVarDecl *> ParamVars);
238
239
  bool resolveTParamReference(StringRef Name,
240
                              const TemplateParameterList *TemplateParameters,
241
                              SmallVectorImpl<unsigned> *Position);
242
243
  StringRef correctTypoInTParamReference(
244
                              StringRef Typo,
245
                              const TemplateParameterList *TemplateParameters);
246
247
  InlineCommandRenderKind getInlineCommandRenderKind(StringRef Name) const;
248
};
249
250
} // end namespace comments
251
} // end namespace clang
252
253
#endif
254