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 \\returns command and its aliases.
62 const BlockCommandComment *ReturnsCommand;
64 /// AST node for the \\headerfile command.
65 const BlockCommandComment *HeaderfileCommand;
67 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) {
68 return Diags.Report(Loc, DiagID);
71 /// A stack of HTML tags that are currently open (not matched with closing
73 SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags;
76 Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr,
77 DiagnosticsEngine &Diags, CommandTraits &Traits,
78 const Preprocessor *PP);
80 void setDecl(const Decl *D);
82 /// Returns a copy of array, owned by Sema's allocator.
84 ArrayRef<T> copyArray(ArrayRef<T> Source) {
85 size_t Size = Source.size();
87 T *Mem = Allocator.Allocate<T>(Size);
88 std::uninitialized_copy(Source.begin(), Source.end(), Mem);
89 return llvm::makeArrayRef(Mem, Size);
91 return llvm::makeArrayRef(static_cast<T *>(NULL), 0);
94 ParagraphComment *actOnParagraphComment(
95 ArrayRef<InlineContentComment *> Content);
97 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin,
98 SourceLocation LocEnd,
100 CommandMarkerKind CommandMarker);
102 void actOnBlockCommandArgs(BlockCommandComment *Command,
103 ArrayRef<BlockCommandComment::Argument> Args);
105 void actOnBlockCommandFinish(BlockCommandComment *Command,
106 ParagraphComment *Paragraph);
108 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
109 SourceLocation LocEnd,
111 CommandMarkerKind CommandMarker);
113 void actOnParamCommandDirectionArg(ParamCommandComment *Command,
114 SourceLocation ArgLocBegin,
115 SourceLocation ArgLocEnd,
118 void actOnParamCommandParamNameArg(ParamCommandComment *Command,
119 SourceLocation ArgLocBegin,
120 SourceLocation ArgLocEnd,
123 void actOnParamCommandFinish(ParamCommandComment *Command,
124 ParagraphComment *Paragraph);
126 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
127 SourceLocation LocEnd,
129 CommandMarkerKind CommandMarker);
131 void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
132 SourceLocation ArgLocBegin,
133 SourceLocation ArgLocEnd,
136 void actOnTParamCommandFinish(TParamCommandComment *Command,
137 ParagraphComment *Paragraph);
139 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
140 SourceLocation CommandLocEnd,
143 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
144 SourceLocation CommandLocEnd,
146 SourceLocation ArgLocBegin,
147 SourceLocation ArgLocEnd,
150 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
151 SourceLocation LocEnd,
152 StringRef CommandName);
154 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
155 SourceLocation LocEnd,
158 TextComment *actOnText(SourceLocation LocBegin,
159 SourceLocation LocEnd,
162 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
165 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
168 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
169 SourceLocation CloseNameLocBegin,
171 ArrayRef<VerbatimBlockLineComment *> Lines);
173 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
175 SourceLocation TextBegin,
178 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
181 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
182 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
183 SourceLocation GreaterLoc,
186 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
187 SourceLocation LocEnd,
190 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
192 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
194 void checkReturnsCommand(const BlockCommandComment *Command);
196 /// Emit diagnostics about duplicate block commands that should be
197 /// used only once per comment, e.g., \\brief and \\returns.
198 void checkBlockCommandDuplicate(const BlockCommandComment *Command);
200 void checkDeprecatedCommand(const BlockCommandComment *Comment);
202 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
204 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
206 void checkContainerDecl(const BlockCommandComment *Comment);
208 /// Resolve parameter names to parameter indexes in function declaration.
209 /// Emit diagnostics about unknown parametrs.
210 void resolveParamCommandIndexes(const FullComment *FC);
212 bool isFunctionDecl();
213 bool isAnyFunctionDecl();
214 bool isFunctionPointerVarDecl();
215 bool isObjCMethodDecl();
216 bool isObjCPropertyDecl();
217 bool isTemplateOrSpecialization();
218 bool isRecordLikeDecl();
219 bool isClassOrStructDecl();
221 bool isObjCInterfaceDecl();
222 bool isObjCProtocolDecl();
224 ArrayRef<const ParmVarDecl *> getParamVars();
226 /// Extract all important semantic information from
227 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
228 void inspectThisDecl();
230 /// Returns index of a function parameter with a given name.
231 unsigned resolveParmVarReference(StringRef Name,
232 ArrayRef<const ParmVarDecl *> ParamVars);
234 /// Returns index of a function parameter with the name closest to a given
236 unsigned correctTypoInParmVarReference(StringRef Typo,
237 ArrayRef<const ParmVarDecl *> ParamVars);
239 bool resolveTParamReference(StringRef Name,
240 const TemplateParameterList *TemplateParameters,
241 SmallVectorImpl<unsigned> *Position);
243 StringRef correctTypoInTParamReference(
245 const TemplateParameterList *TemplateParameters);
247 InlineCommandComment::RenderKind
248 getInlineCommandRenderKind(StringRef Name) const;
251 } // end namespace comments
252 } // end namespace clang