Skip to content

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

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

Merged
merged 7 commits into from
May 6, 2025
Merged

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

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a6a1916
Fixes #59819. The underlying problem was fixed in https://reviews.llv…
ZhongUncle Mar 22, 2025
b15a9d0
Fixes #59819. The underlying problem was fixed in https://reviews.llv…
ZhongUncle Mar 22, 2025
2b6556e
Fixes #59819. The underlying problem was fixed in https://reviews.llv…
ZhongUncle Mar 22, 2025
875938c
Fixes #59819. The underlying problem was fixed in https://reviews.llv…
ZhongUncle Mar 25, 2025
7bad199
Update clang-tools-extra/test/clang-doc/comments-in-macros.cpp
ZhongUncle Apr 2, 2025
9e9fdf6
modified: comments-in-macros.cpp
ZhongUncle Apr 19, 2025
f9cd05d
modified: comments-in-macros.cpp
ZhongUncle May 4, 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
35 changes: 35 additions & 0 deletions clang-tools-extra/test/clang-doc/comments-in-macros.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
// Regression test for https://github.com/llvm/llvm-project/issues/59819

// RUN: rm -rf %t && mkdir -p %t
// RUN: clang-doc --format=md --doxygen --output=%t --executor=standalone %s
// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.md --check-prefix=MD-MYCLASS-LINE
// RUN: FileCheck %s < %t/GlobalNamespace/MyClass.md --check-prefix=MD-MYCLASS

// RUN: clang-doc --format=html --doxygen --output=%t --executor=standalone %s
// 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
*/ \
int Add(int a, int b) { \
return a + b; \
}

// MD-MYCLASS: ### Add
// 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>
Copy link
Contributor

Choose a reason for hiding this comment

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

It isn't clear to me from the test if the defined at... part is matching where you want it. the following checks in the class body should probably have the -NEXT: suffix so we know we're matching the last part of the the Add() defintion w/in the macro.

Copy link
Contributor Author

@ZhongUncle ZhongUncle Mar 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It isn't clear to me from the test if the defined at... part is matching where you want it. the following checks in the class body should probably have the -NEXT: suffix so we know we're matching the last part of the the Add() defintion w/in the macro.

Yeah, I notice its line is in class, rather than line comment in macro.
Do you mean: -NEXT: HTML-MYCLASS: <p>public int Add(int a, int b)</p>

I don't know how to use it and can't find usage in documentation. Can you give me a example of -NEXT:? It is better to give me a documentation or manual.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I also have another problem: Why HTML match is not similar to Markdown?

Because I refer to enum.cpp to write this match. It matchs different parts. So I don't make sense which part must match in HTML.

Markdown match is clearly, HTML seem to ignore something.

Copy link
Contributor

Choose a reason for hiding this comment

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

https://llvm.org/docs/CommandGuide/FileCheck.html#the-check-next-directive has information on how the -NEXT suffix works.

You use it the following way.

MYCHECK: match first line
MYCHECK-NEXT: match has to be on following line after the previous MYCHECK
MYCHECK: match something (potentially) far away
MYCHECK-NEXT: match has to be on the following line after the previous MYCHECK

What this allows you do do is be certain you're matching the correct part of the output, and that you're not accidentally matching things out of order.

This becomes more obvious w/ things in codegen where you have easy to spot delimiters, but are also likely to have many duplicate lines in your test program (e.g. most load instructions look the same).

So you use this pattern to match the start of a unique sequence w/ MYCHECK (or whatever your prefix is), and then use MYCHECK-NEXT to make sure the following lines match right afterwards, and not anywhere else.

Copy link
Contributor

Choose a reason for hiding this comment

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

I also have another problem: Why HTML match is not similar to Markdown?

Because I refer to enum.cpp to write this match. It matchs different parts. So I don't make sense which part must match in HTML.

Markdown match is clearly, HTML seem to ignore something.

I'm not sure what you are asking. FileCheck pattern matching will match what it finds in the file that matches. IIRC it will take the last thing it finds that matches, not the first. So your lines may match arbitrary things in the output.

The markdown has a lot of empty lines, which makes writing checks w/ a -NEXT suffix hard to do. HTML is much more structured, so its (generally) more difficult to accidentally match something if you write stricter checks.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thank you very much for the explanation, I'll learn about these new LLVM concepts and get familiar with the FileCheck tools, and then improve the code. However, recently I am preparing for the interview for graduate school, so please forgive me for the slow progress.



class MyClass {
public:
// MD-MYCLASS-LINE: *Defined at {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}comments-in-macros.cpp#[[@LINE+2]]*
// HTML-MYCLASS-LINE: <p>Defined at line [[@LINE+1]] of file {{.*}}clang-tools-extra{{[\/]}}test{{[\/]}}clang-doc{{[\/]}}comments-in-macros.cpp</p>
DECLARE_METHODS
};

Loading