clang 19.0.0git
CommentSema.h
Go to the documentation of this file.
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"
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 SourceMgr;
27class Preprocessor;
28
29namespace comments {
30class CommandTraits;
31
32class 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 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
64 return Diags.Report(Loc, DiagID);
65 }
66
67 /// A stack of HTML tags that are currently open (not matched with closing
68 /// tags).
70
71public:
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>
81 if (!Source.empty())
82 return Source.copy(Allocator);
83 return std::nullopt;
84 }
85
88
90 SourceLocation LocEnd,
91 unsigned CommandID,
92 CommandMarkerKind CommandMarker);
93
96
98 ParagraphComment *Paragraph);
99
101 SourceLocation LocEnd,
102 unsigned CommandID,
103 CommandMarkerKind CommandMarker);
104
106 SourceLocation ArgLocBegin,
107 SourceLocation ArgLocEnd,
108 StringRef Arg);
109
111 SourceLocation ArgLocBegin,
112 SourceLocation ArgLocEnd,
113 StringRef Arg);
114
116 ParagraphComment *Paragraph);
117
119 SourceLocation LocEnd,
120 unsigned CommandID,
121 CommandMarkerKind CommandMarker);
122
124 SourceLocation ArgLocBegin,
125 SourceLocation ArgLocEnd,
126 StringRef Arg);
127
129 ParagraphComment *Paragraph);
130
132 SourceLocation CommandLocEnd,
133 unsigned CommandID,
135
137 SourceLocation LocEnd,
138 StringRef CommandName);
139
141 SourceLocation LocEnd,
142 unsigned CommandID);
143
145 SourceLocation LocEnd,
146 StringRef Text);
147
149 unsigned CommandID);
150
152 StringRef Text);
153
155 SourceLocation CloseNameLocBegin,
156 StringRef CloseName,
158
160 unsigned CommandID,
161 SourceLocation TextBegin,
162 StringRef Text);
163
165 StringRef TagName);
166
169 SourceLocation GreaterLoc,
170 bool IsSelfClosing);
171
173 SourceLocation LocEnd,
174 StringRef TagName);
175
177
178private:
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,
233
234 /// Returns index of a function parameter with the name closest to a given
235 /// typo.
236 unsigned correctTypoInParmVarReference(StringRef Typo,
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
Defines the Diagnostic-related interfaces.
StringRef Text
Definition: Format.cpp:2976
SourceLocation Loc
Definition: SemaObjC.cpp:755
Defines the clang::SourceLocation class and associated facilities.
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:86
A little helper class used to produce diagnostics.
Definition: Diagnostic.h:1271
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:192
DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID)
Issue the message to the client.
Definition: Diagnostic.h:1547
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:128
Encodes a location in the source.
This class handles loading and caching of source files into memory.
Stores a list of template parameters for a TemplateDecl and its derived classes.
Definition: DeclTemplate.h:73
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
Definition: Comment.h:604
This class provides information about commands that can be used in comments.
Any part of the comment.
Definition: Comment.h:65
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1083
An opening HTML tag with attributes.
Definition: Comment.h:433
A command with word-like arguments that is considered inline content.
Definition: Comment.h:335
Inline content (contained within a block).
Definition: Comment.h:265
A single paragraph that contains inline content.
Definition: Comment.h:555
Doxygen \param command.
Definition: Comment.h:711
FullComment * actOnFullComment(ArrayRef< BlockContentComment * > Blocks)
void actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
TParamCommandComment * actOnTParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
void actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph)
void actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:67
TextComment * actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text)
void actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef< BlockCommandComment::Argument > Args)
Definition: CommentSema.cpp:62
BlockCommandComment * actOnBlockCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:50
void actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
HTMLEndTagComment * actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName)
InlineCommandComment * actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID, ArrayRef< Comment::Argument > Args)
VerbatimLineComment * actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text)
void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef< VerbatimBlockLineComment * > Lines)
VerbatimBlockLineComment * actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text)
void actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph)
ArrayRef< T > copyArray(ArrayRef< T > Source)
Returns a copy of array, owned by Sema's allocator.
Definition: CommentSema.h:80
HTMLStartTagComment * actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName)
void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, ArrayRef< HTMLStartTagComment::Attribute > Attrs, SourceLocation GreaterLoc, bool IsSelfClosing)
ParamCommandComment * actOnParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:80
VerbatimBlockComment * actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID)
void actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
void setDecl(const Decl *D)
Definition: CommentSema.cpp:36
InlineContentComment * actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName)
ParagraphComment * actOnParagraphComment(ArrayRef< InlineContentComment * > Content)
Definition: CommentSema.cpp:45
Doxygen \tparam command, describes a template parameter.
Definition: Comment.h:793
A verbatim block command (e.
Definition: Comment.h:879
A line of text contained in a verbatim block.
Definition: Comment.h:854
A verbatim line command.
Definition: Comment.h:930
@ Decl
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
InlineCommandRenderKind
The most appropriate rendering mode for this command, chosen on command semantics in Doxygen.
Definition: Comment.h:326
CommandMarkerKind
Describes the syntax that was used in a documentation command.
Definition: Comment.h:38
The JSON file list parser is used to communicate input to InstallAPI.
Information about the declaration, useful to clients of FullComment.
Definition: Comment.h:962