r176667 - HeaderDoc: Support more of HeaderDoc documentation
Fariborz Jahanian
fjahanian at apple.com
Thu Mar 7 15:33:11 PST 2013
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;
/// \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;
+}
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);
+
+ 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);
+
+ 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() {
+ 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)
More information about the cfe-commits
mailing list