Skip to content

[clang-doc] Add regression test for test comments in macros #132360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

[clang-doc] Add regression test for test comments in macros #132360

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d7afcf5
clang-tools-extra/test/clang-doc/macro.cpp
ZhongUncle Mar 21, 2025
32adcf1
new file: clang-tools-extra/test/clang-doc/macro.cpp
ZhongUncle Mar 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions clang-tools-extra/test/clang-doc/macro.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// RUN: rm -rf %t && mkdir -p %t
// RUN: clang-doc --format=md --doxygen --output=%t --executor=standalone %s
// RUN: clang-doc --format=html --doxygen --output=%t --executor=standalone %s
Copy link
Contributor

@ilovepi ilovepi Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lets move this down w/ the HTML FileCheck lines so they're grouped together.

I'd also suggest renaming the test file to DR-59819.cpp, which is a common way to indicate that its a regression test (DR stands for Defect Report, and the number is the issue number. I'm fine to leave it with a more readable name, but in that case I'd prefer comments-in-macros.cpp and a comment at the top of the file describing the purpose and properties you're testing for.

// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.md --check-prefix=MD-MyClass-LINE
// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.md --check-prefix=MD-MyClass
// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.html --check-prefix=HTML-MyClass-LINE
// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.html --check-prefix=HTML-MyClass

#define DECLARE_METHODS \
/**
* @brief Declare a method to calculate the sum of two numbers
Copy link
Contributor

@ilovepi ilovepi Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this comment is in the macro, did you intend it to be?

Also as I understand it the bug wasn't filed about comments within macros, which I seldom see. But about comments attached to macros.

I'd also suggest a simpler macro that doesn't define a full function (which also doesn't appear to actually be part of the macro.).

Maybe the macro could be something like

/// Your doc comments 
#define ADD(a, b) a+b

Copy link
Contributor Author

@ZhongUncle ZhongUncle Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I intend to do it, because I try to restore code in issue. And I test some comment styles in this position, like ///(not work, because new line symbol not work well), /**/(works well) and /**(works, this is also format in issue, but if I use \ in each line end, it will output 2 \ and blank in gnerated markdown).

Copy link
Contributor Author

@ZhongUncle ZhongUncle Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also rarely see this kind comment in comments, whether in books or in real projects. But this issue display like this. Maybe I understood this wrongly.

If just regular comment, I think I can write a series test like enum.cpp.

Maybe I'm overcomplicating the problem.

Copy link
Contributor

@ilovepi ilovepi Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also rarely see this kind comment in comments, whether in books or in real projects. But this issue display like this. Maybe I understood this wrongly.

ah, no, I've confused this with a different issue. Apologies. I should take my own advice not to review code first thing in the morning XD. Lets just make it syntactically correct using trailing \. If the markdown comes out w/ an extra \, we can file a bug for that and handle that separately.

You can confirm what's going on by dumping the AST from clang, or by using some of the debug output from clang-doc.

Copy link
Contributor Author

@ZhongUncle ZhongUncle Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make sense. I will report something as new issues, or maybe I can write it in my GSoC proposal?

I will fix these files after wake up, because it is already early morning here, and I think I broken up something in the project, so I re-cloned entire project, and even though I used --depth 1, it still takes a very long time when git updating files.

I am very happy to get your help and learn new knowledge on the first day of contacting the project, even though I messed up some things.

*/ \
int Add(int a, int b) \
{ \
return a + b; \
}

// MD-MyClass: ### Add
Copy link
Contributor

@ilovepi ilovepi Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
// MD-MyClass: ### Add
// MD-MYCLASS: ### Add

Use all caps for check prefixes

// MD-MyClass: *public int Add(int a, int b)*
// MD-MyClass: **brief** Declare a method to calculate the sum of two numbers

// HTML-MyClass: <p>public int Add(int a, int b)</p>
// HTML-MyClass: <div>brief</div>
// HTML-MyClass: <p> Declare a method to calculate the sum of two numbers</p>


