r176667 - HeaderDoc: Support more of HeaderDoc documentation
Dmitri Gribenko
gribozavr at gmail.com
Thu Mar 7 15:51:12 PST 2013
Hi Fariborz,
On Fri, Mar 8, 2013 at 1:33 AM, Fariborz Jahanian <fjahanian at apple.com> wrote:
> Author: fjahanian
> Date: Thu Mar 7 17:33:11 2013
> New Revision: 176667
>
> URL: http://llvm.org/viewvc/llvm-project?rev=176667&view=rev
> Log:
> HeaderDoc: Support more of HeaderDoc documentation
> commands; top level tags such as @interface and
> their 2nd level tags such as @coclass, etc.
> // rdar://12379114
>
> Modified:
> cfe/trunk/include/clang/AST/CommentCommandTraits.h
> cfe/trunk/include/clang/AST/CommentCommands.td
> cfe/trunk/include/clang/AST/CommentSema.h
> cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td
> cfe/trunk/lib/AST/CommentSema.cpp
> cfe/trunk/test/Sema/warn-documentation.cpp
> cfe/trunk/test/Sema/warn-documentation.m
> cfe/trunk/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
>
> Modified: cfe/trunk/include/clang/AST/CommentCommandTraits.h
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/CommentCommandTraits.h?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/AST/CommentCommandTraits.h (original)
> +++ cfe/trunk/include/clang/AST/CommentCommandTraits.h Thu Mar 7 17:33:11 2013
> @@ -101,8 +101,15 @@ struct CommandInfo {
> /// \endcode
> unsigned IsDeclarationCommand : 1;
>
> - /// \brief True if verbatim-like line command is a function declaraton.
> + /// \brief True if verbatim-like line command is a function declaration.
> unsigned IsFunctionDeclarationCommand : 1;
> +
> + /// \brief True if block command is further describing a container API; such
> + /// as @coclass, @classdesign, etc.
> + unsigned IsContainerDetailCommand : 1;
> +
> + /// \brief True if block command is a container API; such as @interface.
> + unsigned IsContainerDeclarationCommand : 1;
Is the 'container' the best term for this? I don't know ObjC, but a
container is something like std::vector for me.
>
> /// \brief True if this command is unknown. This \c CommandInfo object was
> /// created during parsing.
>
> Modified: cfe/trunk/include/clang/AST/CommentCommands.td
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/CommentCommands.td?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/AST/CommentCommands.td (original)
> +++ cfe/trunk/include/clang/AST/CommentCommands.td Thu Mar 7 17:33:11 2013
> @@ -25,6 +25,8 @@ class Command<string name> {
> bit IsVerbatimLineCommand = 0;
> bit IsDeclarationCommand = 0;
> bit IsFunctionDeclarationCommand = 0;
> + bit IsContainerDetailCommand = 0;
> + bit IsContainerDeclarationCommand = 0;
> }
>
> class InlineCommand<string name> : Command<name> {
> @@ -66,6 +68,12 @@ class FunctionDeclarationVerbatimLineCom
> let IsFunctionDeclarationCommand = 1;
> }
>
> +class ContainerDeclarationVerbatimLineCommand<string name> :
> + VerbatimLineCommand<name> {
> + let IsDeclarationCommand = 1;
> + let IsContainerDeclarationCommand = 1;
> +}
> +
> //===----------------------------------------------------------------------===//
> // InlineCommand
> //===----------------------------------------------------------------------===//
> @@ -181,9 +189,11 @@ def Typedef : DeclarationVerbatimLineC
> def Var : DeclarationVerbatimLineCommand<"var">;
>
> // HeaderDoc commands.
> -def Class : DeclarationVerbatimLineCommand<"class">;
> -def Interface : DeclarationVerbatimLineCommand<"interface">;
> -def Protocol : DeclarationVerbatimLineCommand<"protocol">;
> +def Class : ContainerDeclarationVerbatimLineCommand<"class">;
> +def Interface : ContainerDeclarationVerbatimLineCommand<"interface">;
> +def Protocol : ContainerDeclarationVerbatimLineCommand<"protocol">;
> +def Struct : ContainerDeclarationVerbatimLineCommand<"struct">;
> +def Union : ContainerDeclarationVerbatimLineCommand<"union">;
> def Category : DeclarationVerbatimLineCommand<"category">;
> def Template : DeclarationVerbatimLineCommand<"template">;
> def Function : FunctionDeclarationVerbatimLineCommand<"function">;
> @@ -191,7 +201,38 @@ def Method : FunctionDeclarationVerba
> def Callback : FunctionDeclarationVerbatimLineCommand<"callback">;
> def Const : DeclarationVerbatimLineCommand<"const">;
> def Constant : DeclarationVerbatimLineCommand<"constant">;
> -def Struct : DeclarationVerbatimLineCommand<"struct">;
> -def Union : DeclarationVerbatimLineCommand<"union">;
> def Enum : DeclarationVerbatimLineCommand<"enum">;
>
> +def ClassDesign : BlockCommand<"classdesign"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def CoClass : BlockCommand<"coclass"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def Dependency : BlockCommand<"dependency"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def Helper : BlockCommand<"helper"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def HelperClass : BlockCommand<"helperclass"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def Helps : BlockCommand<"helps"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def InstanceSize : BlockCommand<"instancesize"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def Ownership : BlockCommand<"ownership"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def Performance : BlockCommand<"performance"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def Security : BlockCommand<"security"> {
> + let IsContainerDetailCommand = 1;
> +}
> +def SuperClass : BlockCommand<"superclass"> {
> + let IsContainerDetailCommand = 1;
> +}
Please clean this up by defining a class in .td that is derived from
BlockCommand.
>
> Modified: cfe/trunk/include/clang/AST/CommentSema.h
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/AST/CommentSema.h?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/AST/CommentSema.h (original)
> +++ cfe/trunk/include/clang/AST/CommentSema.h Thu Mar 7 17:33:11 2013
> @@ -200,6 +200,10 @@ public:
> void checkDeprecatedCommand(const BlockCommandComment *Comment);
>
> void checkFunctionDeclVerbatimLine(const BlockCommandComment *Comment);
> +
> + void checkContainerDeclVerbatimLine(const BlockCommandComment *Comment);
> +
> + void checkContainerDecl(const BlockCommandComment *Comment);
>
> /// Resolve parameter names to parameter indexes in function declaration.
> /// Emit diagnostics about unknown parametrs.
> @@ -211,6 +215,11 @@ public:
> bool isObjCMethodDecl();
> bool isObjCPropertyDecl();
> bool isTemplateOrSpecialization();
> + bool isContainerDecl();
> + bool isClassStructDecl();
> + bool isUnionDecl();
> + bool isObjCInterfaceDecl();
> + bool isObjCProtocolDecl();
>
> ArrayRef<const ParmVarDecl *> getParamVars();
>
>
> Modified: cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td (original)
> +++ cfe/trunk/include/clang/Basic/DiagnosticCommentKinds.td Thu Mar 7 17:33:11 2013
> @@ -79,6 +79,18 @@ def warn_doc_function_method_decl_mismat
> "%select{a function|an Objective-C method|a pointer to function}2 declaration">,
> InGroup<Documentation>, DefaultIgnore;
>
> +def warn_doc_api_container_decl_mismatch : Warning<
> + "'%select{\\|@}0%select{class|interface|protocol|struct|union}1' "
> + "command should not be used in a comment attached to a "
> + "non-%select{class|interface|protocol|struct|union}2 declaration">,
> + InGroup<Documentation>, DefaultIgnore;
> +
> +def warn_doc_container_decl_mismatch : Warning<
> + "'%select{\\|@}0%select{classdesign|coclass|dependency|helper"
> + "|helperclass|helps|instancesize|ownership|performance|security|superclass}1' "
> + "command should not be used in a comment attached to a non-container declaration">,
> + InGroup<Documentation>, DefaultIgnore;
> +
> def warn_doc_param_duplicate : Warning<
> "parameter '%0' is already documented">,
> InGroup<Documentation>, DefaultIgnore;
>
> Modified: cfe/trunk/lib/AST/CommentSema.cpp
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/AST/CommentSema.cpp?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/lib/AST/CommentSema.cpp (original)
> +++ cfe/trunk/lib/AST/CommentSema.cpp Thu Mar 7 17:33:11 2013
> @@ -52,8 +52,11 @@ BlockCommandComment *Sema::actOnBlockCom
> SourceLocation LocEnd,
> unsigned CommandID,
> CommandMarkerKind CommandMarker) {
> - return new (Allocator) BlockCommandComment(LocBegin, LocEnd, CommandID,
> - CommandMarker);
> + BlockCommandComment *BC = new (Allocator) BlockCommandComment(LocBegin, LocEnd,
> + CommandID,
> + CommandMarker);
> + checkContainerDecl(BC);
> + return BC;
> }
>
> void Sema::actOnBlockCommandArgs(BlockCommandComment *Command,
> @@ -105,6 +108,52 @@ void Sema::checkFunctionDeclVerbatimLine
> << (DiagSelect-1) << (DiagSelect-1)
> << Comment->getSourceRange();
> }
> +
> +void Sema::checkContainerDeclVerbatimLine(const BlockCommandComment *Comment) {
> + const CommandInfo *Info = Traits.getCommandInfo(Comment->getCommandID());
> + if (!Info->IsContainerDeclarationCommand)
> + return;
> + StringRef Name = Info->Name;
> + unsigned DiagSelect = llvm::StringSwitch<unsigned>(Name)
> + .Case("class", !isClassStructDecl() ? 1 : 0)
> + .Case("interface", !isObjCInterfaceDecl() ? 2 : 0)
> + .Case("protocol", !isObjCProtocolDecl() ? 3 : 0)
> + .Case("struct", !isClassStructDecl() ? 4 : 0)
> + .Case("union", !isUnionDecl() ? 5 : 0)
> + .Default(0);
Please don't StringSwitch on the command name. Statically known
commands have IDs. See
CommentASTToXMLConverter::visitBlockCommandComment for an example of
how to use these.
> +
> + 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->IsContainerDetailCommand || isContainerDecl())
> + return;
> + StringRef Name = Info->Name;
> + unsigned DiagSelect = llvm::StringSwitch<unsigned>(Name)
> + .Case("classdesign", 1)
> + .Case("coclass", 2)
> + .Case("dependency", 3)
> + .Case("helper", 4)
> + .Case("helperclass", 5)
> + .Case("helps", 6)
> + .Case("instancesize", 7)
> + .Case("ownership", 8)
> + .Case("performance", 9)
> + .Case("security", 10)
> + .Case("superclass", 11)
> + .Default(0);
Same here.
> +
> + if (DiagSelect)
> + Diag(Comment->getLocation(), diag::warn_doc_container_decl_mismatch)
> + << Comment->getCommandMarker()
> + << (DiagSelect-1)
> + << Comment->getSourceRange();
> +}
>
> void Sema::actOnParamCommandDirectionArg(ParamCommandComment *Command,
> SourceLocation ArgLocBegin,
> @@ -362,6 +411,7 @@ VerbatimLineComment *Sema::actOnVerbatim
> TextBegin,
> Text);
> checkFunctionDeclVerbatimLine(VL);
> + checkContainerDeclVerbatimLine(VL);
> return VL;
> }
>
> @@ -735,6 +785,54 @@ bool Sema::isTemplateOrSpecialization()
> return ThisDeclInfo->getTemplateKind() != DeclInfo::NotTemplate;
> }
>
> +bool Sema::isContainerDecl() {
> + if (!ThisDeclInfo)
> + return false;
> + if (!ThisDeclInfo->IsFilled)
> + inspectThisDecl();
> + return isUnionDecl() || isClassStructDecl()
> + || isObjCInterfaceDecl() || isObjCProtocolDecl();
> +}
> +
> +bool Sema::isUnionDecl() {
> + if (!ThisDeclInfo)
> + return false;
> + if (!ThisDeclInfo->IsFilled)
> + inspectThisDecl();
> + if (const RecordDecl *RD =
> + dyn_cast_or_null<RecordDecl>(ThisDeclInfo->CurrentDecl))
> + return RD->isUnion();
> + return false;
> +}
> +
> +bool Sema::isClassStructDecl() {
isClassOrStructDecl() would be a better name.
> + if (!ThisDeclInfo)
> + return false;
> + if (!ThisDeclInfo->IsFilled)
> + inspectThisDecl();
> + return ThisDeclInfo->CurrentDecl &&
> + isa<RecordDecl>(ThisDeclInfo->CurrentDecl) &&
> + !isUnionDecl();
> +}
> +
> +bool Sema::isObjCInterfaceDecl() {
> + if (!ThisDeclInfo)
> + return false;
> + if (!ThisDeclInfo->IsFilled)
> + inspectThisDecl();
> + return ThisDeclInfo->CurrentDecl &&
> + isa<ObjCInterfaceDecl>(ThisDeclInfo->CurrentDecl);
> +}
> +
> +bool Sema::isObjCProtocolDecl() {
> + if (!ThisDeclInfo)
> + return false;
> + if (!ThisDeclInfo->IsFilled)
> + inspectThisDecl();
> + return ThisDeclInfo->CurrentDecl &&
> + isa<ObjCProtocolDecl>(ThisDeclInfo->CurrentDecl);
> +}
> +
> ArrayRef<const ParmVarDecl *> Sema::getParamVars() {
> if (!ThisDeclInfo->IsFilled)
> inspectThisDecl();
>
> Modified: cfe/trunk/test/Sema/warn-documentation.cpp
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/test/Sema/warn-documentation.cpp?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/test/Sema/warn-documentation.cpp (original)
> +++ cfe/trunk/test/Sema/warn-documentation.cpp Thu Mar 7 17:33:11 2013
> @@ -922,3 +922,31 @@ int test_nocrash12();
> // expected-warning at +1 {{empty paragraph passed to '@param' command}}
> ///@param x at param y
> int test_nocrash13(int x, int y);
> +
> +// rdar://12379114
> +// expected-warning at +2 {{'@union' command should not be used in a comment attached to a non-union declaration}}
> +/*!
> + @union U This is new
> +*/
> +struct U { int iS; };
> +
> +/*!
> + @union U1
> +*/
> +union U1 {int i; };
> +
> +// expected-warning at +2 {{'@struct' command should not be used in a comment attached to a non-struct declaration}}
> +/*!
> + @struct S2
> +*/
> +union S2 {};
> +
> +/*!
> + @class C1
> +*/
> +class C1;
> +
> +/*!
> + @struct S3;
> +*/
> +class S3;
>
> Modified: cfe/trunk/test/Sema/warn-documentation.m
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/test/Sema/warn-documentation.m?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/test/Sema/warn-documentation.m (original)
> +++ cfe/trunk/test/Sema/warn-documentation.m Thu Mar 7 17:33:11 2013
> @@ -105,3 +105,55 @@ typedef int (^test_param1)(int aaa, int
> typedef id ID;
> - (unsigned) Base64EncodeEx : (ID)Arg;
> @end
> +
> +// rdar://12379114
> +// expected-warning at +5 {{'@interface' command should not be used in a comment attached to a non-interface declaration}}
> +// expected-warning at +5 {{'@classdesign' command should not be used in a comment attached to a non-container declaration}}
> +// expected-warning at +5 {{'@coclass' command should not be used in a comment attached to a non-container declaration}}
> + at interface NSObject @end
> +/*!
> + at interface IOCommandGate
> + at classdesign Multiple paragraphs go here.
> + at coclass myCoClass
> +*/
> +
> +typedef id OBJ;
> + at interface IOCommandGate : NSObject {
> + OBJ iv;
> +}
> + at end
> +
> +// expected-warning at +2 {{'@protocol' command should not be used in a comment attached to a non-protocol declaration}}
> +/*!
> + at protocol PROTO
> +*/
> +struct S;
> +
> +/*!
> + @interface NSArray This is an array
> +*/
> + at class NSArray;
> + at interface NSArray @end
> +
> +/*!
> + at interface NSMutableArray
> + at super NSArray
> +*/
> + at interface NSMutableArray : NSArray @end
> +
> +/*!
> + @protocol MyProto
> +*/
> + at protocol MyProto @end
> +
> +// expected-warning at +2 {{'@protocol' command should not be used in a comment attached to a non-protocol declaration}}
> +/*!
> + @protocol MyProto
> +*/
> + at interface INTF <MyProto> @end
> +
> +// expected-warning at +2 {{'@struct' command should not be used in a comment attached to a non-struct declaration}}
> +/*!
> + @struct S1 THIS IS IT
> +*/
> + at interface S1 @end
>
> Modified: cfe/trunk/utils/TableGen/ClangCommentCommandInfoEmitter.cpp
> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/utils/TableGen/ClangCommentCommandInfoEmitter.cpp?rev=176667&r1=176666&r2=176667&view=diff
> ==============================================================================
> --- cfe/trunk/utils/TableGen/ClangCommentCommandInfoEmitter.cpp (original)
> +++ cfe/trunk/utils/TableGen/ClangCommentCommandInfoEmitter.cpp Thu Mar 7 17:33:11 2013
> @@ -48,6 +48,8 @@ void EmitClangCommentCommandInfo(RecordK
> << Tag.getValueAsBit("IsVerbatimLineCommand") << ", "
> << Tag.getValueAsBit("IsDeclarationCommand") << ", "
> << Tag.getValueAsBit("IsFunctionDeclarationCommand") << ", "
> + << Tag.getValueAsBit("IsContainerDetailCommand") << ", "
> + << Tag.getValueAsBit("IsContainerDeclarationCommand") << ", "
> << /* IsUnknownCommand = */ "0"
> << " }";
> if (i + 1 != e)
Dmitri
--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
More information about the cfe-commits
mailing list