clang 10.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"
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 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).
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 ArrayRef<T> copyArray(ArrayRef<T> Source) {
81 if (!Source.empty())
82 return Source.copy(Allocator);
83 return None;
84 }
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
135 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
136 SourceLocation CommandLocEnd,
137 unsigned CommandID,
138 SourceLocation ArgLocBegin,
139 SourceLocation ArgLocEnd,
140 StringRef Arg);
141
142 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
143 SourceLocation LocEnd,
144 StringRef CommandName);
145
146 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
147 SourceLocation LocEnd,
148 unsigned CommandID);
149
150 TextComment *actOnText(SourceLocation LocBegin,
151 SourceLocation LocEnd,
152 StringRef Text);
153
154 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
155 unsigned CommandID);
156
157 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
158 StringRef Text);
159
160 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
161 SourceLocation CloseNameLocBegin,
162 StringRef CloseName,
163 ArrayRef<VerbatimBlockLineComment *> Lines);
164
165 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
166 unsigned CommandID,
167 SourceLocation TextBegin,
168 StringRef Text);
169
170 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
171 StringRef TagName);
172
173 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
174 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
175 SourceLocation GreaterLoc,
176 bool IsSelfClosing);
177
178 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
179 SourceLocation LocEnd,
180 StringRef TagName);
181
182 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
183
184 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
185
186 void checkReturnsCommand(const BlockCommandComment *Command);
187
188 /// Emit diagnostics about duplicate block commands that should be
189 /// used only once per comment, e.g., \and \\returns.
190 void checkBlockCommandDuplicate(const BlockCommandComment *Command);
191
192 void checkDeprecatedCommand(const BlockCommandComment *Comment);
193
194 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
195
196 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
197
198 void checkContainerDecl(const BlockCommandComment *Comment);
199
200 /// Resolve parameter names to parameter indexes in function declaration.
201 /// Emit diagnostics about unknown parametrs.
202 void resolveParamCommandIndexes(const FullComment *FC);
203
204 bool isFunctionDecl();
205 bool isAnyFunctionDecl();
206
207 /// \returns \c true if declaration that this comment is attached to declares
208 /// a function pointer.
209 bool isFunctionPointerVarDecl();
210 /// \returns \c true if the declaration that this comment is attached to
211 /// declares a variable or a field whose type is a function or a block
212 /// pointer.
213 bool isFunctionOrBlockPointerVarLikeDecl();
214 bool isFunctionOrMethodVariadic();
215 bool isObjCMethodDecl();
216 bool isObjCPropertyDecl();
217 bool isTemplateOrSpecialization();
218 bool isRecordLikeDecl();
219 bool isClassOrStructDecl();
220 bool isUnionDecl();
221 bool isObjCInterfaceDecl();
222 bool isObjCProtocolDecl();
223 bool isClassTemplateDecl();
224 bool isFunctionTemplateDecl();
225
226 ArrayRef<const ParmVarDecl *> getParamVars();
227
228 /// Extract all important semantic information from
229 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
230 void inspectThisDecl();
231
232 /// Returns index of a function parameter with a given name.
233 unsigned resolveParmVarReference(StringRef Name,
234 ArrayRef<const ParmVarDecl *> ParamVars);
235
236 /// Returns index of a function parameter with the name closest to a given
237 /// typo.
238 unsigned correctTypoInParmVarReference(StringRef Typo,
239 ArrayRef<const ParmVarDecl *> ParamVars);
240
241 bool resolveTParamReference(StringRef Name,
242 const TemplateParameterList *TemplateParameters,
243 SmallVectorImpl<unsigned> *Position);
244
245 StringRef correctTypoInTParamReference(
246 StringRef Typo,
247 const TemplateParameterList *TemplateParameters);
248
249 InlineCommandComment::RenderKind
250 getInlineCommandRenderKind(StringRef Name) const;
251 };
252
253 } // end namespace comments
254 } // end namespace clang
255
256 #endif
257
clang::comments::Sema::actOnParamCommandFinish
void actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:274
clang::comments::Sema::correctTypoInTParamReference
StringRef correctTypoInTParamReference(StringRef Typo, const TemplateParameterList *TemplateParameters)
Definition: CommentSema.cpp:1125
clang::comments::Sema::getParamVars
ArrayRef< const ParmVarDecl * > getParamVars()
Definition: CommentSema.cpp:985
clang::comments::Sema::isClassTemplateDecl
bool isClassTemplateDecl()
Definition: CommentSema.cpp:949
clang::comments::Sema::isFunctionTemplateDecl
bool isFunctionTemplateDecl()
Definition: CommentSema.cpp:958
clang::comments::Sema::checkBlockCommandEmptyParagraph
void checkBlockCommandEmptyParagraph(BlockCommandComment *Command)
Definition: CommentSema.cpp:562
clang::comments::Sema::actOnHTMLStartTagFinish
void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, ArrayRef< HTMLStartTagComment::Attribute > Attrs, SourceLocation GreaterLoc, bool IsSelfClosing)
Definition: CommentSema.cpp:462
clang::comments::Sema::isFunctionOrMethodVariadic
bool isFunctionOrMethodVariadic()
Definition: CommentSema.cpp:831
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:88
clang::comments::Sema::actOnParagraphComment
ParagraphComment * actOnParagraphComment(ArrayRef< InlineContentComment *> Content)
Definition: CommentSema.cpp:44
clang::comments::Sema::isClassOrStructDecl
bool isClassOrStructDecl()
Definition: CommentSema.cpp:939
clang::comments::Sema::actOnVerbatimBlockStart
VerbatimBlockComment * actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID)
Definition: CommentSema.cpp:419
clang::DiagnosticsEngine::Report
DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID)
Issue the message to the client.
Definition: Diagnostic.h:1300
clang::CodeGen::AlignmentSource::Decl
The l-value was an access to a declared entity or something equivalently strong, like the address of ...
clang::comments::Sema::correctTypoInParmVarReference
unsigned correctTypoInParmVarReference(StringRef Typo, ArrayRef< const ParmVarDecl *> ParamVars)
Returns index of a function parameter with the name closest to a given typo.
Definition: CommentSema.cpp:1060
clang::comments::Sema::actOnHTMLStartTagStart
HTMLStartTagComment * actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName)
Definition: CommentSema.cpp:457
clang::comments::Sema::actOnBlockCommandArgs
void actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef< BlockCommandComment::Argument > Args)
Definition: CommentSema.cpp:61
clang::comments::Sema::checkContainerDeclVerbatimLine
void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:130
clang::TemplateParameterList
Stores a list of template parameters for a TemplateDecl and its derived classes.
Definition: DeclTemplate.h:69
clang::comments::Sema::checkBlockCommandDuplicate
void checkBlockCommandDuplicate(const BlockCommandComment *Command)
Emit diagnostics about duplicate block commands that should be used only once per comment...
Definition: CommentSema.cpp:626
clang::comments::Sema::actOnVerbatimBlockFinish
void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef< VerbatimBlockLineComment *> Lines)
Definition: CommentSema.cpp:433
llvm::SmallVectorImpl
Definition: LLVM.h:36
clang::comments::Sema::actOnText
TextComment * actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text)
Definition: CommentSema.cpp:413
clang::comments::InlineCommandComment
A command with word-like arguments that is considered inline content.
Definition: Comment.h:299
clang::comments::Sema
Definition: CommentSema.h:32
clang::comments::VerbatimBlockLineComment
A line of text contained in a verbatim block.
Definition: Comment.h:865
clang::comments::TextComment
Plain text.
Definition: Comment.h:263
clang::comments::VerbatimLineComment
A verbatim line command.
Definition: Comment.h:945
Comment.h
clang::comments::Sema::checkReturnsCommand
void checkReturnsCommand(const BlockCommandComment *Command)
Definition: CommentSema.cpp:580
clang::comments::Sema::isFunctionPointerVarDecl
bool isFunctionPointerVarDecl()
Definition: CommentSema.cpp:859
clang::DiagnosticsEngine
Concrete class used by the front-end to report problems and issues.
Definition: Diagnostic.h:149
clang::comments::Sema::actOnUnknownCommand
InlineContentComment * actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName)
Definition: CommentSema.cpp:396
clang::comments::Sema::actOnFullComment
FullComment * actOnFullComment(ArrayRef< BlockContentComment *> Blocks)
Definition: CommentSema.cpp:543
clang::comments::Comment
Any part of the comment.
Definition: Comment.h:52
Diagnostic.h
Defines the Diagnostic-related interfaces.
clang::comments::InlineContentComment
Inline content (contained within a block).
Definition: Comment.h:238
llvm::ArrayRef
Definition: LLVM.h:31
clang::comments::InlineCommandComment::RenderKind
RenderKind
The most appropriate rendering mode for this command, chosen on command semantics in Doxygen...
Definition: Comment.h:310
clang::comments::Sema::isObjCPropertyDecl
bool isObjCPropertyDecl()
Definition: CommentSema.cpp:903
clang::comments::Sema::copyArray
ArrayRef< T > copyArray(ArrayRef< T > Source)
Returns a copy of array, owned by Sema&#39;s allocator.
Definition: CommentSema.h:80
clang::comments::VerbatimBlockComment
A verbatim block command (e.
Definition: Comment.h:893
clang::comments::Sema::isTemplateOrSpecialization
bool isTemplateOrSpecialization()
Definition: CommentSema.cpp:911
clang::DiagnosticBuilder
A little helper class used to produce diagnostics.
Definition: Diagnostic.h:1053
clang::comments::Sema::resolveTParamReference
bool resolveTParamReference(StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl< unsigned > *Position)
Definition: CommentSema.cpp:1098
clang::comments::Sema::isObjCMethodDecl
bool isObjCMethodDecl()
Definition: CommentSema.cpp:854
clang::comments::Sema::inspectThisDecl
void inspectThisDecl()
Extract all important semantic information from ThisDeclInfo->ThisDecl into ThisDeclInfo members...
Definition: CommentSema.cpp:991
clang::comments::Sema::actOnTParamCommandFinish
void actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:357
clang::comments::CommandMarkerKind
CommandMarkerKind
Describes the syntax that was used in a documentation command.
Definition: Comment.h:36
clang::comments::BlockCommandComment
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
Definition: Comment.h:598
clang::comments::Sema::actOnVerbatimBlockLine
VerbatimBlockLineComment * actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text)
Definition: CommentSema.cpp:428
clang::comments::Sema::resolveParmVarReference
unsigned resolveParmVarReference(StringRef Name, ArrayRef< const ParmVarDecl *> ParamVars)
Returns index of a function parameter with a given name.
Definition: CommentSema.cpp:995
clang::comments::HTMLStartTagComment
An opening HTML tag with attributes.
Definition: Comment.h:415
clang::comments::Sema::checkFunctionDeclVerbatimLine
void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:97
clang::comments::Sema::actOnTParamCommandStart
TParamCommandComment * actOnTParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:280
clang::comments::Sema::actOnBlockCommandFinish
void actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:66
clang::comments::Sema::isFunctionDecl
bool isFunctionDecl()
Definition: CommentSema.cpp:818
clang::comments::CommandTraits
This class provides information about commands that can be used in comments.
Definition: CommentCommandTraits.h:127
clang::comments::Sema::getInlineCommandRenderKind
InlineCommandComment::RenderKind getInlineCommandRenderKind(StringRef Name) const
Definition: CommentSema.cpp:1139
clang::comments::Sema::checkDeprecatedCommand
void checkDeprecatedCommand(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:664
clang::comments::Sema::checkContainerDecl
void checkContainerDecl(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:167
clang::SourceLocation
Encodes a location in the source.
Definition: SourceLocation.h:86
clang::comments::Sema::actOnVerbatimLine
VerbatimLineComment * actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text)
Definition: CommentSema.cpp:442
clang::comments::Sema::isObjCProtocolDecl
bool isObjCProtocolDecl()
Definition: CommentSema.cpp:976
clang::comments::Sema::isFunctionOrBlockPointerVarLikeDecl
bool isFunctionOrBlockPointerVarLikeDecl()
Definition: CommentSema.cpp:873
clang::comments::Sema::actOnParamCommandStart
ParamCommandComment * actOnParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:79
llvm::SmallVector
Definition: LLVM.h:35
clang::comments::HTMLEndTagComment
A closing HTML tag.
Definition: Comment.h:509
clang::comments::TParamCommandComment
Doxygen \tparam command, describes a template parameter.
Definition: Comment.h:801
clang
Dataflow Directional Tag Classes.
Definition: CFGReachabilityAnalysis.h:21
clang::comments::Sema::actOnBlockCommandStart
BlockCommandComment * actOnBlockCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:49
clang::comments::DeclInfo
Information about the declaration, useful to clients of FullComment.
Definition: Comment.h:982
clang::comments::ParagraphComment
A single paragraph that contains inline content.
Definition: Comment.h:548
clang::comments::Sema::actOnHTMLEndTag
HTMLEndTagComment * actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName)
Definition: CommentSema.cpp:475
clang::comments::Sema::isAnyFunctionDecl
bool isAnyFunctionDecl()
Definition: CommentSema.cpp:826
clang::comments::Sema::isUnionDecl
bool isUnionDecl()
Definition: CommentSema.cpp:928
clang::comments::Sema::actOnTParamCommandParamNameArg
void actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:298
clang::comments::Sema::isObjCInterfaceDecl
bool isObjCInterfaceDecl()
Definition: CommentSema.cpp:967
SourceLocation.h
Defines the clang::SourceLocation class and associated facilities.
clang::comments::Sema::setDecl
void setDecl(const Decl *D)
Definition: CommentSema.cpp:35
clang::comments::Sema::isRecordLikeDecl
bool isRecordLikeDecl()
Definition: CommentSema.cpp:919
clang::comments::Sema::actOnInlineCommand
InlineCommandComment * actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID)
Definition: CommentSema.cpp:363
clang::comments::ParamCommandComment
Doxygen \param command.
Definition: Comment.h:713
Text
StringRef Text
Definition: Format.cpp:1826
clang::comments::Sema::actOnParamCommandParamNameArg
void actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:256
clang::comments::Sema::resolveParamCommandIndexes
void resolveParamCommandIndexes(const FullComment *FC)
Resolve parameter names to parameter indexes in function declaration.
Definition: CommentSema.cpp:729
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition: SourceManager.h:596
clang::comments::Sema::actOnParamCommandDirectionArg
void actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:227
clang::comments::FullComment
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1093
clang::Preprocessor
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:128