================ @@ -337,89 +344,93 @@ a starting point for your test cases. A rough outline of the process looks like - Repeat the process until all aspects of your check are covered by tests. The quickest way to prototype your matcher is to use :program:`clang-query` to -interactively build up your matcher. For complicated matchers, build up a matching -expression incrementally and use :program:`clang-query`'s ``let`` command to save named -matching expressions to simplify your matcher. +interactively build up your matcher. For complicated matchers, build up a +matching expression incrementally and use :program:`clang-query`'s ``let`` +command to save named matching expressions to simplify your matcher. .. code-block:: console clang-query> let c1 cxxRecordDecl() clang-query> match c1 -Alternatively, pressing the tab key after a previous matcher's open parentheses -would also show which matchers can be chained with the previous matcher, -though some matchers that work may not be listed. Note that tab completion +Alternatively, pressing the tab key after a previous matcher's open parentheses +would also show which matchers can be chained with the previous matcher, +though some matchers that work may not be listed. Note that tab completion does not currently work on Windows. -Just like breaking up a huge function into smaller chunks with -intention-revealing names can help you understand a complex algorithm, breaking -up a matcher into smaller matchers with intention-revealing names can help -you understand a complicated matcher. +Just like breaking up a huge function into smaller chunks with +intention-revealing names can help you understand a complex algorithm, breaking +up a matcher into smaller matchers with intention-revealing names can help +you understand a complicated matcher. -Once you have a working :program:`clang-query` matcher, the C++ API matchers -will be the same or similar to your interactively constructed matcher (there -can be cases where they differ slightly). You can use local variables to preserve -your intention-revealing names that you applied to nested matchers. +Once you have a working :program:`clang-query` matcher, the C++ API matchers +will be the same or similar to your interactively constructed matcher (there +can be cases where they differ slightly). You can use local variables to +preserve your intention-revealing names that you applied to nested matchers. Creating private matchers ^^^^^^^^^^^^^^^^^^^^^^^^^ -Sometimes you want to match a specific aspect of the AST that isn't provided by the -existing AST matchers. You can create your own private matcher using the same -infrastructure as the public matchers. A private matcher can simplify the processing -in your ``check`` method by eliminating complex hand-crafted AST traversal of the -matched nodes. Using the private matcher allows you to select the desired portions -of the AST directly in the matcher and refer to it by a bound name in the ``check`` -method. +Sometimes you want to match a specific aspect of the AST that isn't provided +by the existing AST matchers. You can create your own private matcher using +the same infrastructure as the public matchers. A private matcher can +simplify the processing in your ``check`` method by eliminating complex +hand-crafted AST traversal of the matched nodes. Using the private matcher +allows you to select the desired portions of the AST directly in the matcher +and refer to it by a bound name in the ``check`` method. Unit testing helper code ^^^^^^^^^^^^^^^^^^^^^^^^ -Private custom matchers are a good example of auxiliary support code for your check -that can be tested with a unit test. It will be easier to test your matchers or -other support classes by writing a unit test than by writing a ``FileCheck`` integration -test. The ``ASTMatchersTests`` target contains unit tests for the public AST matcher -classes and is a good source of testing idioms for matchers. +Private custom matchers are a good example of auxiliary support code for your +check that can be tested with a unit test. It will be easier to test your +matchers or other support classes by writing a unit test than by writing a +``FileCheck`` integration test. The ``ASTMatchersTests`` target contains unit +tests for the public AST matcher classes and is a good source of testing +idioms for matchers. -You can build the Clang-tidy unit tests by building the ``ClangTidyTests`` target. -Test targets in LLVM and Clang are excluded from the "build all" style action of -IDE-based CMake generators, so you need to explicitly build the target for the unit -tests to be built. +You can build the Clang-tidy unit tests by building the ``ClangTidyTests`` +target. Test targets in LLVM and Clang are excluded from the "build all" style +action of IDE-based CMake generators, so you need to explicitly build the +target for the unit tests to be built. Making your check robust ^^^^^^^^^^^^^^^^^^^^^^^^ -Once you've covered your check with the basic "happy path" scenarios, you'll want to -torture your check with as many edge cases as you can cover in order to ensure your -check is robust. Running your check on a large code base, such as Clang/LLVM, is a -good way to catch things you forgot to account for in your matchers. However, the -LLVM code base may be insufficient for testing purposes as it was developed against a -particular set of coding styles and quality measures. The larger the corpus of code -the check is tested against, the higher confidence the community will have in the -check's efficacy and false-positive rate. +Once you've covered your check with the basic "happy path" scenarios, you'll +want to torture your check with as many edge cases as you can cover in order to +ensure your check is robust. Running your check on a large code base, such as +Clang/LLVM, is a good way to catch things you forgot to account for in your +matchers. However, the LLVM code base may be insufficient for testing purposes +as it was developed against a particular set of coding styles and quality +measures. The larger the corpus of code the check is tested against, the +higher confidence the community will have in the check's efficacy and +false-positive rate. Some suggestions to ensure your check is robust: - Create header files that contain code matched by your check. - Validate that fix-its are properly applied to test header files with - :program:`clang-tidy`. You will need to perform this test manually until + :program:`clang-tidy`. You will need to perform this test manually until automated support for checking messages and fix-its is added to the ``check_clang_tidy.py`` script. - Define macros that contain code matched by your check. - Define template classes that contain code matched by your check. - Define template specializations that contain code matched by your check. - Test your check under both Windows and Linux environments. -- Watch out for high false-positive rates. Ideally, a check would have no false - positives, but given that matching against an AST is not control- or data flow- - sensitive, a number of false positives are expected. The higher the - false-positive rate, the less likely the check will be adopted in practice. - Mechanisms should be put in place to help the user manage false positives. +- Watch out for high false-positive rates. Ideally, a check would have no ---------------- EugeneZelenko wrote:
I'm not sure about dash in `false-positive`, but I'm not native English speaker. https://github.com/llvm/llvm-project/pull/168722 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
