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/Basic/Diagnostic.h"
18 #include "clang/Basic/SourceLocation.h"
19 #include "clang/AST/Comment.h"
20 #include "llvm/ADT/ArrayRef.h"
21 #include "llvm/ADT/StringRef.h"
22 #include "llvm/ADT/StringMap.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 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,
98 void actOnBlockCommandArgs(BlockCommandComment *Command,
99 ArrayRef<BlockCommandComment::Argument> Args);
101 void actOnBlockCommandFinish(BlockCommandComment *Command,
102 ParagraphComment *Paragraph);
104 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin,
105 SourceLocation LocEnd,
108 void actOnParamCommandDirectionArg(ParamCommandComment *Command,
109 SourceLocation ArgLocBegin,
110 SourceLocation ArgLocEnd,
113 void actOnParamCommandParamNameArg(ParamCommandComment *Command,
114 SourceLocation ArgLocBegin,
115 SourceLocation ArgLocEnd,
118 void actOnParamCommandFinish(ParamCommandComment *Command,
119 ParagraphComment *Paragraph);
121 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin,
122 SourceLocation LocEnd,
125 void actOnTParamCommandParamNameArg(TParamCommandComment *Command,
126 SourceLocation ArgLocBegin,
127 SourceLocation ArgLocEnd,
130 void actOnTParamCommandFinish(TParamCommandComment *Command,
131 ParagraphComment *Paragraph);
133 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
134 SourceLocation CommandLocEnd,
137 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin,
138 SourceLocation CommandLocEnd,
140 SourceLocation ArgLocBegin,
141 SourceLocation ArgLocEnd,
144 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
145 SourceLocation LocEnd,
146 StringRef CommandName);
148 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin,
149 SourceLocation LocEnd,
152 TextComment *actOnText(SourceLocation LocBegin,
153 SourceLocation LocEnd,
156 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc,
159 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc,
162 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block,
163 SourceLocation CloseNameLocBegin,
165 ArrayRef<VerbatimBlockLineComment *> Lines);
167 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin,
169 SourceLocation TextBegin,
172 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin,
175 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag,
176 ArrayRef<HTMLStartTagComment::Attribute> Attrs,
177 SourceLocation GreaterLoc,
180 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin,
181 SourceLocation LocEnd,
184 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks);
186 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command);
188 void checkReturnsCommand(const BlockCommandComment *Command);
190 /// Emit diagnostics about duplicate block commands that should be
191 /// used only once per comment, e.g., \\brief and \\returns.
192 void checkBlockCommandDuplicate(const BlockCommandComment *Command);
194 void checkDeprecatedCommand(const BlockCommandComment *Comment);
196 /// Resolve parameter names to parameter indexes in function declaration.
197 /// Emit diagnostics about unknown parametrs.
198 void resolveParamCommandIndexes(const FullComment *FC);
200 bool isFunctionDecl();
201 bool isTemplateOrSpecialization();
203 ArrayRef<const ParmVarDecl *> getParamVars();
205 /// Extract all important semantic information from
206 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members.
207 void inspectThisDecl();
209 /// Returns index of a function parameter with a given name.
210 unsigned resolveParmVarReference(StringRef Name,
211 ArrayRef<const ParmVarDecl *> ParamVars);
213 /// Returns index of a function parameter with the name closest to a given
215 unsigned correctTypoInParmVarReference(StringRef Typo,
216 ArrayRef<const ParmVarDecl *> ParamVars);
218 bool resolveTParamReference(StringRef Name,
219 const TemplateParameterList *TemplateParameters,
220 SmallVectorImpl<unsigned> *Position);
222 StringRef correctTypoInTParamReference(
224 const TemplateParameterList *TemplateParameters);
226 InlineCommandComment::RenderKind
227 getInlineCommandRenderKind(StringRef Name) const;
230 } // end namespace comments
231 } // end namespace clang