[all-commits] [llvm/llvm-project] 6416b6: [clang][test] add testing for the AST matcher refe...
Julian Schmidt via All-commits
all-commits at lists.llvm.org
Thu Aug 29 08:15:00 PDT 2024
Branch: refs/heads/users/5chmidti/add_testing_for_the_AST_matcher_reference
Home: https://github.com/llvm/llvm-project
Commit: 6416b6d43ec241433a3cf274c3828309cda99abf
https://github.com/llvm/llvm-project/commit/6416b6d43ec241433a3cf274c3828309cda99abf
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/docs/LibASTMatchersReference.html
M clang/docs/ReleaseNotes.rst
M clang/docs/doxygen.cfg.in
M clang/docs/tools/dump_ast_matchers.py
M clang/include/clang/ASTMatchers/ASTMatchers.h
M clang/unittests/ASTMatchers/ASTMatchersTest.h
M clang/unittests/ASTMatchers/CMakeLists.txt
A clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
[clang][test] add testing for the AST matcher reference
Previously, the examples in the AST matcher reference, which gets
generated by the doxygen comments in `ASTMatchers.h`, were untested
and best effort.
Some of the matchers had no or wrong examples of how to use the matcher.
This patch introduces a simple DSL around doxygen commands to enable
testing the AST matcher documentation in a way that should be relatively
easy.
In `ASTMatchers.h`, most matchers are documented with a doxygen comment.
Most of these also have a code example that aims to show what the
matcher will match, given a matcher somewhere in the documentation text.
The way that testing the documentation is done, is by using doxygens
alias feature to declare custom aliases. These aliases forward to
`<tt>text</tt>` (which is what doxygens \c does, but for multiple words).
Using the doxygen aliases was the obvious choice, because there are
(now) four consumers:
- people reading the header/using signature help
- the doxygen generated documentation
- the generated html AST matcher reference
- (new) the generated matcher tests
This patch rewrites/extends the documentation such that all matchers
have a documented example.
The new `generate_ast_matcher_doc_tests.py` script will warn on any
undocumented matchers (but not on matchers without a doxygen comment)
and provides diagnostics and statistics about the matchers.
Below is a file-level comment from the test generation script that
describes how documenting matchers to be tested works on a slightly more
technical level. In general, the new comments can be used as a reference
for how to implement a tested documentation.
The current statistics emitted by the parser are:
```text
Statistics:
doxygen_blocks : 519
missing_tests : 10
skipped_objc : 42
code_snippets : 503
matches : 820
matchers : 580
tested_matchers : 574
none_type_matchers : 6
```
The tests are generated during building and the script will only print
something if it found an issue (compile failure, parsing issues,
the expected and actual number of failures differs).
DSL for generating the tests from documentation.
TLDR:
The order for a single code snippet example is:
\header{a.h}
\endheader <- zero or more header
\code
int a = 42;
\endcode
\compile_args{-std=c++,c23-or-later} <- optional, supports std ranges and
whole languages
\matcher{expr()} <- one or more matchers in succession
\match{42} <- one ore more matches in succession
\matcher{varDecl()} <- new matcher resets the context, the above
\match will not count for this new
matcher(-group)
\match{int a = 42} <- only applies to the previous matcher (no the
previous case)
The above block can be repeated inside of a doxygen command for multiple
code examples.
Language Grammar:
[] denotes an optional, and <> denotes user-input
compile_args j:= \compile_args{[<compile_arg>;]<compile_arg>}
matcher_tag_key ::= type
match_tag_key ::= type || std || count
matcher_tags ::= [matcher_tag_key=<value>;]matcher_tag_key=<value>
match_tags ::= [match_tag_key=<value>;]match_tag_key=<value>
matcher ::= \matcher{[matcher_tags$]<matcher>}
matchers ::= [matcher] matcher
match ::= \match{[match_tags$]<match>}
matches ::= [match] match
case ::= matchers matches
cases ::= [case] case
header-block ::= \header{<name>} <code> \endheader
code-block ::= \code <code> \endcode
testcase ::= code-block [compile_args] cases
The 'std' tag and '\compile_args' support specifying a specific
language version, a whole language and all of it's versions, and thresholds
(implies ranges). Multiple arguments are passed with a ',' seperator.
For a language and version to execute a tested matcher, it has to match
the specified '\compile_args' for the code, and the 'std' tag for the matcher.
Predicates for the 'std' compiler flag are used with disjunction between
languages (e.g. 'c || c++') and conjunction for all predicates specific
to each language (e.g. 'c++11-or-later && c++23-or-earlier').
Examples:
- c all available versions of C
- c++11 only C++11
- c++11-or-later C++11 or later
- c++11-or-earlier C++11 or earlier
- c++11-or-later,c++23-or-earlier,c all of C and C++ between 11 and
23 (inclusive)
- c++11-23,c same as above
Tags:
Type:
Match types are used to select where the string that is used to check if
a node matches comes from.
Available: code, name, typestr, typeofstr.
The default is 'code'.
Matcher types are used to mark matchers as submatchers with 'sub' or as
deactivated using 'none'. Testing submatchers is not implemented.
Count:
Specifying a 'count=n' on a match will result in a test that requires that
the specified match will be matched n times. Default is 1.
Std:
A match allows specifying if it matches only in specific language versions.
This may be needed when the AST differs between language versions.
Fixes #57607
Fixes #63748
Commit: 99b4f0cb9d2662209d717264465aa2df9e254f3b
https://github.com/llvm/llvm-project/commit/99b4f0cb9d2662209d717264465aa2df9e254f3b
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix cuda tests
Commit: fcd5c7ccbb775616c56a2e37a394fefd88b2adfe
https://github.com/llvm/llvm-project/commit/fcd5c7ccbb775616c56a2e37a394fefd88b2adfe
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix cuda tests
Commit: 274d3825a6caa3994523e789ef243470a155e5d2
https://github.com/llvm/llvm-project/commit/274d3825a6caa3994523e789ef243470a155e5d2
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix f-string containing backslash
Commit: df3fa5b746b6c028a446eae72417ed5f6754a396
https://github.com/llvm/llvm-project/commit/df3fa5b746b6c028a446eae72417ed5f6754a396
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
M clang/unittests/ASTMatchers/ASTMatchersTest.h
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
rm not needed typeofstr match kind
Commit: e8ad32dda0792d0196c9374f44e2e76368a4089e
https://github.com/llvm/llvm-project/commit/e8ad32dda0792d0196c9374f44e2e76368a4089e
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
move some FIXME's to the main function
Commit: 2854e1bf6604ddbd2043d6bce11947a23a2d0e39
https://github.com/llvm/llvm-project/commit/2854e1bf6604ddbd2043d6bce11947a23a2d0e39
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
replace some type=name matches with explicit code matches to be more expressive
Commit: a41a8a394b287a97ffec8f5635621887a8623442
https://github.com/llvm/llvm-project/commit/a41a8a394b287a97ffec8f5635621887a8623442
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
add missing comments on some matchers on the number of matches generated
Commit: 8d5ac3e9d5bfb0d5ca686dd495f623f2288b83ea
https://github.com/llvm/llvm-project/commit/8d5ac3e9d5bfb0d5ca686dd495f623f2288b83ea
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
add documentation (pr desc) to ASTMatchers.h's file comment
Commit: 4a89df28776c85ee28517b577b323cebb6e6c18c
https://github.com/llvm/llvm-project/commit/4a89df28776c85ee28517b577b323cebb6e6c18c
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
fix empty enum decl
Commit: 34c446b3f53e9bbe280ed7ac54f60d9fa8a6f4af
https://github.com/llvm/llvm-project/commit/34c446b3f53e9bbe280ed7ac54f60d9fa8a6f4af
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix formatting
Commit: d7712f3873acf05e86d549fc7b4db72c6be2a2d1
https://github.com/llvm/llvm-project/commit/d7712f3873acf05e86d549fc7b4db72c6be2a2d1
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-08-29 (Thu, 29 Aug 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
fix formatting
Compare: https://github.com/llvm/llvm-project/compare/c4cb284ac357...d7712f3873ac
To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications
More information about the All-commits
mailing list