class MyClass {
Copy link
Contributor

@ilovepi ilovepi Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this class testing? It's not clear what property you're trying to exercise. I see you expect the macro to expand in the class, but I don't think you're testing what you think you are.

Copy link
Contributor Author

@ZhongUncle ZhongUncle Mar 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I didn't use this class, in this style comment, generated content will no this macro, both html and markdown. That why I use a . And again, I try to restore issue example in issue, so I use this style comment.

I also think this class shouldn't be here, but I don't know how to implement a macro function like in issue.

public:
// MD-MyClass-LINE: *Defined at {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}macro.cpp#[[@LINE+2]]*
// HTML-MyClass-LINE: <p>Defined at line [[@LINE+1]] of file {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}macro.cpp</p>
DECLARE_METHODS
};
1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/CUDA-symlinks/usr/bin/ptxas
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/CUDA-symlinks/usr/bin/ptxas
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0024
509d326cf43a00f4244e32ee2f04c3e2
../../opt/cuda/bin/ptxas

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/basic_cross_linux_tree/usr/bin/i386-unknown-linux-gnu-ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/basic_cross_linux_tree/usr/bin/i386-unknown-linux-gnu-ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0030
d830f4e83fadc0198bcd16cda139c2ab
i386-unknown-linux-gnu-ld.gold

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/basic_cross_linux_tree/usr/bin/x86_64-unknown-linux-gnu-ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/basic_cross_linux_tree/usr/bin/x86_64-unknown-linux-gnu-ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0032
dc3942b3625b5edbceda2054b487f4cf
x86_64-unknown-linux-gnu-ld.gold

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/basic_cross_linux_tree/usr/i386-unknown-linux-gnu/bin/ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/basic_cross_linux_tree/usr/i386-unknown-linux-gnu/bin/ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0007
a4a6106fa60c6a126bf88b36f82eca45
ld.gold

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/basic_cross_linux_tree/usr/x86_64-unknown-linux-gnu/bin/ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/basic_cross_linux_tree/usr/x86_64-unknown-linux-gnu/bin/ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0007
a4a6106fa60c6a126bf88b36f82eca45
ld.gold

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/basic_cross_linux_tree/usr/x86_64-unknown-linux-gnu/bin/lld-wrapper
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/basic_cross_linux_tree/usr/x86_64-unknown-linux-gnu/bin/lld-wrapper
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0006
75027f59be28a4783c4dbb6f47c0ce72
ld.lld

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/bin/as
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/bin/as
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0025
f706cb75cd2a1eeaf3cc4516f97ca07a
i386-unknown-linux-gnu-as

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/bin/ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/bin/ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0025
fae188f0b438aa0ee85bf296c22d408d
i386-unknown-linux-gnu-ld

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/bin/as
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/bin/as
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0035
cc3d89dc47131fa307b744805fdeb87b
../../bin/i386-unknown-linux-gnu-as

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/bin/ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_32bit_linux_tree/usr/i386-unknown-linux/bin/ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0035
6693f8726305d07602737a435e2b8a22
../../bin/i386-unknown-linux-gnu-ld

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/bin/as
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/bin/as
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0027
4b879674be084ecc7a2574cf9f69ec98
x86_64-unknown-linux-gnu-as

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/bin/ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/bin/ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0027
acddaea92e9f2581b0940c29f8726108
x86_64-unknown-linux-gnu-ld

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/bin/as
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/bin/as
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0037
4237f2b716c4c66e0a5a9d62e2947704
../../bin/x86_64-unknown-linux-gnu-as

1 change: 0 additions & 1 deletion clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/bin/ld
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions clang/test/Driver/Inputs/multilib_64bit_linux_tree/usr/x86_64-unknown-linux/bin/ld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0037
c87e4c3470038094e85a9724945b6b54
../../bin/x86_64-unknown-linux-gnu-ld

1 change: 0 additions & 1 deletion ...est/API/functionalities/breakpoint/breakpoint_with_realpath_and_source_map/symlink1/foo.h
View file
Open in desktop

This file was deleted.

5 changes: 5 additions & 0 deletions ...est/API/functionalities/breakpoint/breakpoint_with_realpath_and_source_map/symlink1/foo.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
XSym
0013
64f134e8c57126ca56932a494eb70be5
../real/foo.h

1 change: 0 additions & 1 deletion lldb/test/API/functionalities/breakpoint/breakpoint_with_realpath_and_source_map/symlink2
View file
Open in desktop

This file was deleted.

Loading