[all-commits] [llvm/llvm-project] deac0b: [clang][test] add testing for the AST matcher refe...
Julian Schmidt via All-commits
all-commits at lists.llvm.org
Thu Oct 31 01:30:17 PDT 2024
Branch: refs/heads/users/5chmidti/add_testing_for_the_AST_matcher_reference
Home: https://github.com/llvm/llvm-project
Commit: deac0b7b46334bcf9355b86ccab05e5f9c2b4bea
https://github.com/llvm/llvm-project/commit/deac0b7b46334bcf9355b86ccab05e5f9c2b4bea
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 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: e364ac16b73285d6454d17c2198ae4d437fde2c2
https://github.com/llvm/llvm-project/commit/e364ac16b73285d6454d17c2198ae4d437fde2c2
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix cuda tests
Commit: ee6fac2000fee3b581c113650394f873941103aa
https://github.com/llvm/llvm-project/commit/ee6fac2000fee3b581c113650394f873941103aa
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 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: 236909b5a70874a768793eb534458bcc028c827a
https://github.com/llvm/llvm-project/commit/236909b5a70874a768793eb534458bcc028c827a
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix f-string containing backslash
Commit: 7cf190fd6c63c6bea396e8d341aac04807957c27
https://github.com/llvm/llvm-project/commit/7cf190fd6c63c6bea396e8d341aac04807957c27
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 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: 975a8a2db80eeabc1b6b8fb61cfb44d8dc1623dc
https://github.com/llvm/llvm-project/commit/975a8a2db80eeabc1b6b8fb61cfb44d8dc1623dc
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
move some FIXME's to the main function
Commit: 24c2dd0b1c3975efb2ab89724b5f5cb25877e014
https://github.com/llvm/llvm-project/commit/24c2dd0b1c3975efb2ab89724b5f5cb25877e014
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 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: 5969c52e1c248e0ac7ee00b1495b37ea854d83b1
https://github.com/llvm/llvm-project/commit/5969c52e1c248e0ac7ee00b1495b37ea854d83b1
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 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: 714369cf8cd696d72930a4b9cc7e726a4a6e63ca
https://github.com/llvm/llvm-project/commit/714369cf8cd696d72930a4b9cc7e726a4a6e63ca
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
add documentation (pr desc) to ASTMatchers.h's file comment
Commit: c00f1c07c7b8621ffc5c85ee9a63f6b786541b9b
https://github.com/llvm/llvm-project/commit/c00f1c07c7b8621ffc5c85ee9a63f6b786541b9b
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
fix empty enum decl
Commit: 32cb6f68acb5606159b1f5f2b0bcb38f6ef2d7d5
https://github.com/llvm/llvm-project/commit/32cb6f68acb5606159b1f5f2b0bcb38f6ef2d7d5
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
fix formatting
Commit: 64d7057579696ecd0543b80d8bb8aee4f0d59e99
https://github.com/llvm/llvm-project/commit/64d7057579696ecd0543b80d8bb8aee4f0d59e99
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
fix formatting
Commit: d5b33fd02e978229b4277384fc8b99d93348890a
https://github.com/llvm/llvm-project/commit/d5b33fd02e978229b4277384fc8b99d93348890a
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
[clang][test][NFC] fix for python version requirements
Fix for the buildbot failure due to lower python versions not supporting
some types to be subscripted. Tested with python3.8.
Commit: 05419a18fc5b9515ec55b8332b8b834676c23452
https://github.com/llvm/llvm-project/commit/05419a18fc5b9515ec55b8332b8b834676c23452
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/utils/generate_ast_matcher_doc_tests.py
Log Message:
-----------
remove testing if the examples compile in the test gen script
Commit: 54832710ebd49971dd437770c043638c20bb71ce
https://github.com/llvm/llvm-project/commit/54832710ebd49971dd437770c043638c20bb71ce
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/include/clang/ASTMatchers/ASTMatchers.h
Log Message:
-----------
update header comment
Commit: 6012540dcbc332293bfee95bad384ab2c9ec7e71
https://github.com/llvm/llvm-project/commit/6012540dcbc332293bfee95bad384ab2c9ec7e71
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/unittests/ASTMatchers/ASTMatchersTest.h
Log Message:
-----------
fix control flow reaching end of function without return
Commit: c2923a6a14879106fca05700bd87ad2caa6b7382
https://github.com/llvm/llvm-project/commit/c2923a6a14879106fca05700bd87ad2caa6b7382
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/unittests/ASTMatchers/ASTMatchersTest.h
Log Message:
-----------
[NFC] rm unused arg
Commit: c59ab52b7fe9f1836c9d7c41f6970ba7d114dceb
https://github.com/llvm/llvm-project/commit/c59ab52b7fe9f1836c9d7c41f6970ba7d114dceb
Author: Julian Schmidt <git.julian.schmidt at gmail.com>
Date: 2024-10-31 (Thu, 31 Oct 2024)
Changed paths:
M clang/unittests/ASTMatchers/CMakeLists.txt
Log Message:
-----------
rm misplaced ARGS in add_custom_command
Compare: https://github.com/llvm/llvm-project/compare/deac0b7b4633%5E...c59ab52b7fe9
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