r176667 - HeaderDoc: Support more of HeaderDoc documentation
jahanian
fjahanian at apple.com
Thu Mar 7 17:57:23 PST 2013
On Mar 7, 2013, at 3:51 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> 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.
It is not only ObjC objects but also class/struct/union objects. So, I probably
should use something like IsObjectDeclarationCommand?
>
>>
>> /// \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.
OK.
>
>>
>> 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.
Comment->getCommandID() returns the static ID number. But I also
need to know the static ID number for "interface", etc. to compare them against.
How do I get the static IDs for the commands I am interested in?
- Fariborz
More information about the cfe-commits
mailing list