head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC4:1.1.1.8 netbsd-11-0-RC3:1.1.1.8 netbsd-11-0-RC2:1.1.1.8 netbsd-11-0-RC1:1.1.1.8 perseant-exfatfs-base-20250801:1.1.1.8 netbsd-11:1.1.1.8.0.10 netbsd-11-base:1.1.1.8 netbsd-10-1-RELEASE:1.1.1.8 perseant-exfatfs-base-20240630:1.1.1.8 perseant-exfatfs:1.1.1.8.0.8 perseant-exfatfs-base:1.1.1.8 netbsd-8-3-RELEASE:1.1.1.5 netbsd-9-4-RELEASE:1.1.1.7 netbsd-10-0-RELEASE:1.1.1.8 netbsd-10-0-RC6:1.1.1.8 netbsd-10-0-RC5:1.1.1.8 netbsd-10-0-RC4:1.1.1.8 netbsd-10-0-RC3:1.1.1.8 netbsd-10-0-RC2:1.1.1.8 netbsd-10-0-RC1:1.1.1.8 netbsd-10:1.1.1.8.0.6 netbsd-10-base:1.1.1.8 netbsd-9-3-RELEASE:1.1.1.7 cjep_sun2x:1.1.1.8.0.4 cjep_sun2x-base:1.1.1.8 cjep_staticlib_x-base1:1.1.1.8 netbsd-9-2-RELEASE:1.1.1.7 cjep_staticlib_x:1.1.1.8.0.2 cjep_staticlib_x-base:1.1.1.8 netbsd-9-1-RELEASE:1.1.1.7 phil-wifi-20200421:1.1.1.8 phil-wifi-20200411:1.1.1.8 phil-wifi-20200406:1.1.1.8 netbsd-8-2-RELEASE:1.1.1.5 netbsd-9-0-RELEASE:1.1.1.7 netbsd-9-0-RC2:1.1.1.7 netbsd-9-0-RC1:1.1.1.7 netbsd-9:1.1.1.7.0.2 netbsd-9-base:1.1.1.7 phil-wifi-20190609:1.1.1.7 netbsd-8-1-RELEASE:1.1.1.5 netbsd-8-1-RC1:1.1.1.5 pgoyette-compat-merge-20190127:1.1.1.6.2.1 pgoyette-compat-20190127:1.1.1.7 pgoyette-compat-20190118:1.1.1.7 pgoyette-compat-1226:1.1.1.7 pgoyette-compat-1126:1.1.1.7 pgoyette-compat-1020:1.1.1.7 pgoyette-compat-0930:1.1.1.7 pgoyette-compat-0906:1.1.1.7 netbsd-7-2-RELEASE:1.1.1.4 pgoyette-compat-0728:1.1.1.7 clang-337282:1.1.1.7 netbsd-8-0-RELEASE:1.1.1.5 phil-wifi:1.1.1.6.0.4 phil-wifi-base:1.1.1.6 pgoyette-compat-0625:1.1.1.6 netbsd-8-0-RC2:1.1.1.5 pgoyette-compat-0521:1.1.1.6 pgoyette-compat-0502:1.1.1.6 pgoyette-compat-0422:1.1.1.6 netbsd-8-0-RC1:1.1.1.5 pgoyette-compat-0415:1.1.1.6 pgoyette-compat-0407:1.1.1.6 pgoyette-compat-0330:1.1.1.6 pgoyette-compat-0322:1.1.1.6 pgoyette-compat-0315:1.1.1.6 netbsd-7-1-2-RELEASE:1.1.1.4 pgoyette-compat:1.1.1.6.0.2 pgoyette-compat-base:1.1.1.6 netbsd-7-1-1-RELEASE:1.1.1.4 clang-319952:1.1.1.6 matt-nb8-mediatek:1.1.1.5.0.10 matt-nb8-mediatek-base:1.1.1.5 clang-309604:1.1.1.6 perseant-stdc-iso10646:1.1.1.5.0.8 perseant-stdc-iso10646-base:1.1.1.5 netbsd-8:1.1.1.5.0.6 netbsd-8-base:1.1.1.5 prg-localcount2-base3:1.1.1.5 prg-localcount2-base2:1.1.1.5 prg-localcount2-base1:1.1.1.5 prg-localcount2:1.1.1.5.0.4 prg-localcount2-base:1.1.1.5 pgoyette-localcount-20170426:1.1.1.5 bouyer-socketcan-base1:1.1.1.5 pgoyette-localcount-20170320:1.1.1.5 netbsd-7-1:1.1.1.4.0.12 netbsd-7-1-RELEASE:1.1.1.4 netbsd-7-1-RC2:1.1.1.4 clang-294123:1.1.1.5 netbsd-7-nhusb-base-20170116:1.1.1.4 bouyer-socketcan:1.1.1.5.0.2 bouyer-socketcan-base:1.1.1.5 clang-291444:1.1.1.5 pgoyette-localcount-20170107:1.1.1.4 netbsd-7-1-RC1:1.1.1.4 pgoyette-localcount-20161104:1.1.1.4 netbsd-7-0-2-RELEASE:1.1.1.4 localcount-20160914:1.1.1.4 netbsd-7-nhusb:1.1.1.4.0.10 netbsd-7-nhusb-base:1.1.1.4 clang-280599:1.1.1.4 pgoyette-localcount-20160806:1.1.1.4 pgoyette-localcount-20160726:1.1.1.4 pgoyette-localcount:1.1.1.4.0.8 pgoyette-localcount-base:1.1.1.4 netbsd-7-0-1-RELEASE:1.1.1.4 clang-261930:1.1.1.4 netbsd-7-0:1.1.1.4.0.6 netbsd-7-0-RELEASE:1.1.1.4 netbsd-7-0-RC3:1.1.1.4 netbsd-7-0-RC2:1.1.1.4 netbsd-7-0-RC1:1.1.1.4 clang-237755:1.1.1.4 clang-232565:1.1.1.4 clang-227398:1.1.1.4 tls-maxphys-base:1.1.1.4 tls-maxphys:1.1.1.4.0.4 netbsd-7:1.1.1.4.0.2 netbsd-7-base:1.1.1.4 clang-215315:1.1.1.4 clang-209886:1.1.1.4 yamt-pagecache:1.1.1.3.0.4 yamt-pagecache-base9:1.1.1.3 tls-earlyentropy:1.1.1.3.0.2 tls-earlyentropy-base:1.1.1.4 riastradh-xf86-video-intel-2-7-1-pre-2-21-15:1.1.1.3 riastradh-drm2-base3:1.1.1.3 clang-202566:1.1.1.3 clang-201163:1.1.1.3 clang-199312:1.1.1.2 clang-198450:1.1.1.2 clang-196603:1.1.1.1 clang-195771:1.1.1.1 LLVM:1.1.1; locks; strict; comment @// @; 1.1 date 2013.11.28.14.14.51; author joerg; state Exp; branches 1.1.1.1; next ; commitid ow8OybrawrB1f3fx; 1.1.1.1 date 2013.11.28.14.14.51; author joerg; state Exp; branches; next 1.1.1.2; commitid ow8OybrawrB1f3fx; 1.1.1.2 date 2014.01.05.15.39.12; author joerg; state Exp; branches; next 1.1.1.3; commitid wh3aCSIWykURqWjx; 1.1.1.3 date 2014.02.14.20.07.21; author joerg; state Exp; branches 1.1.1.3.2.1 1.1.1.3.4.1; next 1.1.1.4; commitid annVkZ1sc17rF6px; 1.1.1.4 date 2014.05.30.18.14.39; author joerg; state Exp; branches 1.1.1.4.4.1 1.1.1.4.8.1; next 1.1.1.5; commitid 8q0kdlBlCn09GACx; 1.1.1.5 date 2017.01.11.10.34.31; author joerg; state Exp; branches; next 1.1.1.6; commitid CNnUNfII1jgNmxBz; 1.1.1.6 date 2017.08.01.19.34.51; author joerg; state Exp; branches 1.1.1.6.2.1 1.1.1.6.4.1; next 1.1.1.7; commitid pMuDy65V0VicSx1A; 1.1.1.7 date 2018.07.17.18.31.11; author joerg; state Exp; branches; next 1.1.1.8; commitid wDzL46ALjrCZgwKA; 1.1.1.8 date 2019.11.13.22.19.19; author joerg; state dead; branches; next ; commitid QD8YATxuNG34YJKB; 1.1.1.3.2.1 date 2014.08.10.07.08.06; author tls; state Exp; branches; next ; commitid t01A1TLTYxkpGMLx; 1.1.1.3.4.1 date 2014.02.14.20.07.21; author yamt; state dead; branches; next 1.1.1.3.4.2; commitid WSrDtL5nYAUyiyBx; 1.1.1.3.4.2 date 2014.05.22.16.18.25; author yamt; state Exp; branches; next ; commitid WSrDtL5nYAUyiyBx; 1.1.1.4.4.1 date 2014.05.30.18.14.39; author tls; state dead; branches; next 1.1.1.4.4.2; commitid jTnpym9Qu0o4R1Nx; 1.1.1.4.4.2 date 2014.08.19.23.47.25; author tls; state Exp; branches; next ; commitid jTnpym9Qu0o4R1Nx; 1.1.1.4.8.1 date 2017.03.20.06.52.35; author pgoyette; state Exp; branches; next ; commitid jjw7cAwgyKq7RfKz; 1.1.1.6.2.1 date 2018.07.28.04.33.15; author pgoyette; state Exp; branches; next ; commitid 1UP1xAIUxv1ZgRLA; 1.1.1.6.4.1 date 2019.06.10.21.45.19; author christos; state Exp; branches; next 1.1.1.6.4.2; commitid jtc8rnCzWiEEHGqB; 1.1.1.6.4.2 date 2020.04.13.07.46.30; author martin; state dead; branches; next ; commitid X01YhRUPVUDaec4C; desc @@ 1.1 log @Initial revision @ text @//===--- CommentSema.cpp - Doxygen comment semantic analysis --------------===// // // The LLVM Compiler Infrastructure // // This file is distributed under the University of Illinois Open Source // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// #include "clang/AST/CommentSema.h" #include "clang/AST/Attr.h" #include "clang/AST/CommentCommandTraits.h" #include "clang/AST/CommentDiagnostic.h" #include "clang/AST/Decl.h" #include "clang/AST/DeclTemplate.h" #include "clang/Basic/SourceManager.h" #include "clang/Lex/Preprocessor.h" #include "llvm/ADT/SmallString.h" #include "llvm/ADT/StringSwitch.h" namespace clang { namespace comments { namespace { #include "clang/AST/CommentHTMLTagsProperties.inc" } // unnamed namespace Sema::Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, DiagnosticsEngine &Diags, CommandTraits &Traits, const Preprocessor *PP) : Allocator(Allocator), SourceMgr(SourceMgr), Diags(Diags), Traits(Traits), PP(PP), ThisDeclInfo(NULL), BriefCommand(NULL), HeaderfileCommand(NULL) { } void Sema::setDecl(const Decl *D) { if (!D) return; ThisDeclInfo = new (Allocator) DeclInfo; ThisDeclInfo->CommentDecl = D; ThisDeclInfo->IsFilled = false; } ParagraphComment *Sema::actOnParagraphComment( ArrayRef Content) { return new (Allocator) ParagraphComment(Content); } BlockCommandComment *Sema::actOnBlockCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { BlockCommandComment *BC = new (Allocator) BlockCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); checkContainerDecl(BC); return BC; } void Sema::actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef Args) { Command->setArgs(Args); } void Sema::actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); checkBlockCommandDuplicate(Command); checkReturnsCommand(Command); checkDeprecatedCommand(Command); } ParamCommandComment *Sema::actOnParamCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { ParamCommandComment *Command = new (Allocator) ParamCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); if (!isFunctionDecl()) Diag(Command->getLocation(), diag::warn_doc_param_not_attached_to_a_function_decl) << CommandMarker << Command->getCommandNameRange(Traits); return Command; } void Sema::checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsFunctionDeclarationCommand) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_function: DiagSelect = (!isAnyFunctionDecl() && !isFunctionTemplateDecl())? 1 : 0; break; case CommandTraits::KCI_functiongroup: DiagSelect = (!isAnyFunctionDecl() && !isFunctionTemplateDecl())? 2 : 0; break; case CommandTraits::KCI_method: DiagSelect = !isObjCMethodDecl() ? 3 : 0; break; case CommandTraits::KCI_methodgroup: DiagSelect = !isObjCMethodDecl() ? 4 : 0; break; case CommandTraits::KCI_callback: DiagSelect = !isFunctionPointerVarDecl() ? 5 : 0; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_function_method_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << (DiagSelect-1) << Comment->getSourceRange(); } void Sema::checkContainerDeclVerbatimLine(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsRecordLikeDeclarationCommand) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_class: DiagSelect = (!isClassOrStructDecl() && !isClassTemplateDecl()) ? 1 : 0; // Allow @@class command on @@interface declarations. // FIXME. Currently, \class and @@class are indistinguishable. So, // \class is also allowed on an @@interface declaration if (DiagSelect && Comment->getCommandMarker() && isObjCInterfaceDecl()) DiagSelect = 0; break; case CommandTraits::KCI_interface: DiagSelect = !isObjCInterfaceDecl() ? 2 : 0; break; case CommandTraits::KCI_protocol: DiagSelect = !isObjCProtocolDecl() ? 3 : 0; break; case CommandTraits::KCI_struct: DiagSelect = !isClassOrStructDecl() ? 4 : 0; break; case CommandTraits::KCI_union: DiagSelect = !isUnionDecl() ? 5 : 0; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_api_container_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << (DiagSelect-1) << Comment->getSourceRange(); } void Sema::checkContainerDecl(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsRecordLikeDetailCommand || isRecordLikeDecl()) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_classdesign: DiagSelect = 1; break; case CommandTraits::KCI_coclass: DiagSelect = 2; break; case CommandTraits::KCI_dependency: DiagSelect = 3; break; case CommandTraits::KCI_helper: DiagSelect = 4; break; case CommandTraits::KCI_helperclass: DiagSelect = 5; break; case CommandTraits::KCI_helps: DiagSelect = 6; break; case CommandTraits::KCI_instancesize: DiagSelect = 7; break; case CommandTraits::KCI_ownership: DiagSelect = 8; break; case CommandTraits::KCI_performance: DiagSelect = 9; break; case CommandTraits::KCI_security: DiagSelect = 10; break; case CommandTraits::KCI_superclass: DiagSelect = 11; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_container_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << Comment->getSourceRange(); } /// \brief Turn a string into the corresponding PassDirection or -1 if it's not /// valid. static int getParamPassDirection(StringRef Arg) { return llvm::StringSwitch(Arg) .Case("[in]", ParamCommandComment::In) .Case("[out]", ParamCommandComment::Out) .Cases("[in,out]", "[out,in]", ParamCommandComment::InOut) .Default(-1); } void Sema::actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { std::string ArgLower = Arg.lower(); int Direction = getParamPassDirection(ArgLower); if (Direction == -1) { // Try again with whitespace removed. ArgLower.erase( std::remove_if(ArgLower.begin(), ArgLower.end(), clang::isWhitespace), ArgLower.end()); Direction = getParamPassDirection(ArgLower); SourceRange ArgRange(ArgLocBegin, ArgLocEnd); if (Direction != -1) { const char *FixedName = ParamCommandComment::getDirectionAsString( (ParamCommandComment::PassDirection)Direction); Diag(ArgLocBegin, diag::warn_doc_param_spaces_in_direction) << ArgRange << FixItHint::CreateReplacement(ArgRange, FixedName); } else { Diag(ArgLocBegin, diag::warn_doc_param_invalid_direction) << ArgRange; Direction = ParamCommandComment::In; // Sane fall back. } } Command->setDirection((ParamCommandComment::PassDirection)Direction, /*Explicit=*/true); } void Sema::actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { // Parser will not feed us more arguments than needed. assert(Command->getNumArgs() == 0); if (!Command->isDirectionExplicit()) { // User didn't provide a direction argument. Command->setDirection(ParamCommandComment::In, /* Explicit = */ false); } typedef BlockCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); Command->setArgs(llvm::makeArrayRef(A, 1)); } void Sema::actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); } TParamCommandComment *Sema::actOnTParamCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { TParamCommandComment *Command = new (Allocator) TParamCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); if (!isTemplateOrSpecialization()) Diag(Command->getLocation(), diag::warn_doc_tparam_not_attached_to_a_template_decl) << CommandMarker << Command->getCommandNameRange(Traits); return Command; } void Sema::actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { // Parser will not feed us more arguments than needed. assert(Command->getNumArgs() == 0); typedef BlockCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); Command->setArgs(llvm::makeArrayRef(A, 1)); if (!isTemplateOrSpecialization()) { // We already warned that this \\tparam is not attached to a template decl. return; } const TemplateParameterList *TemplateParameters = ThisDeclInfo->TemplateParameters; SmallVector Position; if (resolveTParamReference(Arg, TemplateParameters, &Position)) { Command->setPosition(copyArray(llvm::makeArrayRef(Position))); TParamCommandComment *&PrevCommand = TemplateParameterDocs[Arg]; if (PrevCommand) { SourceRange ArgRange(ArgLocBegin, ArgLocEnd); Diag(ArgLocBegin, diag::warn_doc_tparam_duplicate) << Arg << ArgRange; Diag(PrevCommand->getLocation(), diag::note_doc_tparam_previous) << PrevCommand->getParamNameRange(); } PrevCommand = Command; return; } SourceRange ArgRange(ArgLocBegin, ArgLocEnd); Diag(ArgLocBegin, diag::warn_doc_tparam_not_found) << Arg << ArgRange; if (!TemplateParameters || TemplateParameters->size() == 0) return; StringRef CorrectedName; if (TemplateParameters->size() == 1) { const NamedDecl *Param = TemplateParameters->getParam(0); const IdentifierInfo *II = Param->getIdentifier(); if (II) CorrectedName = II->getName(); } else { CorrectedName = correctTypoInTParamReference(Arg, TemplateParameters); } if (!CorrectedName.empty()) { Diag(ArgLocBegin, diag::note_doc_tparam_name_suggestion) << CorrectedName << FixItHint::CreateReplacement(ArgRange, CorrectedName); } return; } void Sema::actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); } InlineCommandComment *Sema::actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID) { ArrayRef Args; StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) InlineCommandComment( CommandLocBegin, CommandLocEnd, CommandID, getInlineCommandRenderKind(CommandName), Args); } InlineCommandComment *Sema::actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { typedef InlineCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) InlineCommandComment( CommandLocBegin, CommandLocEnd, CommandID, getInlineCommandRenderKind(CommandName), llvm::makeArrayRef(A, 1)); } InlineContentComment *Sema::actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName) { unsigned CommandID = Traits.registerUnknownCommand(CommandName)->getID(); return actOnUnknownCommand(LocBegin, LocEnd, CommandID); } InlineContentComment *Sema::actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID) { ArrayRef Args; return new (Allocator) InlineCommandComment( LocBegin, LocEnd, CommandID, InlineCommandComment::RenderNormal, Args); } TextComment *Sema::actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text) { return new (Allocator) TextComment(LocBegin, LocEnd, Text); } VerbatimBlockComment *Sema::actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID) { StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) VerbatimBlockComment( Loc, Loc.getLocWithOffset(1 + CommandName.size()), CommandID); } VerbatimBlockLineComment *Sema::actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text) { return new (Allocator) VerbatimBlockLineComment(Loc, Text); } void Sema::actOnVerbatimBlockFinish( VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef Lines) { Block->setCloseName(CloseName, CloseNameLocBegin); Block->setLines(Lines); } VerbatimLineComment *Sema::actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text) { VerbatimLineComment *VL = new (Allocator) VerbatimLineComment( LocBegin, TextBegin.getLocWithOffset(Text.size()), CommandID, TextBegin, Text); checkFunctionDeclVerbatimLine(VL); checkContainerDeclVerbatimLine(VL); return VL; } HTMLStartTagComment *Sema::actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName) { return new (Allocator) HTMLStartTagComment(LocBegin, TagName); } void Sema::actOnHTMLStartTagFinish( HTMLStartTagComment *Tag, ArrayRef Attrs, SourceLocation GreaterLoc, bool IsSelfClosing) { Tag->setAttrs(Attrs); Tag->setGreaterLoc(GreaterLoc); if (IsSelfClosing) Tag->setSelfClosing(); else if (!isHTMLEndTagForbidden(Tag->getTagName())) HTMLOpenTags.push_back(Tag); } HTMLEndTagComment *Sema::actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName) { HTMLEndTagComment *HET = new (Allocator) HTMLEndTagComment(LocBegin, LocEnd, TagName); if (isHTMLEndTagForbidden(TagName)) { Diag(HET->getLocation(), diag::warn_doc_html_end_forbidden) << TagName << HET->getSourceRange(); return HET; } bool FoundOpen = false; for (SmallVectorImpl::const_reverse_iterator I = HTMLOpenTags.rbegin(), E = HTMLOpenTags.rend(); I != E; ++I) { if ((*I)->getTagName() == TagName) { FoundOpen = true; break; } } if (!FoundOpen) { Diag(HET->getLocation(), diag::warn_doc_html_end_unbalanced) << HET->getSourceRange(); return HET; } while (!HTMLOpenTags.empty()) { const HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); StringRef LastNotClosedTagName = HST->getTagName(); if (LastNotClosedTagName == TagName) break; if (isHTMLEndTagOptional(LastNotClosedTagName)) continue; bool OpenLineInvalid; const unsigned OpenLine = SourceMgr.getPresumedLineNumber( HST->getLocation(), &OpenLineInvalid); bool CloseLineInvalid; const unsigned CloseLine = SourceMgr.getPresumedLineNumber( HET->getLocation(), &CloseLineInvalid); if (OpenLineInvalid || CloseLineInvalid || OpenLine == CloseLine) Diag(HST->getLocation(), diag::warn_doc_html_start_end_mismatch) << HST->getTagName() << HET->getTagName() << HST->getSourceRange() << HET->getSourceRange(); else { Diag(HST->getLocation(), diag::warn_doc_html_start_end_mismatch) << HST->getTagName() << HET->getTagName() << HST->getSourceRange(); Diag(HET->getLocation(), diag::note_doc_html_end_tag) << HET->getSourceRange(); } } return HET; } FullComment *Sema::actOnFullComment( ArrayRef Blocks) { FullComment *FC = new (Allocator) FullComment(Blocks, ThisDeclInfo); resolveParamCommandIndexes(FC); return FC; } void Sema::checkBlockCommandEmptyParagraph(BlockCommandComment *Command) { if (Traits.getCommandInfo(Command->getCommandID())->IsEmptyParagraphAllowed) return; ParagraphComment *Paragraph = Command->getParagraph(); if (Paragraph->isWhitespace()) { SourceLocation DiagLoc; if (Command->getNumArgs() > 0) DiagLoc = Command->getArgRange(Command->getNumArgs() - 1).getEnd(); if (!DiagLoc.isValid()) DiagLoc = Command->getCommandNameRange(Traits).getEnd(); Diag(DiagLoc, diag::warn_doc_block_command_empty_paragraph) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange(); } } void Sema::checkReturnsCommand(const BlockCommandComment *Command) { if (!Traits.getCommandInfo(Command->getCommandID())->IsReturnsCommand) return; if (isFunctionDecl()) { if (ThisDeclInfo->ResultType->isVoidType()) { unsigned DiagKind; switch (ThisDeclInfo->CommentDecl->getKind()) { default: if (ThisDeclInfo->IsObjCMethod) DiagKind = 3; else DiagKind = 0; break; case Decl::CXXConstructor: DiagKind = 1; break; case Decl::CXXDestructor: DiagKind = 2; break; } Diag(Command->getLocation(), diag::warn_doc_returns_attached_to_a_void_function) << Command->getCommandMarker() << Command->getCommandName(Traits) << DiagKind << Command->getSourceRange(); } return; } else if (isObjCPropertyDecl()) return; Diag(Command->getLocation(), diag::warn_doc_returns_not_attached_to_a_function_decl) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange(); } void Sema::checkBlockCommandDuplicate(const BlockCommandComment *Command) { const CommandInfo *Info = Traits.getCommandInfo(Command->getCommandID()); const BlockCommandComment *PrevCommand = NULL; if (Info->IsBriefCommand) { if (!BriefCommand) { BriefCommand = Command; return; } PrevCommand = BriefCommand; } else if (Info->IsHeaderfileCommand) { if (!HeaderfileCommand) { HeaderfileCommand = Command; return; } PrevCommand = HeaderfileCommand; } else { // We don't want to check this command for duplicates. return; } StringRef CommandName = Command->getCommandName(Traits); StringRef PrevCommandName = PrevCommand->getCommandName(Traits); Diag(Command->getLocation(), diag::warn_doc_block_command_duplicate) << Command->getCommandMarker() << CommandName << Command->getSourceRange(); if (CommandName == PrevCommandName) Diag(PrevCommand->getLocation(), diag::note_doc_block_command_previous) << PrevCommand->getCommandMarker() << PrevCommandName << PrevCommand->getSourceRange(); else Diag(PrevCommand->getLocation(), diag::note_doc_block_command_previous_alias) << PrevCommand->getCommandMarker() << PrevCommandName << CommandName; } void Sema::checkDeprecatedCommand(const BlockCommandComment *Command) { if (!Traits.getCommandInfo(Command->getCommandID())->IsDeprecatedCommand) return; const Decl *D = ThisDeclInfo->CommentDecl; if (!D) return; if (D->hasAttr() || D->hasAttr() || D->hasAttr()) return; Diag(Command->getLocation(), diag::warn_doc_deprecated_not_sync) << Command->getSourceRange(); // Try to emit a fixit with a deprecation attribute. if (const FunctionDecl *FD = dyn_cast(D)) { // Don't emit a Fix-It for non-member function definitions. GCC does not // accept attributes on them. const DeclContext *Ctx = FD->getDeclContext(); if ((!Ctx || !Ctx->isRecord()) && FD->doesThisDeclarationHaveABody()) return; StringRef AttributeSpelling = "__attribute__((deprecated))"; if (PP) { TokenValue Tokens[] = { tok::kw___attribute, tok::l_paren, tok::l_paren, PP->getIdentifierInfo("deprecated"), tok::r_paren, tok::r_paren }; StringRef MacroName = PP->getLastMacroWithSpelling(FD->getLocation(), Tokens); if (!MacroName.empty()) AttributeSpelling = MacroName; } SmallString<64> TextToInsert(" "); TextToInsert += AttributeSpelling; Diag(FD->getLocEnd(), diag::note_add_deprecation_attr) << FixItHint::CreateInsertion(FD->getLocEnd().getLocWithOffset(1), TextToInsert); } } void Sema::resolveParamCommandIndexes(const FullComment *FC) { if (!isFunctionDecl()) { // We already warned that \\param commands are not attached to a function // decl. return; } SmallVector UnresolvedParamCommands; // Comment AST nodes that correspond to \c ParamVars for which we have // found a \\param command or NULL if no documentation was found so far. SmallVector ParamVarDocs; ArrayRef ParamVars = getParamVars(); ParamVarDocs.resize(ParamVars.size(), NULL); // First pass over all \\param commands: resolve all parameter names. for (Comment::child_iterator I = FC->child_begin(), E = FC->child_end(); I != E; ++I) { ParamCommandComment *PCC = dyn_cast(*I); if (!PCC || !PCC->hasParamName()) continue; StringRef ParamName = PCC->getParamNameAsWritten(); // Check that referenced parameter name is in the function decl. const unsigned ResolvedParamIndex = resolveParmVarReference(ParamName, ParamVars); if (ResolvedParamIndex == ParamCommandComment::VarArgParamIndex) { PCC->setIsVarArgParam(); continue; } if (ResolvedParamIndex == ParamCommandComment::InvalidParamIndex) { UnresolvedParamCommands.push_back(PCC); continue; } PCC->setParamIndex(ResolvedParamIndex); if (ParamVarDocs[ResolvedParamIndex]) { SourceRange ArgRange = PCC->getParamNameRange(); Diag(ArgRange.getBegin(), diag::warn_doc_param_duplicate) << ParamName << ArgRange; ParamCommandComment *PrevCommand = ParamVarDocs[ResolvedParamIndex]; Diag(PrevCommand->getLocation(), diag::note_doc_param_previous) << PrevCommand->getParamNameRange(); } ParamVarDocs[ResolvedParamIndex] = PCC; } // Find parameter declarations that have no corresponding \\param. SmallVector OrphanedParamDecls; for (unsigned i = 0, e = ParamVarDocs.size(); i != e; ++i) { if (!ParamVarDocs[i]) OrphanedParamDecls.push_back(ParamVars[i]); } // Second pass over unresolved \\param commands: do typo correction. // Suggest corrections from a set of parameter declarations that have no // corresponding \\param. for (unsigned i = 0, e = UnresolvedParamCommands.size(); i != e; ++i) { const ParamCommandComment *PCC = UnresolvedParamCommands[i]; SourceRange ArgRange = PCC->getParamNameRange(); StringRef ParamName = PCC->getParamNameAsWritten(); Diag(ArgRange.getBegin(), diag::warn_doc_param_not_found) << ParamName << ArgRange; // All parameters documented -- can't suggest a correction. if (OrphanedParamDecls.size() == 0) continue; unsigned CorrectedParamIndex = ParamCommandComment::InvalidParamIndex; if (OrphanedParamDecls.size() == 1) { // If one parameter is not documented then that parameter is the only // possible suggestion. CorrectedParamIndex = 0; } else { // Do typo correction. CorrectedParamIndex = correctTypoInParmVarReference(ParamName, OrphanedParamDecls); } if (CorrectedParamIndex != ParamCommandComment::InvalidParamIndex) { const ParmVarDecl *CorrectedPVD = OrphanedParamDecls[CorrectedParamIndex]; if (const IdentifierInfo *CorrectedII = CorrectedPVD->getIdentifier()) Diag(ArgRange.getBegin(), diag::note_doc_param_name_suggestion) << CorrectedII->getName() << FixItHint::CreateReplacement(ArgRange, CorrectedII->getName()); } } } bool Sema::isFunctionDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->getKind() == DeclInfo::FunctionKind; } bool Sema::isAnyFunctionDecl() { return isFunctionDecl() && ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isFunctionOrMethodVariadic() { if (!isAnyFunctionDecl() && !isObjCMethodDecl()) return false; if (const FunctionDecl *FD = dyn_cast(ThisDeclInfo->CurrentDecl)) return FD->isVariadic(); if (const ObjCMethodDecl *MD = dyn_cast(ThisDeclInfo->CurrentDecl)) return MD->isVariadic(); return false; } bool Sema::isObjCMethodDecl() { return isFunctionDecl() && ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isFunctionPointerVarDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (ThisDeclInfo->getKind() == DeclInfo::VariableKind) { if (const VarDecl *VD = dyn_cast_or_null(ThisDeclInfo->CurrentDecl)) { QualType QT = VD->getType(); return QT->isFunctionPointerType(); } } return false; } bool Sema::isObjCPropertyDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl->getKind() == Decl::ObjCProperty; } bool Sema::isTemplateOrSpecialization() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->getTemplateKind() != DeclInfo::NotTemplate; } bool Sema::isRecordLikeDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return isUnionDecl() || isClassOrStructDecl() || isObjCInterfaceDecl() || isObjCProtocolDecl(); } bool Sema::isUnionDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (const RecordDecl *RD = dyn_cast_or_null(ThisDeclInfo->CurrentDecl)) return RD->isUnion(); return false; } bool Sema::isClassOrStructDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl) && !isUnionDecl(); } bool Sema::isClassTemplateDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && (isa(ThisDeclInfo->CurrentDecl)); } bool Sema::isFunctionTemplateDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && (isa(ThisDeclInfo->CurrentDecl)); } bool Sema::isObjCInterfaceDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isObjCProtocolDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } ArrayRef Sema::getParamVars() { if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->ParamVars; } void Sema::inspectThisDecl() { ThisDeclInfo->fill(); } unsigned Sema::resolveParmVarReference(StringRef Name, ArrayRef ParamVars) { for (unsigned i = 0, e = ParamVars.size(); i != e; ++i) { const IdentifierInfo *II = ParamVars[i]->getIdentifier(); if (II && II->getName() == Name) return i; } if (Name == "..." && isFunctionOrMethodVariadic()) return ParamCommandComment::VarArgParamIndex; return ParamCommandComment::InvalidParamIndex; } namespace { class SimpleTypoCorrector { StringRef Typo; const unsigned MaxEditDistance; const NamedDecl *BestDecl; unsigned BestEditDistance; unsigned BestIndex; unsigned NextIndex; public: SimpleTypoCorrector(StringRef Typo) : Typo(Typo), MaxEditDistance((Typo.size() + 2) / 3), BestDecl(NULL), BestEditDistance(MaxEditDistance + 1), BestIndex(0), NextIndex(0) { } void addDecl(const NamedDecl *ND); const NamedDecl *getBestDecl() const { if (BestEditDistance > MaxEditDistance) return NULL; return BestDecl; } unsigned getBestDeclIndex() const { assert(getBestDecl()); return BestIndex; } }; void SimpleTypoCorrector::addDecl(const NamedDecl *ND) { unsigned CurrIndex = NextIndex++; const IdentifierInfo *II = ND->getIdentifier(); if (!II) return; StringRef Name = II->getName(); unsigned MinPossibleEditDistance = abs((int)Name.size() - (int)Typo.size()); if (MinPossibleEditDistance > 0 && Typo.size() / MinPossibleEditDistance < 3) return; unsigned EditDistance = Typo.edit_distance(Name, true, MaxEditDistance); if (EditDistance < BestEditDistance) { BestEditDistance = EditDistance; BestDecl = ND; BestIndex = CurrIndex; } } } // unnamed namespace unsigned Sema::correctTypoInParmVarReference( StringRef Typo, ArrayRef ParamVars) { SimpleTypoCorrector Corrector(Typo); for (unsigned i = 0, e = ParamVars.size(); i != e; ++i) Corrector.addDecl(ParamVars[i]); if (Corrector.getBestDecl()) return Corrector.getBestDeclIndex(); else return ParamCommandComment::InvalidParamIndex; } namespace { bool ResolveTParamReferenceHelper( StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl *Position) { for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) { const NamedDecl *Param = TemplateParameters->getParam(i); const IdentifierInfo *II = Param->getIdentifier(); if (II && II->getName() == Name) { Position->push_back(i); return true; } if (const TemplateTemplateParmDecl *TTP = dyn_cast(Param)) { Position->push_back(i); if (ResolveTParamReferenceHelper(Name, TTP->getTemplateParameters(), Position)) return true; Position->pop_back(); } } return false; } } // unnamed namespace bool Sema::resolveTParamReference( StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl *Position) { Position->clear(); if (!TemplateParameters) return false; return ResolveTParamReferenceHelper(Name, TemplateParameters, Position); } namespace { void CorrectTypoInTParamReferenceHelper( const TemplateParameterList *TemplateParameters, SimpleTypoCorrector &Corrector) { for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) { const NamedDecl *Param = TemplateParameters->getParam(i); Corrector.addDecl(Param); if (const TemplateTemplateParmDecl *TTP = dyn_cast(Param)) CorrectTypoInTParamReferenceHelper(TTP->getTemplateParameters(), Corrector); } } } // unnamed namespace StringRef Sema::correctTypoInTParamReference( StringRef Typo, const TemplateParameterList *TemplateParameters) { SimpleTypoCorrector Corrector(Typo); CorrectTypoInTParamReferenceHelper(TemplateParameters, Corrector); if (const NamedDecl *ND = Corrector.getBestDecl()) { const IdentifierInfo *II = ND->getIdentifier(); assert(II && "SimpleTypoCorrector should not return this decl"); return II->getName(); } return StringRef(); } InlineCommandComment::RenderKind Sema::getInlineCommandRenderKind(StringRef Name) const { assert(Traits.getCommandInfo(Name)->IsInlineCommand); return llvm::StringSwitch(Name) .Case("b", InlineCommandComment::RenderBold) .Cases("c", "p", InlineCommandComment::RenderMonospaced) .Cases("a", "e", "em", InlineCommandComment::RenderEmphasized) .Default(InlineCommandComment::RenderNormal); } } // end namespace comments } // end namespace clang @ 1.1.1.1 log @Import Clang 3.4rc1 r195771. @ text @@ 1.1.1.2 log @Import clang 3.5svn r198450. @ text @d125 1 a125 1 d589 1 a589 1 d815 1 a815 1 d837 2 a838 2 return isUnionDecl() || isClassOrStructDecl() || isObjCInterfaceDecl() || isObjCProtocolDecl(); d851 1 a851 1 d861 1 a861 1 d877 1 a877 1 (isa(ThisDeclInfo->CurrentDecl)); d888 1 a888 1 d897 1 a897 1 @ 1.1.1.3 log @Import Clang 3.5svn r201163. @ text @d71 2 a72 6 if (ThisDeclInfo) { // These checks only make sense if the comment is attached to a // declaration. checkReturnsCommand(Command); checkDeprecatedCommand(Command); } a560 3 assert(ThisDeclInfo && "should not call this check on a bare comment"); d562 1 a562 1 if (ThisDeclInfo->ReturnType->isVoidType()) { a638 2 assert(ThisDeclInfo && "should not call this check on a bare comment"); @ 1.1.1.3.2.1 log @Rebase. @ text @d32 1 a32 2 PP(PP), ThisDeclInfo(nullptr), BriefCommand(nullptr), HeaderfileCommand(nullptr) { a484 1 HET->setIsMalformed(); a499 1 HET->setIsMalformed(); d504 1 a504 1 HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); d506 1 a506 4 if (LastNotClosedTagName == TagName) { // If the start tag is malformed, end tag is malformed as well. if (HST->isMalformed()) HET->setIsMalformed(); a507 1 } d521 1 a521 1 if (OpenLineInvalid || CloseLineInvalid || OpenLine == CloseLine) { d525 1 a525 2 HST->setIsMalformed(); } else { a530 1 HST->setIsMalformed(); a540 12 // Complain about HTML tags that are not closed. while (!HTMLOpenTags.empty()) { HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); if (isHTMLEndTagOptional(HST->getTagName())) continue; Diag(HST->getLocation(), diag::warn_doc_html_missing_end_tag) << HST->getTagName() << HST->getSourceRange(); HST->setIsMalformed(); } d606 1 a606 1 const BlockCommandComment *PrevCommand = nullptr; d706 1 a706 1 ParamVarDocs.resize(ParamVars.size(), nullptr); d795 1 a795 1 if (!isAnyFunctionDecl() && !isObjCMethodDecl() && !isFunctionTemplateDecl()) a799 3 if (const FunctionTemplateDecl *FTD = dyn_cast(ThisDeclInfo->CurrentDecl)) return FTD->getTemplatedDecl()->isVariadic(); d942 1 a942 1 BestDecl(nullptr), BestEditDistance(MaxEditDistance + 1), d950 1 a950 1 return nullptr; @ 1.1.1.4 log @Import Clang 3.5svn r209886. @ text @d32 1 a32 2 PP(PP), ThisDeclInfo(nullptr), BriefCommand(nullptr), HeaderfileCommand(nullptr) { a484 1 HET->setIsMalformed(); a499 1 HET->setIsMalformed(); d504 1 a504 1 HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); d506 1 a506 4 if (LastNotClosedTagName == TagName) { // If the start tag is malformed, end tag is malformed as well. if (HST->isMalformed()) HET->setIsMalformed(); a507 1 } d521 1 a521 1 if (OpenLineInvalid || CloseLineInvalid || OpenLine == CloseLine) { d525 1 a525 2 HST->setIsMalformed(); } else { a530 1 HST->setIsMalformed(); a540 12 // Complain about HTML tags that are not closed. while (!HTMLOpenTags.empty()) { HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); if (isHTMLEndTagOptional(HST->getTagName())) continue; Diag(HST->getLocation(), diag::warn_doc_html_missing_end_tag) << HST->getTagName() << HST->getSourceRange(); HST->setIsMalformed(); } d606 1 a606 1 const BlockCommandComment *PrevCommand = nullptr; d706 1 a706 1 ParamVarDocs.resize(ParamVars.size(), nullptr); d795 1 a795 1 if (!isAnyFunctionDecl() && !isObjCMethodDecl() && !isFunctionTemplateDecl()) a799 3 if (const FunctionTemplateDecl *FTD = dyn_cast(ThisDeclInfo->CurrentDecl)) return FTD->getTemplatedDecl()->isVariadic(); d942 1 a942 1 BestDecl(nullptr), BestEditDistance(MaxEditDistance + 1), d950 1 a950 1 return nullptr; @ 1.1.1.4.8.1 log @Sync with HEAD @ text @d26 1 a26 1 } // end anonymous namespace d356 2 a954 2 const NamedDecl *BestDecl; d958 1 d964 5 a968 3 explicit SimpleTypoCorrector(StringRef Typo) : BestDecl(nullptr), Typo(Typo), MaxEditDistance((Typo.size() + 2) / 3), BestEditDistance(MaxEditDistance + 1), BestIndex(0), NextIndex(0) {} d1005 1 a1005 1 } // end anonymous namespace d1043 1 a1043 1 } // end anonymous namespace d1070 1 a1070 1 } // end anonymous namespace d1098 1 @ 1.1.1.5 log @Import Clang pre-4.0.0 r291444. @ text @d26 1 a26 1 } // end anonymous namespace d356 2 a954 2 const NamedDecl *BestDecl; d958 1 d964 5 a968 3 explicit SimpleTypoCorrector(StringRef Typo) : BestDecl(nullptr), Typo(Typo), MaxEditDistance((Typo.size() + 2) / 3), BestEditDistance(MaxEditDistance + 1), BestIndex(0), NextIndex(0) {} d1005 1 a1005 1 } // end anonymous namespace d1043 1 a1043 1 } // end anonymous namespace d1070 1 a1070 1 } // end anonymous namespace d1098 1 @ 1.1.1.6 log @Import clang r309604 from branches/release_50 @ text @d89 1 a89 1 if (!isFunctionDecl() && !isFunctionOrBlockPointerVarLikeDecl()) d587 1 a587 5 // We allow the return command for all @@properties because it can be used // to document the value that the property getter returns. if (isObjCPropertyDecl()) return; if (isFunctionDecl() || isFunctionOrBlockPointerVarLikeDecl()) { d613 2 a846 24 bool Sema::isFunctionOrBlockPointerVarLikeDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (ThisDeclInfo->getKind() != DeclInfo::VariableKind || !ThisDeclInfo->CurrentDecl) return false; QualType QT; if (const auto *VD = dyn_cast(ThisDeclInfo->CurrentDecl)) QT = VD->getType(); else if (const auto *PD = dyn_cast(ThisDeclInfo->CurrentDecl)) QT = PD->getType(); else return false; // We would like to warn about the 'returns'/'param' commands for // variables that don't directly specify the function type, so type aliases // can be ignored. if (QT->getAs()) return false; return QT->isFunctionPointerType() || QT->isBlockPointerType(); } @ 1.1.1.6.4.1 log @Sync with HEAD @ text @d218 1 a218 1 /// Turn a string into the corresponding PassDirection or -1 if it's not d816 1 a816 1 if (!isFunctionDecl() || !ThisDeclInfo->CurrentDecl) a826 8 if (const TypedefNameDecl *TD = dyn_cast(ThisDeclInfo->CurrentDecl)) { QualType Type = TD->getUnderlyingType(); if (Type->isFunctionPointerType() || Type->isBlockPointerType()) Type = Type->getPointeeType(); if (const auto *FT = Type->getAs()) return FT->isVariadic(); } @ 1.1.1.6.4.2 log @Mostly merge changes from HEAD upto 20200411 @ text @@ 1.1.1.6.2.1 log @Sync with HEAD @ text @d218 1 a218 1 /// Turn a string into the corresponding PassDirection or -1 if it's not d816 1 a816 1 if (!isFunctionDecl() || !ThisDeclInfo->CurrentDecl) a826 8 if (const TypedefNameDecl *TD = dyn_cast(ThisDeclInfo->CurrentDecl)) { QualType Type = TD->getUnderlyingType(); if (Type->isFunctionPointerType() || Type->isBlockPointerType()) Type = Type->getPointeeType(); if (const auto *FT = Type->getAs()) return FT->isVariadic(); } @ 1.1.1.7 log @Import clang r337282 from trunk @ text @d218 1 a218 1 /// Turn a string into the corresponding PassDirection or -1 if it's not d816 1 a816 1 if (!isFunctionDecl() || !ThisDeclInfo->CurrentDecl) a826 8 if (const TypedefNameDecl *TD = dyn_cast(ThisDeclInfo->CurrentDecl)) { QualType Type = TD->getUnderlyingType(); if (Type->isFunctionPointerType() || Type->isBlockPointerType()) Type = Type->getPointeeType(); if (const auto *FT = Type->getAs()) return FT->isVariadic(); } @ 1.1.1.8 log @Mark old LLVM instance as dead. @ text @@ 1.1.1.4.4.1 log @file CommentSema.cpp was added on branch tls-maxphys on 2014-08-19 23:47:25 +0000 @ text @d1 1098 @ 1.1.1.4.4.2 log @Rebase to HEAD as of a few days ago. @ text @a0 1098 //===--- CommentSema.cpp - Doxygen comment semantic analysis --------------===// // // The LLVM Compiler Infrastructure // // This file is distributed under the University of Illinois Open Source // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// #include "clang/AST/CommentSema.h" #include "clang/AST/Attr.h" #include "clang/AST/CommentCommandTraits.h" #include "clang/AST/CommentDiagnostic.h" #include "clang/AST/Decl.h" #include "clang/AST/DeclTemplate.h" #include "clang/Basic/SourceManager.h" #include "clang/Lex/Preprocessor.h" #include "llvm/ADT/SmallString.h" #include "llvm/ADT/StringSwitch.h" namespace clang { namespace comments { namespace { #include "clang/AST/CommentHTMLTagsProperties.inc" } // unnamed namespace Sema::Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, DiagnosticsEngine &Diags, CommandTraits &Traits, const Preprocessor *PP) : Allocator(Allocator), SourceMgr(SourceMgr), Diags(Diags), Traits(Traits), PP(PP), ThisDeclInfo(nullptr), BriefCommand(nullptr), HeaderfileCommand(nullptr) { } void Sema::setDecl(const Decl *D) { if (!D) return; ThisDeclInfo = new (Allocator) DeclInfo; ThisDeclInfo->CommentDecl = D; ThisDeclInfo->IsFilled = false; } ParagraphComment *Sema::actOnParagraphComment( ArrayRef Content) { return new (Allocator) ParagraphComment(Content); } BlockCommandComment *Sema::actOnBlockCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { BlockCommandComment *BC = new (Allocator) BlockCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); checkContainerDecl(BC); return BC; } void Sema::actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef Args) { Command->setArgs(Args); } void Sema::actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); checkBlockCommandDuplicate(Command); if (ThisDeclInfo) { // These checks only make sense if the comment is attached to a // declaration. checkReturnsCommand(Command); checkDeprecatedCommand(Command); } } ParamCommandComment *Sema::actOnParamCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { ParamCommandComment *Command = new (Allocator) ParamCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); if (!isFunctionDecl()) Diag(Command->getLocation(), diag::warn_doc_param_not_attached_to_a_function_decl) << CommandMarker << Command->getCommandNameRange(Traits); return Command; } void Sema::checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsFunctionDeclarationCommand) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_function: DiagSelect = (!isAnyFunctionDecl() && !isFunctionTemplateDecl())? 1 : 0; break; case CommandTraits::KCI_functiongroup: DiagSelect = (!isAnyFunctionDecl() && !isFunctionTemplateDecl())? 2 : 0; break; case CommandTraits::KCI_method: DiagSelect = !isObjCMethodDecl() ? 3 : 0; break; case CommandTraits::KCI_methodgroup: DiagSelect = !isObjCMethodDecl() ? 4 : 0; break; case CommandTraits::KCI_callback: DiagSelect = !isFunctionPointerVarDecl() ? 5 : 0; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_function_method_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << (DiagSelect-1) << Comment->getSourceRange(); } void Sema::checkContainerDeclVerbatimLine(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsRecordLikeDeclarationCommand) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_class: DiagSelect = (!isClassOrStructDecl() && !isClassTemplateDecl()) ? 1 : 0; // Allow @@class command on @@interface declarations. // FIXME. Currently, \class and @@class are indistinguishable. So, // \class is also allowed on an @@interface declaration if (DiagSelect && Comment->getCommandMarker() && isObjCInterfaceDecl()) DiagSelect = 0; break; case CommandTraits::KCI_interface: DiagSelect = !isObjCInterfaceDecl() ? 2 : 0; break; case CommandTraits::KCI_protocol: DiagSelect = !isObjCProtocolDecl() ? 3 : 0; break; case CommandTraits::KCI_struct: DiagSelect = !isClassOrStructDecl() ? 4 : 0; break; case CommandTraits::KCI_union: DiagSelect = !isUnionDecl() ? 5 : 0; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_api_container_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << (DiagSelect-1) << Comment->getSourceRange(); } void Sema::checkContainerDecl(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsRecordLikeDetailCommand || isRecordLikeDecl()) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_classdesign: DiagSelect = 1; break; case CommandTraits::KCI_coclass: DiagSelect = 2; break; case CommandTraits::KCI_dependency: DiagSelect = 3; break; case CommandTraits::KCI_helper: DiagSelect = 4; break; case CommandTraits::KCI_helperclass: DiagSelect = 5; break; case CommandTraits::KCI_helps: DiagSelect = 6; break; case CommandTraits::KCI_instancesize: DiagSelect = 7; break; case CommandTraits::KCI_ownership: DiagSelect = 8; break; case CommandTraits::KCI_performance: DiagSelect = 9; break; case CommandTraits::KCI_security: DiagSelect = 10; break; case CommandTraits::KCI_superclass: DiagSelect = 11; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_container_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << Comment->getSourceRange(); } /// \brief Turn a string into the corresponding PassDirection or -1 if it's not /// valid. static int getParamPassDirection(StringRef Arg) { return llvm::StringSwitch(Arg) .Case("[in]", ParamCommandComment::In) .Case("[out]", ParamCommandComment::Out) .Cases("[in,out]", "[out,in]", ParamCommandComment::InOut) .Default(-1); } void Sema::actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { std::string ArgLower = Arg.lower(); int Direction = getParamPassDirection(ArgLower); if (Direction == -1) { // Try again with whitespace removed. ArgLower.erase( std::remove_if(ArgLower.begin(), ArgLower.end(), clang::isWhitespace), ArgLower.end()); Direction = getParamPassDirection(ArgLower); SourceRange ArgRange(ArgLocBegin, ArgLocEnd); if (Direction != -1) { const char *FixedName = ParamCommandComment::getDirectionAsString( (ParamCommandComment::PassDirection)Direction); Diag(ArgLocBegin, diag::warn_doc_param_spaces_in_direction) << ArgRange << FixItHint::CreateReplacement(ArgRange, FixedName); } else { Diag(ArgLocBegin, diag::warn_doc_param_invalid_direction) << ArgRange; Direction = ParamCommandComment::In; // Sane fall back. } } Command->setDirection((ParamCommandComment::PassDirection)Direction, /*Explicit=*/true); } void Sema::actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { // Parser will not feed us more arguments than needed. assert(Command->getNumArgs() == 0); if (!Command->isDirectionExplicit()) { // User didn't provide a direction argument. Command->setDirection(ParamCommandComment::In, /* Explicit = */ false); } typedef BlockCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); Command->setArgs(llvm::makeArrayRef(A, 1)); } void Sema::actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); } TParamCommandComment *Sema::actOnTParamCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { TParamCommandComment *Command = new (Allocator) TParamCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); if (!isTemplateOrSpecialization()) Diag(Command->getLocation(), diag::warn_doc_tparam_not_attached_to_a_template_decl) << CommandMarker << Command->getCommandNameRange(Traits); return Command; } void Sema::actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { // Parser will not feed us more arguments than needed. assert(Command->getNumArgs() == 0); typedef BlockCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); Command->setArgs(llvm::makeArrayRef(A, 1)); if (!isTemplateOrSpecialization()) { // We already warned that this \\tparam is not attached to a template decl. return; } const TemplateParameterList *TemplateParameters = ThisDeclInfo->TemplateParameters; SmallVector Position; if (resolveTParamReference(Arg, TemplateParameters, &Position)) { Command->setPosition(copyArray(llvm::makeArrayRef(Position))); TParamCommandComment *&PrevCommand = TemplateParameterDocs[Arg]; if (PrevCommand) { SourceRange ArgRange(ArgLocBegin, ArgLocEnd); Diag(ArgLocBegin, diag::warn_doc_tparam_duplicate) << Arg << ArgRange; Diag(PrevCommand->getLocation(), diag::note_doc_tparam_previous) << PrevCommand->getParamNameRange(); } PrevCommand = Command; return; } SourceRange ArgRange(ArgLocBegin, ArgLocEnd); Diag(ArgLocBegin, diag::warn_doc_tparam_not_found) << Arg << ArgRange; if (!TemplateParameters || TemplateParameters->size() == 0) return; StringRef CorrectedName; if (TemplateParameters->size() == 1) { const NamedDecl *Param = TemplateParameters->getParam(0); const IdentifierInfo *II = Param->getIdentifier(); if (II) CorrectedName = II->getName(); } else { CorrectedName = correctTypoInTParamReference(Arg, TemplateParameters); } if (!CorrectedName.empty()) { Diag(ArgLocBegin, diag::note_doc_tparam_name_suggestion) << CorrectedName << FixItHint::CreateReplacement(ArgRange, CorrectedName); } return; } void Sema::actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); } InlineCommandComment *Sema::actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID) { ArrayRef Args; StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) InlineCommandComment( CommandLocBegin, CommandLocEnd, CommandID, getInlineCommandRenderKind(CommandName), Args); } InlineCommandComment *Sema::actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { typedef InlineCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) InlineCommandComment( CommandLocBegin, CommandLocEnd, CommandID, getInlineCommandRenderKind(CommandName), llvm::makeArrayRef(A, 1)); } InlineContentComment *Sema::actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName) { unsigned CommandID = Traits.registerUnknownCommand(CommandName)->getID(); return actOnUnknownCommand(LocBegin, LocEnd, CommandID); } InlineContentComment *Sema::actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID) { ArrayRef Args; return new (Allocator) InlineCommandComment( LocBegin, LocEnd, CommandID, InlineCommandComment::RenderNormal, Args); } TextComment *Sema::actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text) { return new (Allocator) TextComment(LocBegin, LocEnd, Text); } VerbatimBlockComment *Sema::actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID) { StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) VerbatimBlockComment( Loc, Loc.getLocWithOffset(1 + CommandName.size()), CommandID); } VerbatimBlockLineComment *Sema::actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text) { return new (Allocator) VerbatimBlockLineComment(Loc, Text); } void Sema::actOnVerbatimBlockFinish( VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef Lines) { Block->setCloseName(CloseName, CloseNameLocBegin); Block->setLines(Lines); } VerbatimLineComment *Sema::actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text) { VerbatimLineComment *VL = new (Allocator) VerbatimLineComment( LocBegin, TextBegin.getLocWithOffset(Text.size()), CommandID, TextBegin, Text); checkFunctionDeclVerbatimLine(VL); checkContainerDeclVerbatimLine(VL); return VL; } HTMLStartTagComment *Sema::actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName) { return new (Allocator) HTMLStartTagComment(LocBegin, TagName); } void Sema::actOnHTMLStartTagFinish( HTMLStartTagComment *Tag, ArrayRef Attrs, SourceLocation GreaterLoc, bool IsSelfClosing) { Tag->setAttrs(Attrs); Tag->setGreaterLoc(GreaterLoc); if (IsSelfClosing) Tag->setSelfClosing(); else if (!isHTMLEndTagForbidden(Tag->getTagName())) HTMLOpenTags.push_back(Tag); } HTMLEndTagComment *Sema::actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName) { HTMLEndTagComment *HET = new (Allocator) HTMLEndTagComment(LocBegin, LocEnd, TagName); if (isHTMLEndTagForbidden(TagName)) { Diag(HET->getLocation(), diag::warn_doc_html_end_forbidden) << TagName << HET->getSourceRange(); HET->setIsMalformed(); return HET; } bool FoundOpen = false; for (SmallVectorImpl::const_reverse_iterator I = HTMLOpenTags.rbegin(), E = HTMLOpenTags.rend(); I != E; ++I) { if ((*I)->getTagName() == TagName) { FoundOpen = true; break; } } if (!FoundOpen) { Diag(HET->getLocation(), diag::warn_doc_html_end_unbalanced) << HET->getSourceRange(); HET->setIsMalformed(); return HET; } while (!HTMLOpenTags.empty()) { HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); StringRef LastNotClosedTagName = HST->getTagName(); if (LastNotClosedTagName == TagName) { // If the start tag is malformed, end tag is malformed as well. if (HST->isMalformed()) HET->setIsMalformed(); break; } if (isHTMLEndTagOptional(LastNotClosedTagName)) continue; bool OpenLineInvalid; const unsigned OpenLine = SourceMgr.getPresumedLineNumber( HST->getLocation(), &OpenLineInvalid); bool CloseLineInvalid; const unsigned CloseLine = SourceMgr.getPresumedLineNumber( HET->getLocation(), &CloseLineInvalid); if (OpenLineInvalid || CloseLineInvalid || OpenLine == CloseLine) { Diag(HST->getLocation(), diag::warn_doc_html_start_end_mismatch) << HST->getTagName() << HET->getTagName() << HST->getSourceRange() << HET->getSourceRange(); HST->setIsMalformed(); } else { Diag(HST->getLocation(), diag::warn_doc_html_start_end_mismatch) << HST->getTagName() << HET->getTagName() << HST->getSourceRange(); Diag(HET->getLocation(), diag::note_doc_html_end_tag) << HET->getSourceRange(); HST->setIsMalformed(); } } return HET; } FullComment *Sema::actOnFullComment( ArrayRef Blocks) { FullComment *FC = new (Allocator) FullComment(Blocks, ThisDeclInfo); resolveParamCommandIndexes(FC); // Complain about HTML tags that are not closed. while (!HTMLOpenTags.empty()) { HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); if (isHTMLEndTagOptional(HST->getTagName())) continue; Diag(HST->getLocation(), diag::warn_doc_html_missing_end_tag) << HST->getTagName() << HST->getSourceRange(); HST->setIsMalformed(); } return FC; } void Sema::checkBlockCommandEmptyParagraph(BlockCommandComment *Command) { if (Traits.getCommandInfo(Command->getCommandID())->IsEmptyParagraphAllowed) return; ParagraphComment *Paragraph = Command->getParagraph(); if (Paragraph->isWhitespace()) { SourceLocation DiagLoc; if (Command->getNumArgs() > 0) DiagLoc = Command->getArgRange(Command->getNumArgs() - 1).getEnd(); if (!DiagLoc.isValid()) DiagLoc = Command->getCommandNameRange(Traits).getEnd(); Diag(DiagLoc, diag::warn_doc_block_command_empty_paragraph) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange(); } } void Sema::checkReturnsCommand(const BlockCommandComment *Command) { if (!Traits.getCommandInfo(Command->getCommandID())->IsReturnsCommand) return; assert(ThisDeclInfo && "should not call this check on a bare comment"); if (isFunctionDecl()) { if (ThisDeclInfo->ReturnType->isVoidType()) { unsigned DiagKind; switch (ThisDeclInfo->CommentDecl->getKind()) { default: if (ThisDeclInfo->IsObjCMethod) DiagKind = 3; else DiagKind = 0; break; case Decl::CXXConstructor: DiagKind = 1; break; case Decl::CXXDestructor: DiagKind = 2; break; } Diag(Command->getLocation(), diag::warn_doc_returns_attached_to_a_void_function) << Command->getCommandMarker() << Command->getCommandName(Traits) << DiagKind << Command->getSourceRange(); } return; } else if (isObjCPropertyDecl()) return; Diag(Command->getLocation(), diag::warn_doc_returns_not_attached_to_a_function_decl) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange(); } void Sema::checkBlockCommandDuplicate(const BlockCommandComment *Command) { const CommandInfo *Info = Traits.getCommandInfo(Command->getCommandID()); const BlockCommandComment *PrevCommand = nullptr; if (Info->IsBriefCommand) { if (!BriefCommand) { BriefCommand = Command; return; } PrevCommand = BriefCommand; } else if (Info->IsHeaderfileCommand) { if (!HeaderfileCommand) { HeaderfileCommand = Command; return; } PrevCommand = HeaderfileCommand; } else { // We don't want to check this command for duplicates. return; } StringRef CommandName = Command->getCommandName(Traits); StringRef PrevCommandName = PrevCommand->getCommandName(Traits); Diag(Command->getLocation(), diag::warn_doc_block_command_duplicate) << Command->getCommandMarker() << CommandName << Command->getSourceRange(); if (CommandName == PrevCommandName) Diag(PrevCommand->getLocation(), diag::note_doc_block_command_previous) << PrevCommand->getCommandMarker() << PrevCommandName << PrevCommand->getSourceRange(); else Diag(PrevCommand->getLocation(), diag::note_doc_block_command_previous_alias) << PrevCommand->getCommandMarker() << PrevCommandName << CommandName; } void Sema::checkDeprecatedCommand(const BlockCommandComment *Command) { if (!Traits.getCommandInfo(Command->getCommandID())->IsDeprecatedCommand) return; assert(ThisDeclInfo && "should not call this check on a bare comment"); const Decl *D = ThisDeclInfo->CommentDecl; if (!D) return; if (D->hasAttr() || D->hasAttr() || D->hasAttr()) return; Diag(Command->getLocation(), diag::warn_doc_deprecated_not_sync) << Command->getSourceRange(); // Try to emit a fixit with a deprecation attribute. if (const FunctionDecl *FD = dyn_cast(D)) { // Don't emit a Fix-It for non-member function definitions. GCC does not // accept attributes on them. const DeclContext *Ctx = FD->getDeclContext(); if ((!Ctx || !Ctx->isRecord()) && FD->doesThisDeclarationHaveABody()) return; StringRef AttributeSpelling = "__attribute__((deprecated))"; if (PP) { TokenValue Tokens[] = { tok::kw___attribute, tok::l_paren, tok::l_paren, PP->getIdentifierInfo("deprecated"), tok::r_paren, tok::r_paren }; StringRef MacroName = PP->getLastMacroWithSpelling(FD->getLocation(), Tokens); if (!MacroName.empty()) AttributeSpelling = MacroName; } SmallString<64> TextToInsert(" "); TextToInsert += AttributeSpelling; Diag(FD->getLocEnd(), diag::note_add_deprecation_attr) << FixItHint::CreateInsertion(FD->getLocEnd().getLocWithOffset(1), TextToInsert); } } void Sema::resolveParamCommandIndexes(const FullComment *FC) { if (!isFunctionDecl()) { // We already warned that \\param commands are not attached to a function // decl. return; } SmallVector UnresolvedParamCommands; // Comment AST nodes that correspond to \c ParamVars for which we have // found a \\param command or NULL if no documentation was found so far. SmallVector ParamVarDocs; ArrayRef ParamVars = getParamVars(); ParamVarDocs.resize(ParamVars.size(), nullptr); // First pass over all \\param commands: resolve all parameter names. for (Comment::child_iterator I = FC->child_begin(), E = FC->child_end(); I != E; ++I) { ParamCommandComment *PCC = dyn_cast(*I); if (!PCC || !PCC->hasParamName()) continue; StringRef ParamName = PCC->getParamNameAsWritten(); // Check that referenced parameter name is in the function decl. const unsigned ResolvedParamIndex = resolveParmVarReference(ParamName, ParamVars); if (ResolvedParamIndex == ParamCommandComment::VarArgParamIndex) { PCC->setIsVarArgParam(); continue; } if (ResolvedParamIndex == ParamCommandComment::InvalidParamIndex) { UnresolvedParamCommands.push_back(PCC); continue; } PCC->setParamIndex(ResolvedParamIndex); if (ParamVarDocs[ResolvedParamIndex]) { SourceRange ArgRange = PCC->getParamNameRange(); Diag(ArgRange.getBegin(), diag::warn_doc_param_duplicate) << ParamName << ArgRange; ParamCommandComment *PrevCommand = ParamVarDocs[ResolvedParamIndex]; Diag(PrevCommand->getLocation(), diag::note_doc_param_previous) << PrevCommand->getParamNameRange(); } ParamVarDocs[ResolvedParamIndex] = PCC; } // Find parameter declarations that have no corresponding \\param. SmallVector OrphanedParamDecls; for (unsigned i = 0, e = ParamVarDocs.size(); i != e; ++i) { if (!ParamVarDocs[i]) OrphanedParamDecls.push_back(ParamVars[i]); } // Second pass over unresolved \\param commands: do typo correction. // Suggest corrections from a set of parameter declarations that have no // corresponding \\param. for (unsigned i = 0, e = UnresolvedParamCommands.size(); i != e; ++i) { const ParamCommandComment *PCC = UnresolvedParamCommands[i]; SourceRange ArgRange = PCC->getParamNameRange(); StringRef ParamName = PCC->getParamNameAsWritten(); Diag(ArgRange.getBegin(), diag::warn_doc_param_not_found) << ParamName << ArgRange; // All parameters documented -- can't suggest a correction. if (OrphanedParamDecls.size() == 0) continue; unsigned CorrectedParamIndex = ParamCommandComment::InvalidParamIndex; if (OrphanedParamDecls.size() == 1) { // If one parameter is not documented then that parameter is the only // possible suggestion. CorrectedParamIndex = 0; } else { // Do typo correction. CorrectedParamIndex = correctTypoInParmVarReference(ParamName, OrphanedParamDecls); } if (CorrectedParamIndex != ParamCommandComment::InvalidParamIndex) { const ParmVarDecl *CorrectedPVD = OrphanedParamDecls[CorrectedParamIndex]; if (const IdentifierInfo *CorrectedII = CorrectedPVD->getIdentifier()) Diag(ArgRange.getBegin(), diag::note_doc_param_name_suggestion) << CorrectedII->getName() << FixItHint::CreateReplacement(ArgRange, CorrectedII->getName()); } } } bool Sema::isFunctionDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->getKind() == DeclInfo::FunctionKind; } bool Sema::isAnyFunctionDecl() { return isFunctionDecl() && ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isFunctionOrMethodVariadic() { if (!isAnyFunctionDecl() && !isObjCMethodDecl() && !isFunctionTemplateDecl()) return false; if (const FunctionDecl *FD = dyn_cast(ThisDeclInfo->CurrentDecl)) return FD->isVariadic(); if (const FunctionTemplateDecl *FTD = dyn_cast(ThisDeclInfo->CurrentDecl)) return FTD->getTemplatedDecl()->isVariadic(); if (const ObjCMethodDecl *MD = dyn_cast(ThisDeclInfo->CurrentDecl)) return MD->isVariadic(); return false; } bool Sema::isObjCMethodDecl() { return isFunctionDecl() && ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isFunctionPointerVarDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (ThisDeclInfo->getKind() == DeclInfo::VariableKind) { if (const VarDecl *VD = dyn_cast_or_null(ThisDeclInfo->CurrentDecl)) { QualType QT = VD->getType(); return QT->isFunctionPointerType(); } } return false; } bool Sema::isObjCPropertyDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl->getKind() == Decl::ObjCProperty; } bool Sema::isTemplateOrSpecialization() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->getTemplateKind() != DeclInfo::NotTemplate; } bool Sema::isRecordLikeDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return isUnionDecl() || isClassOrStructDecl() || isObjCInterfaceDecl() || isObjCProtocolDecl(); } bool Sema::isUnionDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (const RecordDecl *RD = dyn_cast_or_null(ThisDeclInfo->CurrentDecl)) return RD->isUnion(); return false; } bool Sema::isClassOrStructDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl) && !isUnionDecl(); } bool Sema::isClassTemplateDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && (isa(ThisDeclInfo->CurrentDecl)); } bool Sema::isFunctionTemplateDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && (isa(ThisDeclInfo->CurrentDecl)); } bool Sema::isObjCInterfaceDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isObjCProtocolDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } ArrayRef Sema::getParamVars() { if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->ParamVars; } void Sema::inspectThisDecl() { ThisDeclInfo->fill(); } unsigned Sema::resolveParmVarReference(StringRef Name, ArrayRef ParamVars) { for (unsigned i = 0, e = ParamVars.size(); i != e; ++i) { const IdentifierInfo *II = ParamVars[i]->getIdentifier(); if (II && II->getName() == Name) return i; } if (Name == "..." && isFunctionOrMethodVariadic()) return ParamCommandComment::VarArgParamIndex; return ParamCommandComment::InvalidParamIndex; } namespace { class SimpleTypoCorrector { StringRef Typo; const unsigned MaxEditDistance; const NamedDecl *BestDecl; unsigned BestEditDistance; unsigned BestIndex; unsigned NextIndex; public: SimpleTypoCorrector(StringRef Typo) : Typo(Typo), MaxEditDistance((Typo.size() + 2) / 3), BestDecl(nullptr), BestEditDistance(MaxEditDistance + 1), BestIndex(0), NextIndex(0) { } void addDecl(const NamedDecl *ND); const NamedDecl *getBestDecl() const { if (BestEditDistance > MaxEditDistance) return nullptr; return BestDecl; } unsigned getBestDeclIndex() const { assert(getBestDecl()); return BestIndex; } }; void SimpleTypoCorrector::addDecl(const NamedDecl *ND) { unsigned CurrIndex = NextIndex++; const IdentifierInfo *II = ND->getIdentifier(); if (!II) return; StringRef Name = II->getName(); unsigned MinPossibleEditDistance = abs((int)Name.size() - (int)Typo.size()); if (MinPossibleEditDistance > 0 && Typo.size() / MinPossibleEditDistance < 3) return; unsigned EditDistance = Typo.edit_distance(Name, true, MaxEditDistance); if (EditDistance < BestEditDistance) { BestEditDistance = EditDistance; BestDecl = ND; BestIndex = CurrIndex; } } } // unnamed namespace unsigned Sema::correctTypoInParmVarReference( StringRef Typo, ArrayRef ParamVars) { SimpleTypoCorrector Corrector(Typo); for (unsigned i = 0, e = ParamVars.size(); i != e; ++i) Corrector.addDecl(ParamVars[i]); if (Corrector.getBestDecl()) return Corrector.getBestDeclIndex(); else return ParamCommandComment::InvalidParamIndex; } namespace { bool ResolveTParamReferenceHelper( StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl *Position) { for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) { const NamedDecl *Param = TemplateParameters->getParam(i); const IdentifierInfo *II = Param->getIdentifier(); if (II && II->getName() == Name) { Position->push_back(i); return true; } if (const TemplateTemplateParmDecl *TTP = dyn_cast(Param)) { Position->push_back(i); if (ResolveTParamReferenceHelper(Name, TTP->getTemplateParameters(), Position)) return true; Position->pop_back(); } } return false; } } // unnamed namespace bool Sema::resolveTParamReference( StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl *Position) { Position->clear(); if (!TemplateParameters) return false; return ResolveTParamReferenceHelper(Name, TemplateParameters, Position); } namespace { void CorrectTypoInTParamReferenceHelper( const TemplateParameterList *TemplateParameters, SimpleTypoCorrector &Corrector) { for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) { const NamedDecl *Param = TemplateParameters->getParam(i); Corrector.addDecl(Param); if (const TemplateTemplateParmDecl *TTP = dyn_cast(Param)) CorrectTypoInTParamReferenceHelper(TTP->getTemplateParameters(), Corrector); } } } // unnamed namespace StringRef Sema::correctTypoInTParamReference( StringRef Typo, const TemplateParameterList *TemplateParameters) { SimpleTypoCorrector Corrector(Typo); CorrectTypoInTParamReferenceHelper(TemplateParameters, Corrector); if (const NamedDecl *ND = Corrector.getBestDecl()) { const IdentifierInfo *II = ND->getIdentifier(); assert(II && "SimpleTypoCorrector should not return this decl"); return II->getName(); } return StringRef(); } InlineCommandComment::RenderKind Sema::getInlineCommandRenderKind(StringRef Name) const { assert(Traits.getCommandInfo(Name)->IsInlineCommand); return llvm::StringSwitch(Name) .Case("b", InlineCommandComment::RenderBold) .Cases("c", "p", InlineCommandComment::RenderMonospaced) .Cases("a", "e", "em", InlineCommandComment::RenderEmphasized) .Default(InlineCommandComment::RenderNormal); } } // end namespace comments } // end namespace clang @ 1.1.1.3.4.1 log @file CommentSema.cpp was added on branch yamt-pagecache on 2014-05-22 16:18:25 +0000 @ text @d1 1074 @ 1.1.1.3.4.2 log @sync with head. for a reference, the tree before this commit was tagged as yamt-pagecache-tag8. this commit was splitted into small chunks to avoid a limitation of cvs. ("Protocol error: too many arguments") @ text @a0 1074 //===--- CommentSema.cpp - Doxygen comment semantic analysis --------------===// // // The LLVM Compiler Infrastructure // // This file is distributed under the University of Illinois Open Source // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// #include "clang/AST/CommentSema.h" #include "clang/AST/Attr.h" #include "clang/AST/CommentCommandTraits.h" #include "clang/AST/CommentDiagnostic.h" #include "clang/AST/Decl.h" #include "clang/AST/DeclTemplate.h" #include "clang/Basic/SourceManager.h" #include "clang/Lex/Preprocessor.h" #include "llvm/ADT/SmallString.h" #include "llvm/ADT/StringSwitch.h" namespace clang { namespace comments { namespace { #include "clang/AST/CommentHTMLTagsProperties.inc" } // unnamed namespace Sema::Sema(llvm::BumpPtrAllocator &Allocator, const SourceManager &SourceMgr, DiagnosticsEngine &Diags, CommandTraits &Traits, const Preprocessor *PP) : Allocator(Allocator), SourceMgr(SourceMgr), Diags(Diags), Traits(Traits), PP(PP), ThisDeclInfo(NULL), BriefCommand(NULL), HeaderfileCommand(NULL) { } void Sema::setDecl(const Decl *D) { if (!D) return; ThisDeclInfo = new (Allocator) DeclInfo; ThisDeclInfo->CommentDecl = D; ThisDeclInfo->IsFilled = false; } ParagraphComment *Sema::actOnParagraphComment( ArrayRef Content) { return new (Allocator) ParagraphComment(Content); } BlockCommandComment *Sema::actOnBlockCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { BlockCommandComment *BC = new (Allocator) BlockCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); checkContainerDecl(BC); return BC; } void Sema::actOnBlockCommandArgs(BlockCommandComment *Command, ArrayRef Args) { Command->setArgs(Args); } void Sema::actOnBlockCommandFinish(BlockCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); checkBlockCommandDuplicate(Command); if (ThisDeclInfo) { // These checks only make sense if the comment is attached to a // declaration. checkReturnsCommand(Command); checkDeprecatedCommand(Command); } } ParamCommandComment *Sema::actOnParamCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { ParamCommandComment *Command = new (Allocator) ParamCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); if (!isFunctionDecl()) Diag(Command->getLocation(), diag::warn_doc_param_not_attached_to_a_function_decl) << CommandMarker << Command->getCommandNameRange(Traits); return Command; } void Sema::checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsFunctionDeclarationCommand) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_function: DiagSelect = (!isAnyFunctionDecl() && !isFunctionTemplateDecl())? 1 : 0; break; case CommandTraits::KCI_functiongroup: DiagSelect = (!isAnyFunctionDecl() && !isFunctionTemplateDecl())? 2 : 0; break; case CommandTraits::KCI_method: DiagSelect = !isObjCMethodDecl() ? 3 : 0; break; case CommandTraits::KCI_methodgroup: DiagSelect = !isObjCMethodDecl() ? 4 : 0; break; case CommandTraits::KCI_callback: DiagSelect = !isFunctionPointerVarDecl() ? 5 : 0; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_function_method_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << (DiagSelect-1) << Comment->getSourceRange(); } void Sema::checkContainerDeclVerbatimLine(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsRecordLikeDeclarationCommand) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_class: DiagSelect = (!isClassOrStructDecl() && !isClassTemplateDecl()) ? 1 : 0; // Allow @@class command on @@interface declarations. // FIXME. Currently, \class and @@class are indistinguishable. So, // \class is also allowed on an @@interface declaration if (DiagSelect && Comment->getCommandMarker() && isObjCInterfaceDecl()) DiagSelect = 0; break; case CommandTraits::KCI_interface: DiagSelect = !isObjCInterfaceDecl() ? 2 : 0; break; case CommandTraits::KCI_protocol: DiagSelect = !isObjCProtocolDecl() ? 3 : 0; break; case CommandTraits::KCI_struct: DiagSelect = !isClassOrStructDecl() ? 4 : 0; break; case CommandTraits::KCI_union: DiagSelect = !isUnionDecl() ? 5 : 0; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_api_container_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << (DiagSelect-1) << Comment->getSourceRange(); } void Sema::checkContainerDecl(const BlockCommandComment *Comment) { const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID()); if (!Info->IsRecordLikeDetailCommand || isRecordLikeDecl()) return; unsigned DiagSelect; switch (Comment->getCommandID()) { case CommandTraits::KCI_classdesign: DiagSelect = 1; break; case CommandTraits::KCI_coclass: DiagSelect = 2; break; case CommandTraits::KCI_dependency: DiagSelect = 3; break; case CommandTraits::KCI_helper: DiagSelect = 4; break; case CommandTraits::KCI_helperclass: DiagSelect = 5; break; case CommandTraits::KCI_helps: DiagSelect = 6; break; case CommandTraits::KCI_instancesize: DiagSelect = 7; break; case CommandTraits::KCI_ownership: DiagSelect = 8; break; case CommandTraits::KCI_performance: DiagSelect = 9; break; case CommandTraits::KCI_security: DiagSelect = 10; break; case CommandTraits::KCI_superclass: DiagSelect = 11; break; default: DiagSelect = 0; break; } if (DiagSelect) Diag(Comment->getLocation(), diag::warn_doc_container_decl_mismatch) << Comment->getCommandMarker() << (DiagSelect-1) << Comment->getSourceRange(); } /// \brief Turn a string into the corresponding PassDirection or -1 if it's not /// valid. static int getParamPassDirection(StringRef Arg) { return llvm::StringSwitch(Arg) .Case("[in]", ParamCommandComment::In) .Case("[out]", ParamCommandComment::Out) .Cases("[in,out]", "[out,in]", ParamCommandComment::InOut) .Default(-1); } void Sema::actOnParamCommandDirectionArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { std::string ArgLower = Arg.lower(); int Direction = getParamPassDirection(ArgLower); if (Direction == -1) { // Try again with whitespace removed. ArgLower.erase( std::remove_if(ArgLower.begin(), ArgLower.end(), clang::isWhitespace), ArgLower.end()); Direction = getParamPassDirection(ArgLower); SourceRange ArgRange(ArgLocBegin, ArgLocEnd); if (Direction != -1) { const char *FixedName = ParamCommandComment::getDirectionAsString( (ParamCommandComment::PassDirection)Direction); Diag(ArgLocBegin, diag::warn_doc_param_spaces_in_direction) << ArgRange << FixItHint::CreateReplacement(ArgRange, FixedName); } else { Diag(ArgLocBegin, diag::warn_doc_param_invalid_direction) << ArgRange; Direction = ParamCommandComment::In; // Sane fall back. } } Command->setDirection((ParamCommandComment::PassDirection)Direction, /*Explicit=*/true); } void Sema::actOnParamCommandParamNameArg(ParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { // Parser will not feed us more arguments than needed. assert(Command->getNumArgs() == 0); if (!Command->isDirectionExplicit()) { // User didn't provide a direction argument. Command->setDirection(ParamCommandComment::In, /* Explicit = */ false); } typedef BlockCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); Command->setArgs(llvm::makeArrayRef(A, 1)); } void Sema::actOnParamCommandFinish(ParamCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); } TParamCommandComment *Sema::actOnTParamCommandStart( SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID, CommandMarkerKind CommandMarker) { TParamCommandComment *Command = new (Allocator) TParamCommandComment(LocBegin, LocEnd, CommandID, CommandMarker); if (!isTemplateOrSpecialization()) Diag(Command->getLocation(), diag::warn_doc_tparam_not_attached_to_a_template_decl) << CommandMarker << Command->getCommandNameRange(Traits); return Command; } void Sema::actOnTParamCommandParamNameArg(TParamCommandComment *Command, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { // Parser will not feed us more arguments than needed. assert(Command->getNumArgs() == 0); typedef BlockCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); Command->setArgs(llvm::makeArrayRef(A, 1)); if (!isTemplateOrSpecialization()) { // We already warned that this \\tparam is not attached to a template decl. return; } const TemplateParameterList *TemplateParameters = ThisDeclInfo->TemplateParameters; SmallVector Position; if (resolveTParamReference(Arg, TemplateParameters, &Position)) { Command->setPosition(copyArray(llvm::makeArrayRef(Position))); TParamCommandComment *&PrevCommand = TemplateParameterDocs[Arg]; if (PrevCommand) { SourceRange ArgRange(ArgLocBegin, ArgLocEnd); Diag(ArgLocBegin, diag::warn_doc_tparam_duplicate) << Arg << ArgRange; Diag(PrevCommand->getLocation(), diag::note_doc_tparam_previous) << PrevCommand->getParamNameRange(); } PrevCommand = Command; return; } SourceRange ArgRange(ArgLocBegin, ArgLocEnd); Diag(ArgLocBegin, diag::warn_doc_tparam_not_found) << Arg << ArgRange; if (!TemplateParameters || TemplateParameters->size() == 0) return; StringRef CorrectedName; if (TemplateParameters->size() == 1) { const NamedDecl *Param = TemplateParameters->getParam(0); const IdentifierInfo *II = Param->getIdentifier(); if (II) CorrectedName = II->getName(); } else { CorrectedName = correctTypoInTParamReference(Arg, TemplateParameters); } if (!CorrectedName.empty()) { Diag(ArgLocBegin, diag::note_doc_tparam_name_suggestion) << CorrectedName << FixItHint::CreateReplacement(ArgRange, CorrectedName); } return; } void Sema::actOnTParamCommandFinish(TParamCommandComment *Command, ParagraphComment *Paragraph) { Command->setParagraph(Paragraph); checkBlockCommandEmptyParagraph(Command); } InlineCommandComment *Sema::actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID) { ArrayRef Args; StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) InlineCommandComment( CommandLocBegin, CommandLocEnd, CommandID, getInlineCommandRenderKind(CommandName), Args); } InlineCommandComment *Sema::actOnInlineCommand(SourceLocation CommandLocBegin, SourceLocation CommandLocEnd, unsigned CommandID, SourceLocation ArgLocBegin, SourceLocation ArgLocEnd, StringRef Arg) { typedef InlineCommandComment::Argument Argument; Argument *A = new (Allocator) Argument(SourceRange(ArgLocBegin, ArgLocEnd), Arg); StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) InlineCommandComment( CommandLocBegin, CommandLocEnd, CommandID, getInlineCommandRenderKind(CommandName), llvm::makeArrayRef(A, 1)); } InlineContentComment *Sema::actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, StringRef CommandName) { unsigned CommandID = Traits.registerUnknownCommand(CommandName)->getID(); return actOnUnknownCommand(LocBegin, LocEnd, CommandID); } InlineContentComment *Sema::actOnUnknownCommand(SourceLocation LocBegin, SourceLocation LocEnd, unsigned CommandID) { ArrayRef Args; return new (Allocator) InlineCommandComment( LocBegin, LocEnd, CommandID, InlineCommandComment::RenderNormal, Args); } TextComment *Sema::actOnText(SourceLocation LocBegin, SourceLocation LocEnd, StringRef Text) { return new (Allocator) TextComment(LocBegin, LocEnd, Text); } VerbatimBlockComment *Sema::actOnVerbatimBlockStart(SourceLocation Loc, unsigned CommandID) { StringRef CommandName = Traits.getCommandInfo(CommandID)->Name; return new (Allocator) VerbatimBlockComment( Loc, Loc.getLocWithOffset(1 + CommandName.size()), CommandID); } VerbatimBlockLineComment *Sema::actOnVerbatimBlockLine(SourceLocation Loc, StringRef Text) { return new (Allocator) VerbatimBlockLineComment(Loc, Text); } void Sema::actOnVerbatimBlockFinish( VerbatimBlockComment *Block, SourceLocation CloseNameLocBegin, StringRef CloseName, ArrayRef Lines) { Block->setCloseName(CloseName, CloseNameLocBegin); Block->setLines(Lines); } VerbatimLineComment *Sema::actOnVerbatimLine(SourceLocation LocBegin, unsigned CommandID, SourceLocation TextBegin, StringRef Text) { VerbatimLineComment *VL = new (Allocator) VerbatimLineComment( LocBegin, TextBegin.getLocWithOffset(Text.size()), CommandID, TextBegin, Text); checkFunctionDeclVerbatimLine(VL); checkContainerDeclVerbatimLine(VL); return VL; } HTMLStartTagComment *Sema::actOnHTMLStartTagStart(SourceLocation LocBegin, StringRef TagName) { return new (Allocator) HTMLStartTagComment(LocBegin, TagName); } void Sema::actOnHTMLStartTagFinish( HTMLStartTagComment *Tag, ArrayRef Attrs, SourceLocation GreaterLoc, bool IsSelfClosing) { Tag->setAttrs(Attrs); Tag->setGreaterLoc(GreaterLoc); if (IsSelfClosing) Tag->setSelfClosing(); else if (!isHTMLEndTagForbidden(Tag->getTagName())) HTMLOpenTags.push_back(Tag); } HTMLEndTagComment *Sema::actOnHTMLEndTag(SourceLocation LocBegin, SourceLocation LocEnd, StringRef TagName) { HTMLEndTagComment *HET = new (Allocator) HTMLEndTagComment(LocBegin, LocEnd, TagName); if (isHTMLEndTagForbidden(TagName)) { Diag(HET->getLocation(), diag::warn_doc_html_end_forbidden) << TagName << HET->getSourceRange(); return HET; } bool FoundOpen = false; for (SmallVectorImpl::const_reverse_iterator I = HTMLOpenTags.rbegin(), E = HTMLOpenTags.rend(); I != E; ++I) { if ((*I)->getTagName() == TagName) { FoundOpen = true; break; } } if (!FoundOpen) { Diag(HET->getLocation(), diag::warn_doc_html_end_unbalanced) << HET->getSourceRange(); return HET; } while (!HTMLOpenTags.empty()) { const HTMLStartTagComment *HST = HTMLOpenTags.pop_back_val(); StringRef LastNotClosedTagName = HST->getTagName(); if (LastNotClosedTagName == TagName) break; if (isHTMLEndTagOptional(LastNotClosedTagName)) continue; bool OpenLineInvalid; const unsigned OpenLine = SourceMgr.getPresumedLineNumber( HST->getLocation(), &OpenLineInvalid); bool CloseLineInvalid; const unsigned CloseLine = SourceMgr.getPresumedLineNumber( HET->getLocation(), &CloseLineInvalid); if (OpenLineInvalid || CloseLineInvalid || OpenLine == CloseLine) Diag(HST->getLocation(), diag::warn_doc_html_start_end_mismatch) << HST->getTagName() << HET->getTagName() << HST->getSourceRange() << HET->getSourceRange(); else { Diag(HST->getLocation(), diag::warn_doc_html_start_end_mismatch) << HST->getTagName() << HET->getTagName() << HST->getSourceRange(); Diag(HET->getLocation(), diag::note_doc_html_end_tag) << HET->getSourceRange(); } } return HET; } FullComment *Sema::actOnFullComment( ArrayRef Blocks) { FullComment *FC = new (Allocator) FullComment(Blocks, ThisDeclInfo); resolveParamCommandIndexes(FC); return FC; } void Sema::checkBlockCommandEmptyParagraph(BlockCommandComment *Command) { if (Traits.getCommandInfo(Command->getCommandID())->IsEmptyParagraphAllowed) return; ParagraphComment *Paragraph = Command->getParagraph(); if (Paragraph->isWhitespace()) { SourceLocation DiagLoc; if (Command->getNumArgs() > 0) DiagLoc = Command->getArgRange(Command->getNumArgs() - 1).getEnd(); if (!DiagLoc.isValid()) DiagLoc = Command->getCommandNameRange(Traits).getEnd(); Diag(DiagLoc, diag::warn_doc_block_command_empty_paragraph) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange(); } } void Sema::checkReturnsCommand(const BlockCommandComment *Command) { if (!Traits.getCommandInfo(Command->getCommandID())->IsReturnsCommand) return; assert(ThisDeclInfo && "should not call this check on a bare comment"); if (isFunctionDecl()) { if (ThisDeclInfo->ReturnType->isVoidType()) { unsigned DiagKind; switch (ThisDeclInfo->CommentDecl->getKind()) { default: if (ThisDeclInfo->IsObjCMethod) DiagKind = 3; else DiagKind = 0; break; case Decl::CXXConstructor: DiagKind = 1; break; case Decl::CXXDestructor: DiagKind = 2; break; } Diag(Command->getLocation(), diag::warn_doc_returns_attached_to_a_void_function) << Command->getCommandMarker() << Command->getCommandName(Traits) << DiagKind << Command->getSourceRange(); } return; } else if (isObjCPropertyDecl()) return; Diag(Command->getLocation(), diag::warn_doc_returns_not_attached_to_a_function_decl) << Command->getCommandMarker() << Command->getCommandName(Traits) << Command->getSourceRange(); } void Sema::checkBlockCommandDuplicate(const BlockCommandComment *Command) { const CommandInfo *Info = Traits.getCommandInfo(Command->getCommandID()); const BlockCommandComment *PrevCommand = NULL; if (Info->IsBriefCommand) { if (!BriefCommand) { BriefCommand = Command; return; } PrevCommand = BriefCommand; } else if (Info->IsHeaderfileCommand) { if (!HeaderfileCommand) { HeaderfileCommand = Command; return; } PrevCommand = HeaderfileCommand; } else { // We don't want to check this command for duplicates. return; } StringRef CommandName = Command->getCommandName(Traits); StringRef PrevCommandName = PrevCommand->getCommandName(Traits); Diag(Command->getLocation(), diag::warn_doc_block_command_duplicate) << Command->getCommandMarker() << CommandName << Command->getSourceRange(); if (CommandName == PrevCommandName) Diag(PrevCommand->getLocation(), diag::note_doc_block_command_previous) << PrevCommand->getCommandMarker() << PrevCommandName << PrevCommand->getSourceRange(); else Diag(PrevCommand->getLocation(), diag::note_doc_block_command_previous_alias) << PrevCommand->getCommandMarker() << PrevCommandName << CommandName; } void Sema::checkDeprecatedCommand(const BlockCommandComment *Command) { if (!Traits.getCommandInfo(Command->getCommandID())->IsDeprecatedCommand) return; assert(ThisDeclInfo && "should not call this check on a bare comment"); const Decl *D = ThisDeclInfo->CommentDecl; if (!D) return; if (D->hasAttr() || D->hasAttr() || D->hasAttr()) return; Diag(Command->getLocation(), diag::warn_doc_deprecated_not_sync) << Command->getSourceRange(); // Try to emit a fixit with a deprecation attribute. if (const FunctionDecl *FD = dyn_cast(D)) { // Don't emit a Fix-It for non-member function definitions. GCC does not // accept attributes on them. const DeclContext *Ctx = FD->getDeclContext(); if ((!Ctx || !Ctx->isRecord()) && FD->doesThisDeclarationHaveABody()) return; StringRef AttributeSpelling = "__attribute__((deprecated))"; if (PP) { TokenValue Tokens[] = { tok::kw___attribute, tok::l_paren, tok::l_paren, PP->getIdentifierInfo("deprecated"), tok::r_paren, tok::r_paren }; StringRef MacroName = PP->getLastMacroWithSpelling(FD->getLocation(), Tokens); if (!MacroName.empty()) AttributeSpelling = MacroName; } SmallString<64> TextToInsert(" "); TextToInsert += AttributeSpelling; Diag(FD->getLocEnd(), diag::note_add_deprecation_attr) << FixItHint::CreateInsertion(FD->getLocEnd().getLocWithOffset(1), TextToInsert); } } void Sema::resolveParamCommandIndexes(const FullComment *FC) { if (!isFunctionDecl()) { // We already warned that \\param commands are not attached to a function // decl. return; } SmallVector UnresolvedParamCommands; // Comment AST nodes that correspond to \c ParamVars for which we have // found a \\param command or NULL if no documentation was found so far. SmallVector ParamVarDocs; ArrayRef ParamVars = getParamVars(); ParamVarDocs.resize(ParamVars.size(), NULL); // First pass over all \\param commands: resolve all parameter names. for (Comment::child_iterator I = FC->child_begin(), E = FC->child_end(); I != E; ++I) { ParamCommandComment *PCC = dyn_cast(*I); if (!PCC || !PCC->hasParamName()) continue; StringRef ParamName = PCC->getParamNameAsWritten(); // Check that referenced parameter name is in the function decl. const unsigned ResolvedParamIndex = resolveParmVarReference(ParamName, ParamVars); if (ResolvedParamIndex == ParamCommandComment::VarArgParamIndex) { PCC->setIsVarArgParam(); continue; } if (ResolvedParamIndex == ParamCommandComment::InvalidParamIndex) { UnresolvedParamCommands.push_back(PCC); continue; } PCC->setParamIndex(ResolvedParamIndex); if (ParamVarDocs[ResolvedParamIndex]) { SourceRange ArgRange = PCC->getParamNameRange(); Diag(ArgRange.getBegin(), diag::warn_doc_param_duplicate) << ParamName << ArgRange; ParamCommandComment *PrevCommand = ParamVarDocs[ResolvedParamIndex]; Diag(PrevCommand->getLocation(), diag::note_doc_param_previous) << PrevCommand->getParamNameRange(); } ParamVarDocs[ResolvedParamIndex] = PCC; } // Find parameter declarations that have no corresponding \\param. SmallVector OrphanedParamDecls; for (unsigned i = 0, e = ParamVarDocs.size(); i != e; ++i) { if (!ParamVarDocs[i]) OrphanedParamDecls.push_back(ParamVars[i]); } // Second pass over unresolved \\param commands: do typo correction. // Suggest corrections from a set of parameter declarations that have no // corresponding \\param. for (unsigned i = 0, e = UnresolvedParamCommands.size(); i != e; ++i) { const ParamCommandComment *PCC = UnresolvedParamCommands[i]; SourceRange ArgRange = PCC->getParamNameRange(); StringRef ParamName = PCC->getParamNameAsWritten(); Diag(ArgRange.getBegin(), diag::warn_doc_param_not_found) << ParamName << ArgRange; // All parameters documented -- can't suggest a correction. if (OrphanedParamDecls.size() == 0) continue; unsigned CorrectedParamIndex = ParamCommandComment::InvalidParamIndex; if (OrphanedParamDecls.size() == 1) { // If one parameter is not documented then that parameter is the only // possible suggestion. CorrectedParamIndex = 0; } else { // Do typo correction. CorrectedParamIndex = correctTypoInParmVarReference(ParamName, OrphanedParamDecls); } if (CorrectedParamIndex != ParamCommandComment::InvalidParamIndex) { const ParmVarDecl *CorrectedPVD = OrphanedParamDecls[CorrectedParamIndex]; if (const IdentifierInfo *CorrectedII = CorrectedPVD->getIdentifier()) Diag(ArgRange.getBegin(), diag::note_doc_param_name_suggestion) << CorrectedII->getName() << FixItHint::CreateReplacement(ArgRange, CorrectedII->getName()); } } } bool Sema::isFunctionDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->getKind() == DeclInfo::FunctionKind; } bool Sema::isAnyFunctionDecl() { return isFunctionDecl() && ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isFunctionOrMethodVariadic() { if (!isAnyFunctionDecl() && !isObjCMethodDecl()) return false; if (const FunctionDecl *FD = dyn_cast(ThisDeclInfo->CurrentDecl)) return FD->isVariadic(); if (const ObjCMethodDecl *MD = dyn_cast(ThisDeclInfo->CurrentDecl)) return MD->isVariadic(); return false; } bool Sema::isObjCMethodDecl() { return isFunctionDecl() && ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isFunctionPointerVarDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (ThisDeclInfo->getKind() == DeclInfo::VariableKind) { if (const VarDecl *VD = dyn_cast_or_null(ThisDeclInfo->CurrentDecl)) { QualType QT = VD->getType(); return QT->isFunctionPointerType(); } } return false; } bool Sema::isObjCPropertyDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl->getKind() == Decl::ObjCProperty; } bool Sema::isTemplateOrSpecialization() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->getTemplateKind() != DeclInfo::NotTemplate; } bool Sema::isRecordLikeDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return isUnionDecl() || isClassOrStructDecl() || isObjCInterfaceDecl() || isObjCProtocolDecl(); } bool Sema::isUnionDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); if (const RecordDecl *RD = dyn_cast_or_null(ThisDeclInfo->CurrentDecl)) return RD->isUnion(); return false; } bool Sema::isClassOrStructDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl) && !isUnionDecl(); } bool Sema::isClassTemplateDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && (isa(ThisDeclInfo->CurrentDecl)); } bool Sema::isFunctionTemplateDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && (isa(ThisDeclInfo->CurrentDecl)); } bool Sema::isObjCInterfaceDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } bool Sema::isObjCProtocolDecl() { if (!ThisDeclInfo) return false; if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->CurrentDecl && isa(ThisDeclInfo->CurrentDecl); } ArrayRef Sema::getParamVars() { if (!ThisDeclInfo->IsFilled) inspectThisDecl(); return ThisDeclInfo->ParamVars; } void Sema::inspectThisDecl() { ThisDeclInfo->fill(); } unsigned Sema::resolveParmVarReference(StringRef Name, ArrayRef ParamVars) { for (unsigned i = 0, e = ParamVars.size(); i != e; ++i) { const IdentifierInfo *II = ParamVars[i]->getIdentifier(); if (II && II->getName() == Name) return i; } if (Name == "..." && isFunctionOrMethodVariadic()) return ParamCommandComment::VarArgParamIndex; return ParamCommandComment::InvalidParamIndex; } namespace { class SimpleTypoCorrector { StringRef Typo; const unsigned MaxEditDistance; const NamedDecl *BestDecl; unsigned BestEditDistance; unsigned BestIndex; unsigned NextIndex; public: SimpleTypoCorrector(StringRef Typo) : Typo(Typo), MaxEditDistance((Typo.size() + 2) / 3), BestDecl(NULL), BestEditDistance(MaxEditDistance + 1), BestIndex(0), NextIndex(0) { } void addDecl(const NamedDecl *ND); const NamedDecl *getBestDecl() const { if (BestEditDistance > MaxEditDistance) return NULL; return BestDecl; } unsigned getBestDeclIndex() const { assert(getBestDecl()); return BestIndex; } }; void SimpleTypoCorrector::addDecl(const NamedDecl *ND) { unsigned CurrIndex = NextIndex++; const IdentifierInfo *II = ND->getIdentifier(); if (!II) return; StringRef Name = II->getName(); unsigned MinPossibleEditDistance = abs((int)Name.size() - (int)Typo.size()); if (MinPossibleEditDistance > 0 && Typo.size() / MinPossibleEditDistance < 3) return; unsigned EditDistance = Typo.edit_distance(Name, true, MaxEditDistance); if (EditDistance < BestEditDistance) { BestEditDistance = EditDistance; BestDecl = ND; BestIndex = CurrIndex; } } } // unnamed namespace unsigned Sema::correctTypoInParmVarReference( StringRef Typo, ArrayRef ParamVars) { SimpleTypoCorrector Corrector(Typo); for (unsigned i = 0, e = ParamVars.size(); i != e; ++i) Corrector.addDecl(ParamVars[i]); if (Corrector.getBestDecl()) return Corrector.getBestDeclIndex(); else return ParamCommandComment::InvalidParamIndex; } namespace { bool ResolveTParamReferenceHelper( StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl *Position) { for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) { const NamedDecl *Param = TemplateParameters->getParam(i); const IdentifierInfo *II = Param->getIdentifier(); if (II && II->getName() == Name) { Position->push_back(i); return true; } if (const TemplateTemplateParmDecl *TTP = dyn_cast(Param)) { Position->push_back(i); if (ResolveTParamReferenceHelper(Name, TTP->getTemplateParameters(), Position)) return true; Position->pop_back(); } } return false; } } // unnamed namespace bool Sema::resolveTParamReference( StringRef Name, const TemplateParameterList *TemplateParameters, SmallVectorImpl *Position) { Position->clear(); if (!TemplateParameters) return false; return ResolveTParamReferenceHelper(Name, TemplateParameters, Position); } namespace { void CorrectTypoInTParamReferenceHelper( const TemplateParameterList *TemplateParameters, SimpleTypoCorrector &Corrector) { for (unsigned i = 0, e = TemplateParameters->size(); i != e; ++i) { const NamedDecl *Param = TemplateParameters->getParam(i); Corrector.addDecl(Param); if (const TemplateTemplateParmDecl *TTP = dyn_cast(Param)) CorrectTypoInTParamReferenceHelper(TTP->getTemplateParameters(), Corrector); } } } // unnamed namespace StringRef Sema::correctTypoInTParamReference( StringRef Typo, const TemplateParameterList *TemplateParameters) { SimpleTypoCorrector Corrector(Typo); CorrectTypoInTParamReferenceHelper(TemplateParameters, Corrector); if (const NamedDecl *ND = Corrector.getBestDecl()) { const IdentifierInfo *II = ND->getIdentifier(); assert(II && "SimpleTypoCorrector should not return this decl"); return II->getName(); } return StringRef(); } InlineCommandComment::RenderKind Sema::getInlineCommandRenderKind(StringRef Name) const { assert(Traits.getCommandInfo(Name)->IsInlineCommand); return llvm::StringSwitch(Name) .Case("b", InlineCommandComment::RenderBold) .Cases("c", "p", InlineCommandComment::RenderMonospaced) .Cases("a", "e", "em", InlineCommandComment::RenderEmphasized) .Default(InlineCommandComment::RenderNormal); } } // end namespace comments } // end namespace clang @