1 //===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // This file defines the semantic analysis class for Doxygen comments. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef LLVM_CLANG_AST_COMMENTSEMA_H 14 #define LLVM_CLANG_AST_COMMENTSEMA_H 15 16 #include "clang/AST/Comment.h" 17 #include "clang/Basic/Diagnostic.h" 18 #include "clang/Basic/SourceLocation.h" 19 #include "llvm/ADT/ArrayRef.h" 20 #include "llvm/ADT/StringMap.h" 21 #include "llvm/ADT/StringRef.h" 22 #include "llvm/Support/Allocator.h" 23 24 namespace clang { 25 class Decl; 26 class SourceMgr; 27 class Preprocessor; 28 29 namespace comments { 30 class CommandTraits; 31 32 class Sema { 33 Sema(const Sema &) = delete; 34 void operator=(const Sema &) = delete; 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 const Preprocessor *PP; 47 48 /// Information about the declaration this comment is attached to. 49 DeclInfo *ThisDeclInfo; 50 51 /// Comment AST nodes that correspond to parameter names in 52 /// \c TemplateParameters. 53 /// 54 /// Contains a valid value if \c DeclInfo->IsFilled is true. 55 llvm::StringMap<TParamCommandComment *> TemplateParameterDocs; 56 57 /// AST node for the \command and its aliases. 58 const BlockCommandComment *BriefCommand; 59 60 /// AST node for the \\headerfile command. 61 const BlockCommandComment *HeaderfileCommand; 62 63 DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) { 64 return Diags.Report(Loc, DiagID); 65 } 66 67 /// A stack of HTML tags that are currently open (not matched with closing 68 /// tags). 69 SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags; 70 71 public: 72 Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, 73 DiagnosticsEngine &Diags, CommandTraits &Traits, 74 const Preprocessor *PP); 75 76 void setDecl(const Decl *D); 77 78 /// Returns a copy of array, owned by Sema's allocator. 79 template<typename T> 80 ArrayRef<T> copyArray(ArrayRef<T> Source) { 81 if (!Source.empty()) 82 return Source.copy(Allocator); 83 return None; 84 } 85 86 ParagraphComment *actOnParagraphComment( 87 ArrayRef<InlineContentComment *> Content); 88 89 BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin, 90 SourceLocation LocEnd, 91 unsigned CommandID, 92 CommandMarkerKind CommandMarker); 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 CommandMarkerKind CommandMarker); 104 105 void actOnParamCommandDirectionArg(ParamCommandComment *Command, 106 SourceLocation ArgLocBegin, 107 SourceLocation ArgLocEnd, 108 StringRef Arg); 109 110 void actOnParamCommandParamNameArg(ParamCommandComment *Command, 111 SourceLocation ArgLocBegin, 112 SourceLocation ArgLocEnd, 113 StringRef Arg); 114 115 void actOnParamCommandFinish(ParamCommandComment *Command, 116 ParagraphComment *Paragraph); 117 118 TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin, 119 SourceLocation LocEnd, 120 unsigned CommandID, 121 CommandMarkerKind CommandMarker); 122 123 void actOnTParamCommandParamNameArg(TParamCommandComment *Command, 124 SourceLocation ArgLocBegin, 125 SourceLocation ArgLocEnd, 126 StringRef Arg); 127 128 void actOnTParamCommandFinish(TParamCommandComment *Command, 129 ParagraphComment *Paragraph); 130 131 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, 132 SourceLocation CommandLocEnd, 133 unsigned CommandID); 134 135 InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, 136 SourceLocation CommandLocEnd, 137 unsigned CommandID, 138 SourceLocation ArgLocBegin, 139 SourceLocation ArgLocEnd, 140 StringRef Arg); 141 142 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, 143 SourceLocation LocEnd, 144 StringRef CommandName); 145 146 InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, 147 SourceLocation LocEnd, 148 unsigned CommandID); 149 150 TextComment *actOnText(SourceLocation LocBegin, 151 SourceLocation LocEnd, 152 StringRef Text); 153 154 VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc, 155 unsigned CommandID); 156 157 VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc, 158 StringRef Text); 159 160 void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, 161 SourceLocation CloseNameLocBegin, 162 StringRef CloseName, 163 ArrayRef<VerbatimBlockLineComment *> Lines); 164 165 VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin, 166 unsigned CommandID, 167 SourceLocation TextBegin, 168 StringRef Text); 169 170 HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin, 171 StringRef TagName); 172 173 void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, 174 ArrayRef<HTMLStartTagComment::Attribute> Attrs, 175 SourceLocation GreaterLoc, 176 bool IsSelfClosing); 177 178 HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin, 179 SourceLocation LocEnd, 180 StringRef TagName); 181 182 FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks); 183 184 void checkBlockCommandEmptyParagraph(BlockCommandComment *Command); 185 186 void checkReturnsCommand(const BlockCommandComment *Command); 187 188 /// Emit diagnostics about duplicate block commands that should be 189 /// used only once per comment, e.g., \and \\returns. 190 void checkBlockCommandDuplicate(const BlockCommandComment *Command); 191 192 void checkDeprecatedCommand(const BlockCommandComment *Comment); 193 194 void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment); 195 196 void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment); 197 198 void checkContainerDecl(const BlockCommandComment *Comment); 199 200 /// Resolve parameter names to parameter indexes in function declaration. 201 /// Emit diagnostics about unknown parametrs. 202 void resolveParamCommandIndexes(const FullComment *FC); 203 204 bool isFunctionDecl(); 205 bool isAnyFunctionDecl(); 206 207 /// \returns \c true if declaration that this comment is attached to declares 208 /// a function pointer. 209 bool isFunctionPointerVarDecl(); 210 /// \returns \c true if the declaration that this comment is attached to 211 /// declares a variable or a field whose type is a function or a block 212 /// pointer. 213 bool isFunctionOrBlockPointerVarLikeDecl(); 214 bool isFunctionOrMethodVariadic(); 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 bool isClassTemplateDecl(); 224 bool isFunctionTemplateDecl(); 225 226 ArrayRef<const ParmVarDecl *> getParamVars(); 227 228 /// Extract all important semantic information from 229 /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members. 230 void inspectThisDecl(); 231 232 /// Returns index of a function parameter with a given name. 233 unsigned resolveParmVarReference(StringRef Name, 234 ArrayRef<const ParmVarDecl *> ParamVars); 235 236 /// Returns index of a function parameter with the name closest to a given 237 /// typo. 238 unsigned correctTypoInParmVarReference(StringRef Typo, 239 ArrayRef<const ParmVarDecl *> ParamVars); 240 241 bool resolveTParamReference(StringRef Name, 242 const TemplateParameterList *TemplateParameters, 243 SmallVectorImpl<unsigned> *Position); 244 245 StringRef correctTypoInTParamReference( 246 StringRef Typo, 247 const TemplateParameterList *TemplateParameters); 248 249 InlineCommandComment::RenderKind 250 getInlineCommandRenderKind(StringRef Name) const; 251 }; 252 253 } // end namespace comments 254 } // end namespace clang 255 256 #endif 257 258