1 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file defines the semantic analysis class for Doxygen comments.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H
15 #define LLVM_CLANG_AST_COMMENTSEMA_H
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"
34 Sema(const Sema &) = delete;
35 void operator=(const Sema &) = delete;
37 /// Allocator for AST nodes.
38 llvm::BumpPtrAllocator &Allocator;
40 /// Source manager for the comment being parsed.
41 const SourceManager &SourceMgr;
43 DiagnosticsEngine &Diags;
45 CommandTraits &Traits;
47 const Preprocessor *PP;
49 /// Information about the declaration this comment is attached to.
50 DeclInfo *ThisDeclInfo;
52 /// Comment AST nodes that correspond to parameter names in
53 /// \c TemplateParameters.
55 /// Contains a valid value if \c DeclInfo->IsFilled is true.
56 llvm::StringMap<TParamCommandComment *> TemplateParameterDocs;
58 /// AST node for the \command and its aliases.
59 const BlockCommandComment *BriefCommand;
61 /// AST node for the \\headerfile command.
62 const BlockCommandComment *HeaderfileCommand;
64 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
65 return Diags.Report(Loc, DiagID);
68 /// A stack of HTML tags that are currently open (not matched with closing
70 SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
73 Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
74 DiagnosticsEngine &Diags, CommandTraits &Traits,
75 const Preprocessor *PP);
77 void setDecl(const Decl *D);
79 /// Returns a copy of array, owned by Sema's allocator.
81 ArrayRef<T> copyArray(ArrayRef<T> Source) {
83 return Source.copy(Allocator);
87 ParagraphComment *actOnParagraphComment(
88 ArrayRef<InlineContentComment *> Content);
90 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
91 SourceLocation LocEnd,
93 CommandMarkerKind CommandMarker);
95 void actOnBlockCommandArgs(BlockCommandComment *Command,
96 ArrayRef<BlockCommandComment::Argument> Args);
98 void actOnBlockCommandFinish(BlockCommandComment *Command,
99 ParagraphComment *Paragraph);
101 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
102 SourceLocation LocEnd,
104 CommandMarkerKind CommandMarker);
106 void actOnParamCommandDirectionArg(ParamCommandComment *Command,
107 SourceLocation ArgLocBegin,
108 SourceLocation ArgLocEnd,
111 void actOnParamCommandParamNameArg(ParamCommandComment *Command,
112 SourceLocation ArgLocBegin,
113 SourceLocation ArgLocEnd,
116 void actOnParamCommandFinish(ParamCommandComment *Command,
117 ParagraphComment *Paragraph);
119 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
120 SourceLocation LocEnd,
122 CommandMarkerKind CommandMarker);
124 void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
125 SourceLocation ArgLocBegin,
126 SourceLocation ArgLocEnd,
129 void actOnTParamCommandFinish(TParamCommandComment *Command,
130 ParagraphComment *Paragraph);
132 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
133 SourceLocation CommandLocEnd,
136 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
137 SourceLocation CommandLocEnd,
139 SourceLocation ArgLocBegin,
140 SourceLocation ArgLocEnd,
143 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
144 SourceLocation LocEnd,
145 StringRef CommandName);
147 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
148 SourceLocation LocEnd,
151 TextComment *actOnText(SourceLocation LocBegin,
152 SourceLocation LocEnd,
155 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
158 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
161 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
162 SourceLocation CloseNameLocBegin,
164 ArrayRef<VerbatimBlockLineComment *> Lines);
166 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
168 SourceLocation TextBegin,
171 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
174 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
175 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
176 SourceLocation GreaterLoc,
179 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
180 SourceLocation LocEnd,
183 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
185 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
187 void checkReturnsCommand(const BlockCommandComment *Command);
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);
193 void checkDeprecatedCommand(const BlockCommandComment *Comment);
195 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
197 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
199 void checkContainerDecl(const BlockCommandComment *Comment);
201 /// Resolve parameter names to parameter indexes in function declaration.
202 /// Emit diagnostics about unknown parametrs.
203 void resolveParamCommandIndexes(const FullComment *FC);
205 bool isFunctionDecl();
206 bool isAnyFunctionDecl();
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
214 bool isFunctionOrBlockPointerVarLikeDecl();
215 bool isFunctionOrMethodVariadic();
216 bool isObjCMethodDecl();
217 bool isObjCPropertyDecl();
218 bool isTemplateOrSpecialization();
219 bool isRecordLikeDecl();
220 bool isClassOrStructDecl();
222 bool isObjCInterfaceDecl();
223 bool isObjCProtocolDecl();
224 bool isClassTemplateDecl();
225 bool isFunctionTemplateDecl();
227 ArrayRef<const ParmVarDecl *> getParamVars();
229 /// Extract all important semantic information from
230 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
231 void inspectThisDecl();
233 /// Returns index of a function parameter with a given name.
234 unsigned resolveParmVarReference(StringRef Name,
235 ArrayRef<const ParmVarDecl *> ParamVars);
237 /// Returns index of a function parameter with the name closest to a given
239 unsigned correctTypoInParmVarReference(StringRef Typo,
240 ArrayRef<const ParmVarDecl *> ParamVars);
242 bool resolveTParamReference(StringRef Name,
243 const TemplateParameterList *TemplateParameters,
244 SmallVectorImpl<unsigned> *Position);
246 StringRef correctTypoInTParamReference(
248 const TemplateParameterList *TemplateParameters);
250 InlineCommandComment::RenderKind
251 getInlineCommandRenderKind(StringRef Name) const;
254 } // end namespace comments
255 } // end namespace clang