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