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