1239313Sdim//===--- CommentSema.h - Doxygen comment semantic analysis ------*- C++ -*-===// 2239313Sdim// 3239313Sdim// The LLVM Compiler Infrastructure 4239313Sdim// 5239313Sdim// This file is distributed under the University of Illinois Open Source 6239313Sdim// License. See LICENSE.TXT for details. 7239313Sdim// 8239313Sdim//===----------------------------------------------------------------------===// 9239313Sdim// 10239313Sdim// This file defines the semantic analysis class for Doxygen comments. 11239313Sdim// 12239313Sdim//===----------------------------------------------------------------------===// 13239313Sdim 14239313Sdim#ifndef LLVM_CLANG_AST_COMMENT_SEMA_H 15239313Sdim#define LLVM_CLANG_AST_COMMENT_SEMA_H 16239313Sdim 17249423Sdim#include "clang/AST/Comment.h" 18239313Sdim#include "clang/Basic/Diagnostic.h" 19239313Sdim#include "clang/Basic/SourceLocation.h" 20239313Sdim#include "llvm/ADT/ArrayRef.h" 21249423Sdim#include "llvm/ADT/StringMap.h" 22239313Sdim#include "llvm/ADT/StringRef.h" 23239313Sdim#include "llvm/Support/Allocator.h" 24239313Sdim 25239313Sdimnamespace clang { 26239313Sdimclass Decl; 27239313Sdimclass SourceMgr; 28243830Sdimclass Preprocessor; 29239313Sdim 30239313Sdimnamespace comments { 31239313Sdimclass CommandTraits; 32239313Sdim 33239313Sdimclass Sema { 34243830Sdim Sema(const Sema &) LLVM_DELETED_FUNCTION; 35243830Sdim void operator=(const Sema &) LLVM_DELETED_FUNCTION; 36239313Sdim 37239313Sdim /// Allocator for AST nodes. 38239313Sdim llvm::BumpPtrAllocator &Allocator; 39239313Sdim 40239313Sdim /// Source manager for the comment being parsed. 41239313Sdim const SourceManager &SourceMgr; 42239313Sdim 43239313Sdim DiagnosticsEngine &Diags; 44239313Sdim 45243830Sdim CommandTraits &Traits; 46239313Sdim 47243830Sdim const Preprocessor *PP; 48243830Sdim 49239313Sdim /// Information about the declaration this comment is attached to. 50239313Sdim DeclInfo *ThisDeclInfo; 51239313Sdim 52239313Sdim /// Comment AST nodes that correspond to parameter names in 53239313Sdim /// \c TemplateParameters. 54239313Sdim /// 55239313Sdim /// Contains a valid value if \c DeclInfo->IsFilled is true. 56239313Sdim llvm::StringMap<TParamCommandComment *> TemplateParameterDocs; 57239313Sdim 58239313Sdim /// AST node for the \\brief command and its aliases. 59239313Sdim const BlockCommandComment *BriefCommand; 60239313Sdim 61249423Sdim /// AST node for the \\headerfile command. 62249423Sdim const BlockCommandComment *HeaderfileCommand; 63239313Sdim 64239313Sdim DiagnosticBuilder Diag(SourceLocation Loc, unsigned DiagID) { 65239313Sdim return Diags.Report(Loc, DiagID); 66239313Sdim } 67239313Sdim 68239313Sdim /// A stack of HTML tags that are currently open (not matched with closing 69239313Sdim /// tags). 70239313Sdim SmallVector<HTMLStartTagComment *, 8> HTMLOpenTags; 71239313Sdim 72239313Sdimpublic: 73239313Sdim Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, 74243830Sdim DiagnosticsEngine &Diags, CommandTraits &Traits, 75243830Sdim const Preprocessor *PP); 76239313Sdim 77239313Sdim void setDecl(const Decl *D); 78239313Sdim 79239313Sdim /// Returns a copy of array, owned by Sema's allocator. 80239313Sdim template<typename T> 81239313Sdim ArrayRef<T> copyArray(ArrayRef<T> Source) { 82239313Sdim size_t Size = Source.size(); 83239313Sdim if (Size != 0) { 84239313Sdim T *Mem = Allocator.Allocate<T>(Size); 85239313Sdim std::uninitialized_copy(Source.begin(), Source.end(), Mem); 86239313Sdim return llvm::makeArrayRef(Mem, Size); 87239313Sdim } else 88239313Sdim return llvm::makeArrayRef(static_cast<T *>(NULL), 0); 89239313Sdim } 90239313Sdim 91239313Sdim ParagraphComment *actOnParagraphComment( 92239313Sdim ArrayRef<InlineContentComment *> Content); 93239313Sdim 94239313Sdim BlockCommandComment *actOnBlockCommandStart(SourceLocation LocBegin, 95239313Sdim SourceLocation LocEnd, 96249423Sdim unsigned CommandID, 97249423Sdim CommandMarkerKind CommandMarker); 98239313Sdim 99239313Sdim void actOnBlockCommandArgs(BlockCommandComment *Command, 100239313Sdim ArrayRef<BlockCommandComment::Argument> Args); 101239313Sdim 102239313Sdim void actOnBlockCommandFinish(BlockCommandComment *Command, 103239313Sdim ParagraphComment *Paragraph); 104239313Sdim 105239313Sdim ParamCommandComment *actOnParamCommandStart(SourceLocation LocBegin, 106239313Sdim SourceLocation LocEnd, 107249423Sdim unsigned CommandID, 108249423Sdim CommandMarkerKind CommandMarker); 109239313Sdim 110239313Sdim void actOnParamCommandDirectionArg(ParamCommandComment *Command, 111239313Sdim SourceLocation ArgLocBegin, 112239313Sdim SourceLocation ArgLocEnd, 113239313Sdim StringRef Arg); 114239313Sdim 115239313Sdim void actOnParamCommandParamNameArg(ParamCommandComment *Command, 116239313Sdim SourceLocation ArgLocBegin, 117239313Sdim SourceLocation ArgLocEnd, 118239313Sdim StringRef Arg); 119239313Sdim 120239313Sdim void actOnParamCommandFinish(ParamCommandComment *Command, 121239313Sdim ParagraphComment *Paragraph); 122239313Sdim 123239313Sdim TParamCommandComment *actOnTParamCommandStart(SourceLocation LocBegin, 124239313Sdim SourceLocation LocEnd, 125249423Sdim unsigned CommandID, 126249423Sdim CommandMarkerKind CommandMarker); 127239313Sdim 128239313Sdim void actOnTParamCommandParamNameArg(TParamCommandComment *Command, 129239313Sdim SourceLocation ArgLocBegin, 130239313Sdim SourceLocation ArgLocEnd, 131239313Sdim StringRef Arg); 132239313Sdim 133239313Sdim void actOnTParamCommandFinish(TParamCommandComment *Command, 134239313Sdim ParagraphComment *Paragraph); 135239313Sdim 136239313Sdim InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, 137239313Sdim SourceLocation CommandLocEnd, 138243830Sdim unsigned CommandID); 139239313Sdim 140239313Sdim InlineCommandComment *actOnInlineCommand(SourceLocation CommandLocBegin, 141239313Sdim SourceLocation CommandLocEnd, 142243830Sdim unsigned CommandID, 143239313Sdim SourceLocation ArgLocBegin, 144239313Sdim SourceLocation ArgLocEnd, 145239313Sdim StringRef Arg); 146239313Sdim 147239313Sdim InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, 148239313Sdim SourceLocation LocEnd, 149243830Sdim StringRef CommandName); 150239313Sdim 151243830Sdim InlineContentComment *actOnUnknownCommand(SourceLocation LocBegin, 152243830Sdim SourceLocation LocEnd, 153243830Sdim unsigned CommandID); 154243830Sdim 155239313Sdim TextComment *actOnText(SourceLocation LocBegin, 156239313Sdim SourceLocation LocEnd, 157239313Sdim StringRef Text); 158239313Sdim 159239313Sdim VerbatimBlockComment *actOnVerbatimBlockStart(SourceLocation Loc, 160243830Sdim unsigned CommandID); 161239313Sdim 162239313Sdim VerbatimBlockLineComment *actOnVerbatimBlockLine(SourceLocation Loc, 163239313Sdim StringRef Text); 164239313Sdim 165239313Sdim void actOnVerbatimBlockFinish(VerbatimBlockComment *Block, 166239313Sdim SourceLocation CloseNameLocBegin, 167239313Sdim StringRef CloseName, 168239313Sdim ArrayRef<VerbatimBlockLineComment *> Lines); 169239313Sdim 170239313Sdim VerbatimLineComment *actOnVerbatimLine(SourceLocation LocBegin, 171243830Sdim unsigned CommandID, 172239313Sdim SourceLocation TextBegin, 173239313Sdim StringRef Text); 174239313Sdim 175239313Sdim HTMLStartTagComment *actOnHTMLStartTagStart(SourceLocation LocBegin, 176239313Sdim StringRef TagName); 177239313Sdim 178239313Sdim void actOnHTMLStartTagFinish(HTMLStartTagComment *Tag, 179239313Sdim ArrayRef<HTMLStartTagComment::Attribute> Attrs, 180239313Sdim SourceLocation GreaterLoc, 181239313Sdim bool IsSelfClosing); 182239313Sdim 183239313Sdim HTMLEndTagComment *actOnHTMLEndTag(SourceLocation LocBegin, 184239313Sdim SourceLocation LocEnd, 185239313Sdim StringRef TagName); 186239313Sdim 187239313Sdim FullComment *actOnFullComment(ArrayRef<BlockContentComment *> Blocks); 188239313Sdim 189239313Sdim void checkBlockCommandEmptyParagraph(BlockCommandComment *Command); 190239313Sdim 191239313Sdim void checkReturnsCommand(const BlockCommandComment *Command); 192239313Sdim 193239313Sdim /// Emit diagnostics about duplicate block commands that should be 194239313Sdim /// used only once per comment, e.g., \\brief and \\returns. 195239313Sdim void checkBlockCommandDuplicate(const BlockCommandComment *Command); 196239313Sdim 197243830Sdim void checkDeprecatedCommand(const BlockCommandComment *Comment); 198249423Sdim 199249423Sdim void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment); 200249423Sdim 201249423Sdim void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment); 202249423Sdim 203249423Sdim void checkContainerDecl(const BlockCommandComment *Comment); 204243830Sdim 205243830Sdim /// Resolve parameter names to parameter indexes in function declaration. 206243830Sdim /// Emit diagnostics about unknown parametrs. 207243830Sdim void resolveParamCommandIndexes(const FullComment *FC); 208243830Sdim 209239313Sdim bool isFunctionDecl(); 210249423Sdim bool isAnyFunctionDecl(); 211263508Sdim 212263508Sdim /// \returns \c true if declaration that this comment is attached to declares 213263508Sdim /// a function pointer. 214249423Sdim bool isFunctionPointerVarDecl(); 215263508Sdim bool isFunctionOrMethodVariadic(); 216249423Sdim bool isObjCMethodDecl(); 217249423Sdim bool isObjCPropertyDecl(); 218239313Sdim bool isTemplateOrSpecialization(); 219249423Sdim bool isRecordLikeDecl(); 220249423Sdim bool isClassOrStructDecl(); 221249423Sdim bool isUnionDecl(); 222249423Sdim bool isObjCInterfaceDecl(); 223249423Sdim bool isObjCProtocolDecl(); 224263508Sdim bool isClassTemplateDecl(); 225263508Sdim bool isFunctionTemplateDecl(); 226239313Sdim 227239313Sdim ArrayRef<const ParmVarDecl *> getParamVars(); 228239313Sdim 229239313Sdim /// Extract all important semantic information from 230239313Sdim /// \c ThisDeclInfo->ThisDecl into \c ThisDeclInfo members. 231239313Sdim void inspectThisDecl(); 232239313Sdim 233239313Sdim /// Returns index of a function parameter with a given name. 234239313Sdim unsigned resolveParmVarReference(StringRef Name, 235239313Sdim ArrayRef<const ParmVarDecl *> ParamVars); 236239313Sdim 237239313Sdim /// Returns index of a function parameter with the name closest to a given 238239313Sdim /// typo. 239239313Sdim unsigned correctTypoInParmVarReference(StringRef Typo, 240239313Sdim ArrayRef<const ParmVarDecl *> ParamVars); 241239313Sdim 242239313Sdim bool resolveTParamReference(StringRef Name, 243239313Sdim const TemplateParameterList *TemplateParameters, 244239313Sdim SmallVectorImpl<unsigned> *Position); 245239313Sdim 246239313Sdim StringRef correctTypoInTParamReference( 247239313Sdim StringRef Typo, 248239313Sdim const TemplateParameterList *TemplateParameters); 249239313Sdim 250239313Sdim InlineCommandComment::RenderKind 251239313Sdim getInlineCommandRenderKind(StringRef Name) const; 252239313Sdim}; 253239313Sdim 254239313Sdim} // end namespace comments 255239313Sdim} // end namespace clang 256239313Sdim 257239313Sdim#endif 258239313Sdim 259