[clang][test] add testing for the AST matcher reference #94248

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

…expressive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[clang][test] add testing for the AST matcher reference #94248

[clang][test] add testing for the AST matcher reference #94248

Commits on Jul 12, 2024

[clang][test] add testing for the AST matcher reference #94248

Are you sure you want to change the base?

[clang][test] add testing for the AST matcher reference #94248

Commits on Jul 12, 2024