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