https://github.com/ilovepi created
https://github.com/llvm/llvm-project/pull/119808
[clang-doc][NFC] Rename CHECK prefix for YAML
We plan to introduce checks for other backends, like markdown.
[clang-doc][NFC] Make test resilient to line changes
This just reorganizes the test code, so its easy to use @LINE directives
in the test, and avoid needing to update all the line numbers when making
unrelated changes.
[clang-doc][NFC] Avoid unnecessary operations in the template test
[clang-doc] Add tests for Markdown output with C++ templates
[clang-doc] Precommit test case for functions with templated parameters and
return
To address #67549 we need a test case that will show up in the markdown
output for functions.
[clang-doc] Use QualName in Markdown output
QualName will provide the more useful typename when the type is
templated.
Fixes #67549
>From fad23f92a4bfda42d8d7da492973b1d348678a61 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Thu, 12 Dec 2024 18:10:40 -0800
Subject: [PATCH 1/6] [clang-doc][NFC] Rename CHECK prefix for YAML
We plan to introduce checks for other backends, like markdown.
---
.../test/clang-doc/templates.cpp | 120 +++++++++---------
1 file changed, 60 insertions(+), 60 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/templates.cpp
b/clang-tools-extra/test/clang-doc/templates.cpp
index 4d4a25b8d3b820..d5a9e7d201e1e5 100644
--- a/clang-tools-extra/test/clang-doc/templates.cpp
+++ b/clang-tools-extra/test/clang-doc/templates.cpp
@@ -3,7 +3,7 @@
// RUN: echo "" > %t/compile_flags.txt
// RUN: cp "%s" "%t/test.cpp"
// RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp
-output=%t/docs
-// RUN: cat %t/docs/index.yaml | FileCheck %s --check-prefix=CHECK
+// RUN: cat %t/docs/index.yaml | FileCheck %s --check-prefix=YAML
// RUN: rm -rf %t
template<typename T, int U = 1>
@@ -15,62 +15,62 @@ void function<bool, 0>(bool x) {}
template<class... T>
void ParamPackFunction(T... args);
-// CHECK: ---
-// CHECK-NEXT: USR: '{{([0-9A-F]{40})}}'
-// CHECK-NEXT: ChildFunctions:
-// CHECK-NEXT: - USR: '{{([0-9A-F]{40})}}'
-// CHECK-NEXT: Name: 'ParamPackFunction'
-// CHECK-NEXT: Location:
-// CHECK-NEXT: - LineNumber: 16
-// CHECK-NEXT: Filename: '{{.*}}'
-// CHECK-NEXT: Params:
-// CHECK-NEXT: - Type:
-// CHECK-NEXT: Name: 'T...'
-// CHECK-NEXT: QualName: 'T...'
-// CHECK-NEXT: Name: 'args'
-// CHECK-NEXT: ReturnType:
-// CHECK-NEXT: Type:
-// CHECK-NEXT: Name: 'void'
-// CHECK-NEXT: QualName: 'void'
-// CHECK-NEXT: Template:
-// CHECK-NEXT: Params:
-// CHECK-NEXT: - Contents: 'class... T'
-// CHECK-NEXT: - USR: '{{([0-9A-F]{40})}}'
-// CHECK-NEXT: Name: 'function'
-// CHECK-NEXT: DefLocation:
-// CHECK-NEXT: LineNumber: 10
-// CHECK-NEXT: Filename: '{{.*}}'
-// CHECK-NEXT: Params:
-// CHECK-NEXT: - Type:
-// CHECK-NEXT: Name: 'T'
-// CHECK-NEXT: QualName: 'T'
-// CHECK-NEXT: Name: 'x'
-// CHECK-NEXT: ReturnType:
-// CHECK-NEXT: Type:
-// CHECK-NEXT: Name: 'void'
-// CHECK-NEXT: QualName: 'void'
-// CHECK-NEXT: Template:
-// CHECK-NEXT: Params:
-// CHECK-NEXT: - Contents: 'typename T'
-// CHECK-NEXT: - Contents: 'int U = 1'
-// CHECK-NEXT: - USR: '{{([0-9A-F]{40})}}'
-// CHECK-NEXT: Name: 'function'
-// CHECK-NEXT: DefLocation:
-// CHECK-NEXT: LineNumber: 12
-// CHECK-NEXT: Filename: '{{.*}}'
-// CHECK-NEXT: Params:
-// CHECK-NEXT: - Type:
-// CHECK-NEXT: Name: '_Bool'
-// CHECK-NEXT: QualName: '_Bool'
-// CHECK-NEXT: Name: 'x'
-// CHECK-NEXT: ReturnType:
-// CHECK-NEXT: Type:
-// CHECK-NEXT: Name: 'void'
-// CHECK-NEXT: QualName: 'void'
-// CHECK-NEXT: Template:
-// CHECK-NEXT: Specialization:
-// CHECK-NEXT: SpecializationOf: '{{([0-9A-F]{40})}}'
-// CHECK-NEXT: Params:
-// CHECK-NEXT: - Contents: 'bool'
-// CHECK-NEXT: - Contents: '0'
-// CHECK-NEXT: ...
+// YAML: ---
+// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: ChildFunctions:
+// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Name: 'ParamPackFunction'
+// YAML-NEXT: Location:
+// YAML-NEXT: - LineNumber: 16
+// YAML-NEXT: Filename: '{{.*}}'
+// YAML-NEXT: Params:
+// YAML-NEXT: - Type:
+// YAML-NEXT: Name: 'T...'
+// YAML-NEXT: QualName: 'T...'
+// YAML-NEXT: Name: 'args'
+// YAML-NEXT: ReturnType:
+// YAML-NEXT: Type:
+// YAML-NEXT: Name: 'void'
+// YAML-NEXT: QualName: 'void'
+// YAML-NEXT: Template:
+// YAML-NEXT: Params:
+// YAML-NEXT: - Contents: 'class... T'
+// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Name: 'function'
+// YAML-NEXT: DefLocation:
+// YAML-NEXT: LineNumber: 10
+// YAML-NEXT: Filename: '{{.*}}'
+// YAML-NEXT: Params:
+// YAML-NEXT: - Type:
+// YAML-NEXT: Name: 'T'
+// YAML-NEXT: QualName: 'T'
+// YAML-NEXT: Name: 'x'
+// YAML-NEXT: ReturnType:
+// YAML-NEXT: Type:
+// YAML-NEXT: Name: 'void'
+// YAML-NEXT: QualName: 'void'
+// YAML-NEXT: Template:
+// YAML-NEXT: Params:
+// YAML-NEXT: - Contents: 'typename T'
+// YAML-NEXT: - Contents: 'int U = 1'
+// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Name: 'function'
+// YAML-NEXT: DefLocation:
+// YAML-NEXT: LineNumber: 12
+// YAML-NEXT: Filename: '{{.*}}'
+// YAML-NEXT: Params:
+// YAML-NEXT: - Type:
+// YAML-NEXT: Name: '_Bool'
+// YAML-NEXT: QualName: '_Bool'
+// YAML-NEXT: Name: 'x'
+// YAML-NEXT: ReturnType:
+// YAML-NEXT: Type:
+// YAML-NEXT: Name: 'void'
+// YAML-NEXT: QualName: 'void'
+// YAML-NEXT: Template:
+// YAML-NEXT: Specialization:
+// YAML-NEXT: SpecializationOf: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Params:
+// YAML-NEXT: - Contents: 'bool'
+// YAML-NEXT: - Contents: '0'
+// YAML-NEXT: ...
>From 80c8a707216695d11a564509da957ae518589c8b Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Thu, 12 Dec 2024 18:31:47 -0800
Subject: [PATCH 2/6] [clang-doc][NFC] Make test resilient to line changes
This just reorganizes the test code, so its easy to use @LINE directives
in the test, and avoid needing to update all the line numbers when making
unrelated changes.
---
.../test/clang-doc/templates.cpp | 24 +++++++++++--------
1 file changed, 14 insertions(+), 10 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/templates.cpp
b/clang-tools-extra/test/clang-doc/templates.cpp
index d5a9e7d201e1e5..1adfbe0cf18282 100644
--- a/clang-tools-extra/test/clang-doc/templates.cpp
+++ b/clang-tools-extra/test/clang-doc/templates.cpp
@@ -6,22 +6,17 @@
// RUN: cat %t/docs/index.yaml | FileCheck %s --check-prefix=YAML
// RUN: rm -rf %t
-template<typename T, int U = 1>
-void function(T x) {}
-
-template<>
-void function<bool, 0>(bool x) {}
+// YAML: ---
+// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
template<class... T>
void ParamPackFunction(T... args);
-// YAML: ---
-// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
// YAML-NEXT: ChildFunctions:
// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
// YAML-NEXT: Name: 'ParamPackFunction'
// YAML-NEXT: Location:
-// YAML-NEXT: - LineNumber: 16
+// YAML-NEXT: - LineNumber: [[# @LINE - 6]]
// YAML-NEXT: Filename: '{{.*}}'
// YAML-NEXT: Params:
// YAML-NEXT: - Type:
@@ -35,10 +30,14 @@ void ParamPackFunction(T... args);
// YAML-NEXT: Template:
// YAML-NEXT: Params:
// YAML-NEXT: - Contents: 'class... T'
+
+template<typename T, int U = 1>
+void function(T x) {}
+
// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
// YAML-NEXT: Name: 'function'
// YAML-NEXT: DefLocation:
-// YAML-NEXT: LineNumber: 10
+// YAML-NEXT: LineNumber: [[# @LINE - 5]]
// YAML-NEXT: Filename: '{{.*}}'
// YAML-NEXT: Params:
// YAML-NEXT: - Type:
@@ -53,10 +52,14 @@ void ParamPackFunction(T... args);
// YAML-NEXT: Params:
// YAML-NEXT: - Contents: 'typename T'
// YAML-NEXT: - Contents: 'int U = 1'
+
+template<>
+void function<bool, 0>(bool x) {}
+
// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
// YAML-NEXT: Name: 'function'
// YAML-NEXT: DefLocation:
-// YAML-NEXT: LineNumber: 12
+// YAML-NEXT: LineNumber: [[# @LINE - 6]]
// YAML-NEXT: Filename: '{{.*}}'
// YAML-NEXT: Params:
// YAML-NEXT: - Type:
@@ -74,3 +77,4 @@ void ParamPackFunction(T... args);
// YAML-NEXT: - Contents: 'bool'
// YAML-NEXT: - Contents: '0'
// YAML-NEXT: ...
+
>From 4dede8b5f892030ef777d47e50bb36aae0d76b72 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Thu, 12 Dec 2024 18:34:09 -0800
Subject: [PATCH 3/6] [clang-doc][NFC] Avoid unnecessary operations in the
template test
---
clang-tools-extra/test/clang-doc/templates.cpp | 5 +----
1 file changed, 1 insertion(+), 4 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/templates.cpp
b/clang-tools-extra/test/clang-doc/templates.cpp
index 1adfbe0cf18282..05a3dab71f48a1 100644
--- a/clang-tools-extra/test/clang-doc/templates.cpp
+++ b/clang-tools-extra/test/clang-doc/templates.cpp
@@ -1,10 +1,7 @@
// RUN: rm -rf %t
// RUN: mkdir %t
-// RUN: echo "" > %t/compile_flags.txt
-// RUN: cp "%s" "%t/test.cpp"
-// RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp
-output=%t/docs
+// RUN: clang-doc --doxygen --executor=standalone %s -output=%t/docs
// RUN: cat %t/docs/index.yaml | FileCheck %s --check-prefix=YAML
-// RUN: rm -rf %t
// YAML: ---
// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
>From b770594661bd42567b987a5fdb168ffb6852fbbe Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Thu, 12 Dec 2024 18:56:41 -0800
Subject: [PATCH 4/6] [clang-doc] Add tests for Markdown output with C++
templates
---
.../test/clang-doc/templates.cpp | 19 +++++++++++++++++++
1 file changed, 19 insertions(+)
diff --git a/clang-tools-extra/test/clang-doc/templates.cpp
b/clang-tools-extra/test/clang-doc/templates.cpp
index 05a3dab71f48a1..536b24161990aa 100644
--- a/clang-tools-extra/test/clang-doc/templates.cpp
+++ b/clang-tools-extra/test/clang-doc/templates.cpp
@@ -1,11 +1,18 @@
// RUN: rm -rf %t
// RUN: mkdir %t
+
// RUN: clang-doc --doxygen --executor=standalone %s -output=%t/docs
// RUN: cat %t/docs/index.yaml | FileCheck %s --check-prefix=YAML
+// RUN: clang-doc --doxygen --executor=standalone %s -output=%t/docs
--format=md
+// RUN: cat %t/docs/GlobalNamespace/index.md | FileCheck %s --check-prefix=MD
+
// YAML: ---
// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
+// MD: # Global Namespace
+// MD: ## Functions
+
template<class... T>
void ParamPackFunction(T... args);
@@ -28,6 +35,9 @@ void ParamPackFunction(T... args);
// YAML-NEXT: Params:
// YAML-NEXT: - Contents: 'class... T'
+// MD: ### ParamPackFunction
+// MD: *void ParamPackFunction(T... args)*
+
template<typename T, int U = 1>
void function(T x) {}
@@ -50,6 +60,10 @@ void function(T x) {}
// YAML-NEXT: - Contents: 'typename T'
// YAML-NEXT: - Contents: 'int U = 1'
+// MD: ### function
+// MD: *void function(T x)*
+// MD: *Defined at {{.*}}templates.cpp#[[# @LINE - 23]]*
+
template<>
void function<bool, 0>(bool x) {}
@@ -75,3 +89,8 @@ void function<bool, 0>(bool x) {}
// YAML-NEXT: - Contents: '0'
// YAML-NEXT: ...
+// MD: ### function
+// MD: *void function(_Bool x)*
+// MD: *Defined at {{.*}}templates.cpp#[[# @LINE - 27]]*
+
+
>From ae3fef1380055331ead7b3a76c1d13119a017011 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Thu, 12 Dec 2024 17:18:55 -0800
Subject: [PATCH 5/6] [clang-doc] Precommit test case for functions with
templated parameters and return
To address #67549 we need a test case that will show up in the markdown
output for functions.
---
.../test/clang-doc/templates.cpp | 64 ++++++++++++++++++-
1 file changed, 62 insertions(+), 2 deletions(-)
diff --git a/clang-tools-extra/test/clang-doc/templates.cpp
b/clang-tools-extra/test/clang-doc/templates.cpp
index 536b24161990aa..bf6528437b6ba9 100644
--- a/clang-tools-extra/test/clang-doc/templates.cpp
+++ b/clang-tools-extra/test/clang-doc/templates.cpp
@@ -9,6 +9,12 @@
// YAML: ---
// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: ChildRecords:
+// YAML-NEXT: - Type: Record
+// YAML-NEXT: Name: 'tuple'
+// YAML-NEXT: QualName: 'tuple'
+// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Path: 'GlobalNamespace'
// MD: # Global Namespace
// MD: ## Functions
@@ -87,10 +93,64 @@ void function<bool, 0>(bool x) {}
// YAML-NEXT: Params:
// YAML-NEXT: - Contents: 'bool'
// YAML-NEXT: - Contents: '0'
-// YAML-NEXT: ...
// MD: ### function
// MD: *void function(_Bool x)*
-// MD: *Defined at {{.*}}templates.cpp#[[# @LINE - 27]]*
+// MD: *Defined at {{.*}}templates.cpp#[[# @LINE - 26]]*
+
+/// A Tuple type
+///
+/// Does nothing.
+template<typename ...Tys>
+struct tuple{};
+
+/// A function with a tuple parameter
+///
+/// \param t The input to func_with_tuple_param
+tuple<int,int,bool> func_with_tuple_param(tuple<int,int,bool> t){ return t;}
+// YAML-NEXT: - USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Name: 'func_with_tuple_param'
+// YAML-NEXT: Description:
+// YAML-NEXT: - Kind: 'FullComment'
+// YAML-NEXT: Children:
+// YAML-NEXT: - Kind: 'ParagraphComment'
+// YAML-NEXT: Children:
+// YAML-NEXT: - Kind: 'TextComment'
+// YAML-NEXT: Text: ' A function with a tuple
parameter'
+// YAML-NEXT: - Kind: 'ParagraphComment'
+// YAML-NEXT: Children:
+// YAML-NEXT: - Kind: 'TextComment'
+// YAML-NEXT: - Kind: 'ParamCommandComment'
+// YAML-NEXT: Direction: '[in]'
+// YAML-NEXT: ParamName: 't'
+// YAML-NEXT: Children:
+// YAML-NEXT: - Kind: 'ParagraphComment'
+// YAML-NEXT: Children:
+// YAML-NEXT: - Kind: 'TextComment'
+// YAML-NEXT: Text: ' The input to
func_with_tuple_param'
+// YAML-NEXT: DefLocation:
+// YAML-NEXT: LineNumber: [[# @LINE - 23]]
+// YAML-NEXT: Filename:
+// YAML-NEXT: Params:
+// YAML-NEXT: - Type:
+// YAML-NEXT: Type: Record
+// YAML-NEXT: Name: 'tuple'
+// YAML-NEXT: QualName: 'tuple<int, int, _Bool>'
+// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Path: 'GlobalNamespace'
+// YAML-NEXT: Name: 't'
+// YAML-NEXT: ReturnType:
+// YAML-NEXT: Type:
+// YAML-NEXT: Type: Record
+// YAML-NEXT: Name: 'tuple'
+// YAML-NEXT: QualName: 'tuple<int, int, _Bool>'
+// YAML-NEXT: USR: '{{([0-9A-F]{40})}}'
+// YAML-NEXT: Path: 'GlobalNamespace'
+// YAML-NEXT: ...
+// MD: ### func_with_tuple_param
+// MD: *tuple func_with_tuple_param(tuple t)*
+// MD: *Defined at {{.*}}templates.cpp#[[# @LINE - 44]]*
+// MD: A function with a tuple parameter
+// MD: **t** The input to func_with_tuple_param
>From bb23377a49bee459c9824827f8664f08feaa14f2 Mon Sep 17 00:00:00 2001
From: Paul Kirth <paulki...@google.com>
Date: Thu, 12 Dec 2024 19:14:25 -0800
Subject: [PATCH 6/6] [clang-doc] Use QualName in Markdown output
QualName will provide the more useful typename when the type is
templated.
Fixes #67549
---
clang-tools-extra/clang-doc/MDGenerator.cpp | 6 +++---
clang-tools-extra/test/clang-doc/templates.cpp | 2 +-
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/clang-tools-extra/clang-doc/MDGenerator.cpp
b/clang-tools-extra/clang-doc/MDGenerator.cpp
index 795eb4b904e3ef..00c6605725dae9 100644
--- a/clang-tools-extra/clang-doc/MDGenerator.cpp
+++ b/clang-tools-extra/clang-doc/MDGenerator.cpp
@@ -157,17 +157,17 @@ static void genMarkdown(const ClangDocContext &CDCtx,
const FunctionInfo &I,
for (const auto &N : I.Params) {
if (!First)
Stream << ", ";
- Stream << N.Type.Name + " " + N.Name;
+ Stream << N.Type.QualName + " " + N.Name;
First = false;
}
writeHeader(I.Name, 3, OS);
std::string Access = getAccessSpelling(I.Access).str();
if (Access != "")
- writeLine(genItalic(Access + " " + I.ReturnType.Type.Name + " " + I.Name +
+ writeLine(genItalic(Access + " " + I.ReturnType.Type.QualName + " " +
I.Name +
"(" + Stream.str() + ")"),
OS);
else
- writeLine(genItalic(I.ReturnType.Type.Name + " " + I.Name + "(" +
+ writeLine(genItalic(I.ReturnType.Type.QualName + " " + I.Name + "(" +
Stream.str() + ")"),
OS);
if (I.DefLoc)
diff --git a/clang-tools-extra/test/clang-doc/templates.cpp
b/clang-tools-extra/test/clang-doc/templates.cpp
index bf6528437b6ba9..b5590a92e7524c 100644
--- a/clang-tools-extra/test/clang-doc/templates.cpp
+++ b/clang-tools-extra/test/clang-doc/templates.cpp
@@ -150,7 +150,7 @@ tuple<int,int,bool>
func_with_tuple_param(tuple<int,int,bool> t){ return t;}
// YAML-NEXT: ...
// MD: ### func_with_tuple_param
-// MD: *tuple func_with_tuple_param(tuple t)*
+// MD: *tuple<int, int, _Bool> func_with_tuple_param(tuple<int, int, _Bool> t)*
// MD: *Defined at {{.*}}templates.cpp#[[# @LINE - 44]]*
// MD: A function with a tuple parameter
// MD: **t** The input to func_with_tuple_param
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
