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_COMMENT_SEMA_H
15 #define LLVM_CLANG_AST_COMMENT_SEMA_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 &) LLVM_DELETED_FUNCTION;
35 void operator=(const Sema &) LLVM_DELETED_FUNCTION;
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 \\brief 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) {
82 size_t Size = Source.size();
84 T *Mem = Allocator.Allocate<T>(Size);
85 std::uninitialized_copy(Source.begin(), Source.end(), Mem);
86 return llvm::makeArrayRef(Mem, Size);
88 return llvm::makeArrayRef(static_cast<T *>(NULL), 0);
91 ParagraphComment *actOnParagraphComment(
92 ArrayRef<InlineContentComment *> Content);
94 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
95 SourceLocation LocEnd,
97 CommandMarkerKind CommandMarker);
99 void actOnBlockCommandArgs(BlockCommandComment *Command,
100 ArrayRef<BlockCommandComment::Argument> Args);
102 void actOnBlockCommandFinish(BlockCommandComment *Command,
103 ParagraphComment *Paragraph);
105 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
106 SourceLocation LocEnd,
108 CommandMarkerKind CommandMarker);
110 void actOnParamCommandDirectionArg(ParamCommandComment *Command,
111 SourceLocation ArgLocBegin,
112 SourceLocation ArgLocEnd,
115 void actOnParamCommandParamNameArg(ParamCommandComment *Command,
116 SourceLocation ArgLocBegin,
117 SourceLocation ArgLocEnd,
120 void actOnParamCommandFinish(ParamCommandComment *Command,
121 ParagraphComment *Paragraph);
123 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
124 SourceLocation LocEnd,
126 CommandMarkerKind CommandMarker);
128 void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
129 SourceLocation ArgLocBegin,
130 SourceLocation ArgLocEnd,
133 void actOnTParamCommandFinish(TParamCommandComment *Command,
134 ParagraphComment *Paragraph);
136 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
137 SourceLocation CommandLocEnd,
140 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
141 SourceLocation CommandLocEnd,
143 SourceLocation ArgLocBegin,
144 SourceLocation ArgLocEnd,
147 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
148 SourceLocation LocEnd,
149 StringRef CommandName);
151 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
152 SourceLocation LocEnd,
155 TextComment *actOnText(SourceLocation LocBegin,
156 SourceLocation LocEnd,
159 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
162 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
165 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
166 SourceLocation CloseNameLocBegin,
168 ArrayRef<VerbatimBlockLineComment *> Lines);
170 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
172 SourceLocation TextBegin,
175 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
178 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
179 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
180 SourceLocation GreaterLoc,
183 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
184 SourceLocation LocEnd,
187 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
189 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
191 void checkReturnsCommand(const BlockCommandComment *Command);
193 /// Emit diagnostics about duplicate block commands that should be
194 /// used only once per comment, e.g., \\brief and \\returns.
195 void checkBlockCommandDuplicate(const BlockCommandComment *Command);
197 void checkDeprecatedCommand(const BlockCommandComment *Comment);
199 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
201 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
203 void checkContainerDecl(const BlockCommandComment *Comment);
205 /// Resolve parameter names to parameter indexes in function declaration.
206 /// Emit diagnostics about unknown parametrs.
207 void resolveParamCommandIndexes(const FullComment *FC);
209 bool isFunctionDecl();
210 bool isAnyFunctionDecl();
212 /// \returns \c true if declaration that this comment is attached to declares
213 /// a function pointer.
214 bool isFunctionPointerVarDecl();
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