From 14ec3f3acb46c7049256d87784ee44e1f96d0cd6 Mon Sep 17 00:00:00 2001 From: Fariborz Jahanian Date: Mon, 15 Oct 2012 18:58:50 +0000 Subject: [PATCH] structured document comment: patch to provide comment for overriding function template when comment is comming from overridden declaration. // rdar://12378793 llvm-svn: 165953 --- clang/include/clang/AST/Comment.h | 4 +- clang/lib/AST/Comment.cpp | 15 +++++ clang/lib/AST/CommentDumper.cpp | 2 +- clang/test/Index/overriding-ftemplate-comments.cpp | 78 ++++++++++++++++++++++ clang/test/Index/overriding-method-comments.mm | 13 ++++ clang/tools/libclang/CXComment.cpp | 6 +- clang/unittests/AST/CommentParser.cpp | 2 +- 7 files changed, 112 insertions(+), 8 deletions(-) create mode 100644 clang/test/Index/overriding-ftemplate-comments.cpp diff --git a/clang/include/clang/AST/Comment.h b/clang/include/clang/AST/Comment.h index b946816..00db117 100644 --- a/clang/include/clang/AST/Comment.h +++ b/clang/include/clang/AST/Comment.h @@ -759,9 +759,7 @@ public: return getNumArgs() > 0; } - StringRef getParamName() const { - return Args[0].Text; - } + StringRef getParamName(comments::FullComment *FC) const; SourceRange getParamNameRange() const { return Args[0].Range; diff --git a/clang/lib/AST/Comment.cpp b/clang/lib/AST/Comment.cpp index a443b91..a235b60 100644 --- a/clang/lib/AST/Comment.cpp +++ b/clang/lib/AST/Comment.cpp @@ -310,6 +310,21 @@ StringRef ParamCommandComment::getParamName(comments::FullComment *FC) const { return Args[0].Text; } +StringRef TParamCommandComment::getParamName(comments::FullComment *FC) const { + if (FC && isPositionValid()) { + const TemplateParameterList *TPL = FC->getThisDeclInfo()->TemplateParameters; + for (unsigned i = 0, e = getDepth(); i != e; ++i) { + if (i == e-1) + return TPL->getParam(getIndex(i))->getName(); + const NamedDecl *Param = TPL->getParam(getIndex(i)); + if (const TemplateTemplateParmDecl *TTP = + dyn_cast(Param)) + TPL = TTP->getTemplateParameters(); + } + } + return Args[0].Text; +} + } // end namespace comments } // end namespace clang diff --git a/clang/lib/AST/CommentDumper.cpp b/clang/lib/AST/CommentDumper.cpp index 36261c4..4f51cd5 100644 --- a/clang/lib/AST/CommentDumper.cpp +++ b/clang/lib/AST/CommentDumper.cpp @@ -197,7 +197,7 @@ void CommentDumper::visitTParamCommandComment(const TParamCommandComment *C) { dumpComment(C); if (C->hasParamName()) { - OS << " Param=\"" << C->getParamName() << "\""; + OS << " Param=\"" << C->getParamName(const_cast(FC)) << "\""; } if (C->isPositionValid()) { diff --git a/clang/test/Index/overriding-ftemplate-comments.cpp b/clang/test/Index/overriding-ftemplate-comments.cpp new file mode 100644 index 0000000..6e27b8a --- /dev/null +++ b/clang/test/Index/overriding-ftemplate-comments.cpp @@ -0,0 +1,78 @@ +// RUN: rm -rf %t +// RUN: mkdir %t +// RUN: c-index-test -test-load-source all -comments-xml-schema=%S/../../bindings/xml/comment-xml-schema.rng %s > %t/out +// RUN: FileCheck %s < %t/out +// Test to search overridden methods for documentation when overriding method has none. rdar://12378793 + +// Ensure that XML we generate is not invalid. +// RUN: FileCheck %s -check-prefix=WRONG < %t/out +// WRONG-NOT: CommentXMLInvalid + +/// \tparam +/// \param AAA Blah blah +template +void comment_to_html_conversion_17(T AAA); + +template +void comment_to_html_conversion_17(T PPP); + +/// \tparam BBB Bbb +/// \tparam AAA Aaa +template +void comment_to_html_conversion_19(AAA aaa, BBB bbb); + +template +void comment_to_html_conversion_19(PPP aaa, QQQ bbb); + +/// \tparam BBB Bbb +/// \tparam UUU Zzz +/// \tparam CCC Ccc +/// \tparam AAA Aaa +template +void comment_to_html_conversion_20(AAA aaa, BBB bbb); + +template +void comment_to_html_conversion_20(PPP aaa, QQQ bbb); + +/// \tparam AAA Aaa +/// \tparam BBB Bbb +/// \tparam CCC Ccc +/// \tparam DDD Ddd +template class DDD, class BBB> class AAA> +void comment_to_html_conversion_21(); + +template class SSS, class QQQ> class PPP> +void comment_to_html_conversion_21(); + +/// \tparam C1 Ccc 1 +/// \tparam AAA Zzz +/// \tparam C2 Ccc 2 +/// \tparam C3 Ccc 3 +/// \tparam C4 Ccc 4 +/// \tparam BBB Bbb +template class BBB> class AAA> +void comment_to_html_conversion_22(); + + +template class QQQ> class PPP> +void comment_to_html_conversion_22(); + +// CHECK: FunctionTemplate=comment_to_html_conversion_17:14:6 RawComment=[/// \tparam\n/// \param AAA Blah blah] RawCommentRange=[11:1 - 12:25] FullCommentAsHTML=[
AAA
Blah blah
] FullCommentAsXML=[comment_to_html_conversion_17c:@FT@>1#Tcomment_to_html_conversion_17#t0.0#AAA0in Blah blah + +// CHECK: FunctionTemplate=comment_to_html_conversion_17:17:6 RawComment=[/// \tparam\n/// \param AAA Blah blah] RawCommentRange=[11:1 - 12:25] FullCommentAsHTML=[
PPP
Blah blah
] FullCommentAsXML=[comment_to_html_conversion_17c:@FT@>1#Tcomment_to_html_conversion_17#t0.0#PPP0in Blah blah + +// CHECK: FunctionTemplate=comment_to_html_conversion_19:22:6 RawComment=[/// \tparam BBB Bbb\n/// \tparam AAA Aaa] RawCommentRange=[19:1 - 20:20] FullCommentAsHTML=[
AAA
Aaa
BBB
Bbb
] FullCommentAsXML=[comment_to_html_conversion_19c:@FT@>2#T#Tcomment_to_html_conversion_19#t0.0#t0.1#AAA0 AaaBBB1 Bbb + +// CHECK: FunctionTemplate=comment_to_html_conversion_19:25:6 RawComment=[/// \tparam BBB Bbb\n/// \tparam AAA Aaa] RawCommentRange=[19:1 - 20:20] FullCommentAsHTML=[
PPP
Aaa
QQQ
Bbb
] FullCommentAsXML=[comment_to_html_conversion_19c:@FT@>2#T#Tcomment_to_html_conversion_19#t0.0#t0.1#PPP0 AaaQQQ1 Bbb + +// CHECK: FunctionTemplate=comment_to_html_conversion_20:32:6 RawComment=[/// \tparam BBB Bbb\n/// \tparam UUU Zzz\n/// \tparam CCC Ccc\n/// \tparam AAA Aaa] RawCommentRange=[27:1 - 30:20] FullCommentAsHTML=[
AAA
Aaa
BBB
Bbb
CCC
Ccc
UUU
Zzz
] FullCommentAsXML=[comment_to_html_conversion_20c:@FT@>3#T#T#NIcomment_to_html_conversion_20#t0.0#t0.1#AAA0 AaaBBB1 Bbb CCC2 Ccc UUU Zzz + +// CHECK: FunctionTemplate=comment_to_html_conversion_20:35:6 RawComment=[/// \tparam BBB Bbb\n/// \tparam UUU Zzz\n/// \tparam CCC Ccc\n/// \tparam AAA Aaa] RawCommentRange=[27:1 - 30:20] FullCommentAsHTML=[
PPP
Aaa
QQQ
Bbb
RRR
Ccc
UUU
Zzz
] FullCommentAsXML=[comment_to_html_conversion_20c:@FT@>3#T#T#NIcomment_to_html_conversion_20#t0.0#t0.1#PPP0 AaaQQQ1 Bbb RRR2 Ccc UUU Zzz + +// CHECK: FunctionTemplate=comment_to_html_conversion_21:42:6 RawComment=[/// \tparam AAA Aaa\n/// \tparam BBB Bbb\n/// \tparam CCC Ccc\n/// \tparam DDD Ddd] RawCommentRange=[37:1 - 40:20] FullCommentAsHTML=[
AAA
Aaa
BBB
Bbb
CCC
Ccc
DDD
Ddd
] FullCommentAsXML=[comment_to_html_conversion_21c:@FT@>1#t>2#t>1#T#Tcomment_to_html_conversion_21#AAA0 Aaa BBB Bbb CCC Ccc DDD Ddd + +// CHECK: FunctionTemplate=comment_to_html_conversion_21:45:6 RawComment=[/// \tparam AAA Aaa\n/// \tparam BBB Bbb\n/// \tparam CCC Ccc\n/// \tparam DDD Ddd] RawCommentRange=[37:1 - 40:20] FullCommentAsHTML=[
PPP
Aaa
QQQ
Bbb
RRR
Ccc
SSS
Ddd
] FullCommentAsXML=[comment_to_html_conversion_21c:@FT@>1#t>2#t>1#T#Tcomment_to_html_conversion_21#PPP0 Aaa QQQ Bbb RRR Ccc SSS Ddd + +// CHECK: FunctionTemplate=comment_to_html_conversion_22:54:6 RawComment=[/// \tparam C1 Ccc 1\n/// \tparam AAA Zzz\n/// \tparam C2 Ccc 2\n/// \tparam C3 Ccc 3\n/// \tparam C4 Ccc 4\n/// \tparam BBB Bbb] RawCommentRange=[47:1 - 52:20] FullCommentAsHTML=[
C1
Ccc 1
AAA
Zzz
C2
Ccc 2
C3
Ccc 3
C4
Ccc 4
BBB
Bbb
] FullCommentAsXML=[comment_to_html_conversion_22c:@FT@>2#T#t>2#T#t>2#T#Tcomment_to_html_conversion_22#C10 Ccc 1 AAA1 Zzz C2 Ccc 2 C3 Ccc 3 C4 Ccc 4 BBB Bbb + +// CHECK: FunctionTemplate=comment_to_html_conversion_22:58:6 RawComment=[/// \tparam C1 Ccc 1\n/// \tparam AAA Zzz\n/// \tparam C2 Ccc 2\n/// \tparam C3 Ccc 3\n/// \tparam C4 Ccc 4\n/// \tparam BBB Bbb] RawCommentRange=[47:1 - 52:20] FullCommentAsHTML=[
CCC1
Ccc 1
PPP
Zzz
CCC2
Ccc 2
CCC3
Ccc 3
CCC4
Ccc 4
QQQ
Bbb
] FullCommentAsXML=[comment_to_html_conversion_22c:@FT@>2#T#t>2#T#t>2#T#Tcomment_to_html_conversion_22#CCC10 Ccc 1 PPP1 Zzz CCC2 Ccc 2 CCC3 Ccc 3 CCC4 Ccc 4 QQQ Bbb diff --git a/clang/test/Index/overriding-method-comments.mm b/clang/test/Index/overriding-method-comments.mm index ed3e65a..c0aefb0 100644 --- a/clang/test/Index/overriding-method-comments.mm +++ b/clang/test/Index/overriding-method-comments.mm @@ -109,3 +109,16 @@ void foo1(int TTT); // CHECK: FullCommentAsHTML=[

Does something.

EEE
argument to function decl.
] FullCommentAsXML=[foo1c:@F@foo1#I# Does something. EEE0in argument to function decl. // CHECK: FullCommentAsHTML=[

Does something.

TTT
argument to function decl.
] FullCommentAsXML=[foo1c:@F@foo1#I# Does something. TTT0in argument to function decl. + +/// \brief Documentation +/// \tparam BBB The type, silly. +/// \tparam AAA The type, silly as well. +template +void foo(AAA, BBB); + +template +void foo(PPP, QQQ); + +// CHECK: FullCommentAsHTML=[

Documentation

AAA
The type, silly as well.
BBB
The type, silly.
] FullCommentAsXML=[fooc:@FT@>2#T#Tfoo#t0.0#t0.1# Documentation AAA0 The type, silly as well.BBB1 The type, silly. + +// CHECK: FullCommentAsHTML=[

Documentation

PPP
The type, silly as well.
QQQ
The type, silly.
] FullCommentAsXML=[fooc:@FT@>2#T#Tfoo#t0.0#t0.1# Documentation PPP0 The type, silly as well.QQQ1 The type, silly. diff --git a/clang/tools/libclang/CXComment.cpp b/clang/tools/libclang/CXComment.cpp index 5fa249a..00171eb 100644 --- a/clang/tools/libclang/CXComment.cpp +++ b/clang/tools/libclang/CXComment.cpp @@ -305,7 +305,7 @@ CXString clang_TParamCommandComment_getParamName(CXComment CXC) { if (!TPCC || !TPCC->hasParamName()) return createCXString((const char *) 0); - return createCXString(TPCC->getParamName(), /*DupString=*/ false); + return createCXString(TPCC->getParamName(0), /*DupString=*/ false); } unsigned clang_TParamCommandComment_isParamPositionValid(CXComment CXC) { @@ -697,7 +697,7 @@ void CommentASTToHTMLConverter::visitTParamCommandComment( } else Result << "
"; - appendToResultWithHTMLEscaping(C->getParamName()); + appendToResultWithHTMLEscaping(C->getParamName(FC)); Result << "
"; if (C->isPositionValid()) { @@ -986,7 +986,7 @@ void CommentASTToXMLConverter::visitParamCommandComment(const ParamCommandCommen void CommentASTToXMLConverter::visitTParamCommandComment( const TParamCommandComment *C) { Result << ""; - appendToResultWithXMLEscaping(C->getParamName()); + appendToResultWithXMLEscaping(C->getParamName(FC)); Result << ""; if (C->isPositionValid() && C->getDepth() == 1) { diff --git a/clang/unittests/AST/CommentParser.cpp b/clang/unittests/AST/CommentParser.cpp index ab787c4..01ece2e 100644 --- a/clang/unittests/AST/CommentParser.cpp +++ b/clang/unittests/AST/CommentParser.cpp @@ -247,7 +247,7 @@ template return ::testing::AssertionFailure() << "TParamCommandComment has no parameter name"; - StringRef ActualParamName = TPCC->hasParamName() ? TPCC->getParamName() : ""; + StringRef ActualParamName = TPCC->hasParamName() ? TPCC->getParamName(0) : ""; if (ActualParamName != ParamName) return ::testing::AssertionFailure() << "TParamCommandComment has parameter name \"" << ActualParamName.str() -- 2.7.4