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