clang 8.0.0

CommentSema.h
Go to the documentation of this file.
1 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file defines the semantic analysis class for Doxygen comments.
11 //
12 //===----------------------------------------------------------------------===//
13
14 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H
15 #define LLVM_CLANG_AST_COMMENTSEMA_H
16
17 #include "clang/AST/Comment.h"
18 #include "clang/Basic/Diagnostic.h"
19 #include "clang/Basic/SourceLocation.h"
20 #include "llvm/ADT/ArrayRef.h"
21 #include "llvm/ADT/StringMap.h"
22 #include "llvm/ADT/StringRef.h"
23 #include "llvm/Support/Allocator.h"
24
25 namespace clang {
26 class Decl;
27 class SourceMgr;
28 class Preprocessor;
29
30 namespace comments {
31 class CommandTraits;
32
33 class Sema {
34 Sema(const Sema &) = delete;
35 void operator=(const Sema &) = delete;
36
37 /// Allocator for AST nodes.
38 llvm::BumpPtrAllocator &Allocator;
39
40 /// Source manager for the comment being parsed.
41 const SourceManager &SourceMgr;
42
43 DiagnosticsEngine &Diags;
44
45 CommandTraits &Traits;
46
47 const Preprocessor *PP;
48
49 /// Information about the declaration this comment is attached to.
50 DeclInfo *ThisDeclInfo;
51
52 /// Comment AST nodes that correspond to parameter names in
53 /// \c TemplateParameters.
54 ///
55 /// Contains a valid value if \c DeclInfo->IsFilled is true.
56 llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
57
58 /// AST node for the \command and its aliases.
59 const BlockCommandComment *BriefCommand;
60
61 /// AST node for the \\headerfile command.
62 const BlockCommandComment *HeaderfileCommand;
63
64 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
65 return Diags.Report(Loc, DiagID);
66 }
67
68 /// A stack of HTML tags that are currently open (not matched with closing
69 /// tags).
70 SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
71
72 public:
73 Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
74 DiagnosticsEngine &Diags, CommandTraits &Traits,
75 const Preprocessor *PP);
76
77 void setDecl(const Decl *D);
78
79 /// Returns a copy of array, owned by Sema's allocator.
80 template<typename T>
81 ArrayRef<T> copyArray(ArrayRef<T> Source) {
82 if (!Source.empty())
83 return Source.copy(Allocator);
84 return None;
85 }
86
87 ParagraphComment *actOnParagraphComment(
88 ArrayRef<InlineContentComment *> Content);
89
90 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
91 SourceLocation LocEnd,
92 unsigned CommandID,
93 CommandMarkerKind CommandMarker);
94
95 void actOnBlockCommandArgs(BlockCommandComment *Command,
96 ArrayRef<BlockCommandComment::Argument> Args);
97
98 void actOnBlockCommandFinish(BlockCommandComment *Command,
99 ParagraphComment *Paragraph);
100
101 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
102 SourceLocation LocEnd,
103 unsigned CommandID,
104 CommandMarkerKind CommandMarker);
105
106 void actOnParamCommandDirectionArg(ParamCommandComment *Command,
107 SourceLocation ArgLocBegin,
108 SourceLocation ArgLocEnd,
109 StringRef Arg);
110
111 void actOnParamCommandParamNameArg(ParamCommandComment *Command,
112 SourceLocation ArgLocBegin,
113 SourceLocation ArgLocEnd,
114 StringRef Arg);
115
116 void actOnParamCommandFinish(ParamCommandComment *Command,
117 ParagraphComment *Paragraph);
118
119 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
120 SourceLocation LocEnd,
121 unsigned CommandID,
122 CommandMarkerKind CommandMarker);
123
124 void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
125 SourceLocation ArgLocBegin,
126 SourceLocation ArgLocEnd,
127 StringRef Arg);
128
129 void actOnTParamCommandFinish(TParamCommandComment *Command,
130 ParagraphComment *Paragraph);
131
132 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
133 SourceLocation CommandLocEnd,
134 unsigned CommandID);
135
136 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
137 SourceLocation CommandLocEnd,
138 unsigned CommandID,
139 SourceLocation ArgLocBegin,
140 SourceLocation ArgLocEnd,
141 StringRef Arg);
142
143 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
144 SourceLocation LocEnd,
145 StringRef CommandName);
146
147 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
148 SourceLocation LocEnd,
149 unsigned CommandID);
150
151 TextComment *actOnText(SourceLocation LocBegin,
152 SourceLocation LocEnd,
153 StringRef Text);
154
155 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
156 unsigned CommandID);
157
158 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
159 StringRef Text);
160
161 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
162 SourceLocation CloseNameLocBegin,
163 StringRef CloseName,
164 ArrayRef<VerbatimBlockLineComment *> Lines);
165
166 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
167 unsigned CommandID,
168 SourceLocation TextBegin,
169 StringRef Text);
170
171 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
172 StringRef TagName);
173
174 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
175 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
176 SourceLocation GreaterLoc,
177 bool IsSelfClosing);
178
179 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
180 SourceLocation LocEnd,
181 StringRef TagName);
182
183 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
184
185 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
186
187 void checkReturnsCommand(const BlockCommandComment *Command);
188
189 /// Emit diagnostics about duplicate block commands that should be
190 /// used only once per comment, e.g., \and \\returns.
191 void checkBlockCommandDuplicate(const BlockCommandComment *Command);
192
193 void checkDeprecatedCommand(const BlockCommandComment *Comment);
194
195 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
196
197 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
198
199 void checkContainerDecl(const BlockCommandComment *Comment);
200
201 /// Resolve parameter names to parameter indexes in function declaration.
202 /// Emit diagnostics about unknown parametrs.
203 void resolveParamCommandIndexes(const FullComment *FC);
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 /// \returns \c true if the declaration that this comment is attached to
212 /// declares a variable or a field whose type is a function or a block
213 /// pointer.
214 bool isFunctionOrBlockPointerVarLikeDecl();
215 bool isFunctionOrMethodVariadic();
216 bool isObjCMethodDecl();
217 bool isObjCPropertyDecl();
218 bool isTemplateOrSpecialization();
219 bool isRecordLikeDecl();
220 bool isClassOrStructDecl();
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 InlineCommandComment::RenderKind
251 getInlineCommandRenderKind(StringRef Name) const;
252 };
253
254 } // end namespace comments
255 } // end namespace clang
256
257 #endif
258
clang::comments::Sema::actOnParamCommandFinish
void actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:275
clang::comments::Sema::correctTypoInTParamReference
StringRef correctTypoInTParamReference(StringRef Typo, const TemplateParameterList *TemplateParameters)
Definition: CommentSema.cpp:1102
clang::comments::Sema::getParamVars
ArrayRef< const ParmVarDecl * > getParamVars()
Definition: CommentSema.cpp:962
clang::comments::Sema::isClassTemplateDecl
bool isClassTemplateDecl()
Definition: CommentSema.cpp:926
clang::comments::Sema::isFunctionTemplateDecl
bool isFunctionTemplateDecl()
Definition: CommentSema.cpp:935
clang::comments::Sema::checkBlockCommandEmptyParagraph
void checkBlockCommandEmptyParagraph(BlockCommandComment *Command)
Definition: CommentSema.cpp:563
clang::comments::Sema::actOnHTMLStartTagFinish
void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, ArrayRef< HTMLStartTagComment::Attribute > Attrs, SourceLocation GreaterLoc, bool IsSelfClosing)
Definition: CommentSema.cpp:463
clang::comments::Sema::isFunctionOrMethodVariadic
bool isFunctionOrMethodVariadic()
Definition: CommentSema.cpp:814
clang::Decl
Decl - This represents one declaration (or definition), e.g.
Definition: DeclBase.h:87
clang::comments::Sema::actOnParagraphComment
ParagraphComment * actOnParagraphComment(ArrayRef< InlineContentComment *> Content)
Definition: CommentSema.cpp:45
clang::comments::Sema::isClassOrStructDecl
bool isClassOrStructDecl()
Definition: CommentSema.cpp:916
clang::comments::Sema::actOnVerbatimBlockStart
VerbatimBlockComment * actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID)
Definition: CommentSema.cpp:420
clang::DiagnosticsEngine::Report
DiagnosticBuilder Report(SourceLocation Loc, unsigned DiagID)
Issue the message to the client.
Definition: Diagnostic.h:1295
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:1037
clang::comments::Sema::actOnHTMLStartTagStart
HTMLStartTagComment * actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName)
Definition: CommentSema.cpp:458
clang::comments::Sema::actOnBlockCommandArgs
void actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef< BlockCommandComment::Argument > Args)
Definition: CommentSema.cpp:62
clang::comments::Sema::checkContainerDeclVerbatimLine
void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:131
clang::TemplateParameterList
Stores a list of template parameters for a TemplateDecl and its derived classes.
Definition: DeclTemplate.h:68
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:625
clang::comments::Sema::actOnVerbatimBlockFinish
void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef< VerbatimBlockLineComment *> Lines)
Definition: CommentSema.cpp:434
llvm::SmallVectorImpl
Definition: LLVM.h:37
clang::comments::Sema::actOnText
TextComment * actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text)
Definition: CommentSema.cpp:414
clang::comments::InlineCommandComment
A command with word-like arguments that is considered inline content.
Definition: Comment.h:299
clang::comments::Sema
Definition: CommentSema.h:33
clang::comments::VerbatimBlockLineComment
A line of text contained in a verbatim block.
Definition: Comment.h:864
clang::comments::TextComment
Plain text.
Definition: Comment.h:263
clang::comments::VerbatimLineComment
A verbatim line command.
Definition: Comment.h:944
Comment.h
clang::comments::Sema::checkReturnsCommand
void checkReturnsCommand(const BlockCommandComment *Command)
Definition: CommentSema.cpp:581
clang::comments::Sema::isFunctionPointerVarDecl
bool isFunctionPointerVarDecl()
Definition: CommentSema.cpp:842
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:397
clang::comments::Sema::actOnFullComment
FullComment * actOnFullComment(ArrayRef< BlockContentComment *> Blocks)
Definition: CommentSema.cpp:544
clang::comments::Comment
Any part of the comment.
Definition: Comment.h:53
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:32
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:880
clang::comments::Sema::copyArray
ArrayRef< T > copyArray(ArrayRef< T > Source)
Returns a copy of array, owned by Sema&#39;s allocator.
Definition: CommentSema.h:81
clang::comments::VerbatimBlockComment
A verbatim block command (e.
Definition: Comment.h:892
clang::comments::Sema::isTemplateOrSpecialization
bool isTemplateOrSpecialization()
Definition: CommentSema.cpp:888
clang::DiagnosticBuilder
A little helper class used to produce diagnostics.
Definition: Diagnostic.h:1043
clang::comments::Sema::resolveTParamReference
bool resolveTParamReference(StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl< unsigned > *Position)
Definition: CommentSema.cpp:1075
clang::comments::Sema::isObjCMethodDecl
bool isObjCMethodDecl()
Definition: CommentSema.cpp:837
clang::comments::Sema::inspectThisDecl
void inspectThisDecl()
Extract all important semantic information from ThisDeclInfo->ThisDecl into ThisDeclInfo members...
Definition: CommentSema.cpp:968
clang::comments::Sema::actOnTParamCommandFinish
void actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:358
clang::comments::CommandMarkerKind
CommandMarkerKind
Describes the syntax that was used in a documentation command.
Definition: Comment.h:37
clang::comments::BlockCommandComment
A command that has zero or more word-like arguments (number of word-like arguments depends on command...
Definition: Comment.h:597
clang::comments::Sema::actOnVerbatimBlockLine
VerbatimBlockLineComment * actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text)
Definition: CommentSema.cpp:429
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:972
clang::comments::HTMLStartTagComment
An opening HTML tag with attributes.
Definition: Comment.h:414
clang::comments::Sema::checkFunctionDeclVerbatimLine
void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:98
clang::comments::Sema::actOnTParamCommandStart
TParamCommandComment * actOnTParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:281
clang::comments::Sema::actOnBlockCommandFinish
void actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph)
Definition: CommentSema.cpp:67
clang::comments::Sema::isFunctionDecl
bool isFunctionDecl()
Definition: CommentSema.cpp:801
clang::comments::CommandTraits
This class provides information about commands that can be used in comments.
Definition: CommentCommandTraits.h:128
clang::comments::Sema::getInlineCommandRenderKind
InlineCommandComment::RenderKind getInlineCommandRenderKind(StringRef Name) const
Definition: CommentSema.cpp:1116
clang::comments::Sema::checkDeprecatedCommand
void checkDeprecatedCommand(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:663
clang::comments::Sema::checkContainerDecl
void checkContainerDecl(const BlockCommandComment *Comment)
Definition: CommentSema.cpp:168
clang::SourceLocation
Encodes a location in the source.
Definition: SourceLocation.h:88
clang::comments::Sema::actOnVerbatimLine
VerbatimLineComment * actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text)
Definition: CommentSema.cpp:443
clang::comments::Sema::isObjCProtocolDecl
bool isObjCProtocolDecl()
Definition: CommentSema.cpp:953
clang::comments::Sema::isFunctionOrBlockPointerVarLikeDecl
bool isFunctionOrBlockPointerVarLikeDecl()
Definition: CommentSema.cpp:856
clang::comments::Sema::actOnParamCommandStart
ParamCommandComment * actOnParamCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:80
llvm::SmallVector
Definition: LLVM.h:36
clang::comments::HTMLEndTagComment
A closing HTML tag.
Definition: Comment.h:508
clang::comments::TParamCommandComment
Doxygen \tparam command, describes a template parameter.
Definition: Comment.h:800
clang
Dataflow Directional Tag Classes.
Definition: CFGReachabilityAnalysis.h:22
clang::comments::Sema::actOnBlockCommandStart
BlockCommandComment * actOnBlockCommandStart(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker)
Definition: CommentSema.cpp:50
clang::comments::DeclInfo
Information about the declaration, useful to clients of FullComment.
Definition: Comment.h:981
clang::comments::ParagraphComment
A single paragraph that contains inline content.
Definition: Comment.h:547
clang::comments::Sema::actOnHTMLEndTag
HTMLEndTagComment * actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName)
Definition: CommentSema.cpp:476
clang::comments::Sema::isAnyFunctionDecl
bool isAnyFunctionDecl()
Definition: CommentSema.cpp:809
clang::comments::Sema::isUnionDecl
bool isUnionDecl()
Definition: CommentSema.cpp:905
clang::comments::Sema::actOnTParamCommandParamNameArg
void actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:299
clang::comments::Sema::isObjCInterfaceDecl
bool isObjCInterfaceDecl()
Definition: CommentSema.cpp:944
SourceLocation.h
Defines the clang::SourceLocation class and associated facilities.
clang::comments::Sema::setDecl
void setDecl(const Decl *D)
Definition: CommentSema.cpp:36
clang::comments::Sema::isRecordLikeDecl
bool isRecordLikeDecl()
Definition: CommentSema.cpp:896
clang::comments::Sema::actOnInlineCommand
InlineCommandComment * actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID)
Definition: CommentSema.cpp:364
clang::comments::ParamCommandComment
Doxygen \param command.
Definition: Comment.h:712
Text
StringRef Text
Definition: Format.cpp:1630
clang::comments::Sema::actOnParamCommandParamNameArg
void actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:257
clang::comments::Sema::resolveParamCommandIndexes
void resolveParamCommandIndexes(const FullComment *FC)
Resolve parameter names to parameter indexes in function declaration.
Definition: CommentSema.cpp:712
clang::SourceManager
This class handles loading and caching of source files into memory.
Definition: SourceManager.h:582
clang::comments::Sema::actOnParamCommandDirectionArg
void actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg)
Definition: CommentSema.cpp:228
clang::comments::FullComment
A full comment attached to a declaration, contains block content.
Definition: Comment.h:1092
clang::Preprocessor
Engages in a tight little dance with the lexer to efficiently preprocess tokens.
Definition: Preprocessor.h:125