CommentSema.h revision e4330a302ac20b41b9800267ebd4b5b01f8553f8
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_COMMENT_SEMA_H 15#define LLVM_CLANG_AST_COMMENT_SEMA_H 16 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" 24 25namespace clang { 26class Decl; 27class SourceMgr; 28 29namespace comments { 30class CommandTraits; 31 32class Sema { 33 Sema(const Sema &) LLVM_DELETED_FUNCTION; 34 void operator=(const Sema &) LLVM_DELETED_FUNCTION; 35 36 /// Allocator for AST nodes. 37 llvm::BumpPtrAllocator &Allocator; 38 39 /// Source manager for the comment being parsed. 40 const SourceManager &SourceMgr; 41 42 DiagnosticsEngine &Diags; 43 44 CommandTraits &Traits; 45 46 /// Information about the declaration this comment is attached to. 47 DeclInfo *ThisDeclInfo; 48 49 /// Comment AST nodes that correspond to parameter names in 50 /// \c TemplateParameters. 51 /// 52 /// Contains a valid value if \c DeclInfo->IsFilled is true. 53 llvm::StringMap<TParamCommandComment *> TemplateParameterDocs; 54 55 /// AST node for the \\brief command and its aliases. 56 const BlockCommandComment *BriefCommand; 57 58 /// AST node for the \\returns command and its aliases. 59 const BlockCommandComment *ReturnsCommand; 60 61 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) { 62 return Diags.Report(Loc, DiagID); 63 } 64 65 /// A stack of HTML tags that are currently open (not matched with closing 66 /// tags). 67 SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags; 68 69public: 70 Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, 71 DiagnosticsEngine &Diags, CommandTraits &Traits); 72 73 void setDecl(const Decl *D); 74 75 /// Returns a copy of array, owned by Sema's allocator. 76 template<typename T> 77 ArrayRef<T> copyArray(ArrayRef<T> Source) { 78 size_t Size = Source.size(); 79 if (Size != 0) { 80 T *Mem = Allocator.Allocate<T>(Size); 81 std::uninitialized_copy(Source.begin(), Source.end(), Mem); 82 return llvm::makeArrayRef(Mem, Size); 83 } else 84 return llvm::makeArrayRef(static_cast<T *>(NULL), 0); 85 } 86 87 ParagraphComment *actOnParagraphComment( 88 ArrayRef<InlineContentComment *> Content); 89 90 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin, 91 SourceLocation LocEnd, 92 unsigned CommandID); 93 94 void actOnBlockCommandArgs(BlockCommandComment *Command, 95 ArrayRef<BlockCommandComment::Argument> Args); 96 97 void actOnBlockCommandFinish(BlockCommandComment *Command, 98 ParagraphComment *Paragraph); 99 100 ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin, 101 SourceLocation LocEnd, 102 unsigned CommandID); 103 104 void actOnParamCommandDirectionArg(ParamCommandComment *Command, 105 SourceLocation ArgLocBegin, 106 SourceLocation ArgLocEnd, 107 StringRef Arg); 108 109 void actOnParamCommandParamNameArg(ParamCommandComment *Command, 110 SourceLocation ArgLocBegin, 111 SourceLocation ArgLocEnd, 112 StringRef Arg); 113 114 void actOnParamCommandFinish(ParamCommandComment *Command, 115 ParagraphComment *Paragraph); 116 117 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin, 118 SourceLocation LocEnd, 119 unsigned CommandID); 120 121 void actOnTParamCommandParamNameArg(TParamCommandComment *Command, 122 SourceLocation ArgLocBegin, 123 SourceLocation ArgLocEnd, 124 StringRef Arg); 125 126 void actOnTParamCommandFinish(TParamCommandComment *Command, 127 ParagraphComment *Paragraph); 128 129 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, 130 SourceLocation CommandLocEnd, 131 unsigned CommandID); 132 133 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, 134 SourceLocation CommandLocEnd, 135 unsigned CommandID, 136 SourceLocation ArgLocBegin, 137 SourceLocation ArgLocEnd, 138 StringRef Arg); 139 140 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, 141 SourceLocation LocEnd, 142 StringRef Name); 143 144 TextComment *actOnText(SourceLocation LocBegin, 145 SourceLocation LocEnd, 146 StringRef Text); 147 148 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc, 149 unsigned CommandID); 150 151 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc, 152 StringRef Text); 153 154 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, 155 SourceLocation CloseNameLocBegin, 156 StringRef CloseName, 157 ArrayRef<VerbatimBlockLineComment *> Lines); 158 159 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin, 160 unsigned CommandID, 161 SourceLocation TextBegin, 162 StringRef Text); 163 164 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin, 165 StringRef TagName); 166 167 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, 168 ArrayRef<HTMLStartTagComment::Attribute> Attrs, 169 SourceLocation GreaterLoc, 170 bool IsSelfClosing); 171 172 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin, 173 SourceLocation LocEnd, 174 StringRef TagName); 175 176 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks); 177 178 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command); 179 180 void checkReturnsCommand(const BlockCommandComment *Command); 181 182 /// Emit diagnostics about duplicate block commands that should be 183 /// used only once per comment, e.g., \\brief and \\returns. 184 void checkBlockCommandDuplicate(const BlockCommandComment *Command); 185 186 /// Resolve parameter names to parameter indexes in function declaration. 187 /// Emit diagnostics about unknown parametrs. 188 void resolveParamCommandIndexes(const FullComment *FC); 189 190 bool isFunctionDecl(); 191 bool isTemplateOrSpecialization(); 192 193 ArrayRef<const ParmVarDecl *> getParamVars(); 194 195 /// Extract all important semantic information from 196 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members. 197 void inspectThisDecl(); 198 199 /// Returns index of a function parameter with a given name. 200 unsigned resolveParmVarReference(StringRef Name, 201 ArrayRef<const ParmVarDecl *> ParamVars); 202 203 /// Returns index of a function parameter with the name closest to a given 204 /// typo. 205 unsigned correctTypoInParmVarReference(StringRef Typo, 206 ArrayRef<const ParmVarDecl *> ParamVars); 207 208 bool resolveTParamReference(StringRef Name, 209 const TemplateParameterList *TemplateParameters, 210 SmallVectorImpl<unsigned> *Position); 211 212 StringRef correctTypoInTParamReference( 213 StringRef Typo, 214 const TemplateParameterList *TemplateParameters); 215 216 InlineCommandComment::RenderKind 217 getInlineCommandRenderKind(StringRef Name) const; 218}; 219 220} // end namespace comments 221} // end namespace clang 222 223#endif 224 225