Author: Kazu Hirata Date: 2025-07-21T14:59:35-07:00 New Revision: f0bbe73cf101b82a9b02b8466f562e3173d25523
URL: https://github.com/llvm/llvm-project/commit/f0bbe73cf101b82a9b02b8466f562e3173d25523 DIFF: https://github.com/llvm/llvm-project/commit/f0bbe73cf101b82a9b02b8466f562e3173d25523.diff LOG: [clang-tidy] Proofread Contributing.rst (#149831) Added: Modified: clang-tools-extra/docs/clang-tidy/Contributing.rst Removed: ################################################################################ diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.rst b/clang-tools-extra/docs/clang-tidy/Contributing.rst index 66c0abadc6a40..ad12b2343d1e9 100644 --- a/clang-tools-extra/docs/clang-tidy/Contributing.rst +++ b/clang-tools-extra/docs/clang-tidy/Contributing.rst @@ -19,11 +19,11 @@ check, the rest of this document explains how to do this. There are a few tools particularly useful when developing clang-tidy checks: * ``add_new_check.py`` is a script to automate the process of adding a new - check, it will create the check, update the CMake file and create a test; + check; it will create the check, update the CMake file and create a test. * ``rename_check.py`` does what the script name suggests, renames an existing - check; + check. * :program:`pp-trace` logs method calls on `PPCallbacks` for a source file - and is invaluable in understanding the preprocessor mechanism; + and is invaluable in understanding the preprocessor mechanism. * :program:`clang-query` is invaluable for interactive prototyping of AST matchers and exploration of the Clang AST; * `clang-check`_ with the ``-ast-dump`` (and optionally ``-ast-dump-filter``) @@ -47,7 +47,7 @@ implemented as a: + *Clang diagnostic*: if the check is generic enough, targets code patterns that most probably are bugs (rather than style or readability issues), can be - implemented effectively and with extremely low false positive rate, it may + implemented effectively and with extremely low false-positive rate, it may make a good Clang diagnostic. + *Clang static analyzer check*: if the check requires some sort of control flow @@ -77,7 +77,7 @@ make sure that you enable the ``clang`` and ``clang-tools-extra`` projects to build :program:`clang-tidy`. Because your new check will have associated documentation, you will also want to install `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and enable it in the CMake configuration. -To save build time of the core Clang libraries you may want to only enable the ``X86`` +To save build time of the core Clang libraries, you may want to only enable the ``X86`` target in the CMake configuration. @@ -130,7 +130,7 @@ So you have an idea of a useful check for :program:`clang-tidy`. First, if you're not familiar with LLVM development, read through the `Getting Started with the LLVM System`_ document for instructions on setting up your workflow and the `LLVM Coding Standards`_ document to familiarize yourself with the coding -style used in the project. For code reviews we currently use `LLVM Github`_, +style used in the project. For code reviews, we currently use `LLVM Github`_, though historically we used Phabricator. .. _Getting Started with the LLVM System: https://llvm.org/docs/GettingStarted.html @@ -141,7 +141,7 @@ Next, you need to decide which module the check belongs to. Modules are located in subdirectories of `clang-tidy/ <https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy/>`_ and contain checks targeting a certain aspect of code quality (performance, -readability, etc.), certain coding style or standard (Google, LLVM, CERT, etc.) +readability, etc.), a certain coding style or standard (Google, LLVM, CERT, etc.) or a widely used API (e.g. MPI). Their names are the same as the user-facing check group names described :ref:`above <checks-groups-table>`. @@ -166,7 +166,7 @@ The ``add_new_check.py`` script will: * create a documentation file and include it into the ``docs/clang-tidy/checks/list.rst``. -Let's see in more detail at the check class definition: +Let's look at the check class definition in more detail: .. code-block:: c++ @@ -200,7 +200,7 @@ In our case the check needs to operate on the AST level and it overrides the preprocessor level, we'd need instead to override the ``registerPPCallbacks`` method. -In the ``registerMatchers`` method we create an AST Matcher (see `AST Matchers`_ +In the ``registerMatchers`` method, we create an AST Matcher (see `AST Matchers`_ for more information) that will find the pattern in the AST that we want to inspect. The results of the matching are passed to the ``check`` method, which can further inspect them and report diagnostics. @@ -320,7 +320,7 @@ the ``add_new_check.py`` script: Developing your check incrementally ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The best way to develop your check is to start with the simple test cases and increase +The best way to develop your check is to start with simple test cases and increase complexity incrementally. The test file created by the ``add_new_check.py`` script is a starting point for your test cases. A rough outline of the process looks like this: @@ -393,7 +393,7 @@ good way to catch things you forgot to account for in your matchers. However, t 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. +check's efficacy and false-positive rate. Some suggestions to ensure your check is robust: @@ -406,10 +406,10 @@ Some suggestions to ensure your check is robust: - 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 +- 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. + 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. - There are two primary mechanisms for managing false positives: supporting a code pattern which allows the programmer to silence the diagnostic in an ad @@ -428,10 +428,10 @@ Documenting your check The ``add_new_check.py`` script creates entries in the `release notes <https://clang.llvm.org/extra/ReleaseNotes.html>`_, the list of checks and a new file for the check documentation itself. It is recommended that you -have a concise summation of what your check does in a single sentence that is repeated +have a concise summary of what your check does in a single sentence that is repeated in the release notes, as the first sentence in the doxygen comments in the header file for your check class and as the first sentence of the check documentation. Avoid the -phrase "this check" in your check summation and check documentation. +phrase "this check" in your check summary and check documentation. If your check relates to a published coding guideline (C++ Core Guidelines, MISRA, etc.) or style guide, provide links to the relevant guideline or style guide sections in your @@ -443,10 +443,10 @@ If there are exceptions or limitations to your check, document them thoroughly. will help users understand the scope of the diagnostics and fix-its provided by the check. Building the target ``docs-clang-tools-html`` will run the Sphinx documentation generator -and create documentation HTML files in the tools/clang/tools/extra/docs/html directory in +and create HTML documentation files in the tools/clang/tools/extra/docs/html directory in your build tree. Make sure that your check is correctly shown in the release notes and the list of checks. Make sure that the formatting and structure of your check's documentation -looks correct. +look correct. Registering your Check @@ -503,11 +503,11 @@ Configuring Checks If a check needs configuration options, it can access check-specific options using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check -constructor. In this case the check should also override the +constructor. In this case, the check should also override the ``ClangTidyCheck::storeOptions`` method to make the options provided by the check discoverable. This method lets :program:`clang-tidy` know which options the check implements and what the current values are (e.g. for the -``-dump-config`` command line option). +``-dump-config`` command-line option). .. code-block:: c++ @@ -576,7 +576,7 @@ typically the basic ``CHECK`` forms (``CHECK-MESSAGES`` and ``CHECK-FIXES``) are sufficient for clang-tidy tests. Note that the `FileCheck`_ documentation mostly assumes the default prefix (``CHECK``), and hence describes the directive as ``CHECK:``, ``CHECK-SAME:``, ``CHECK-NOT:``, etc. -Replace ``CHECK`` by either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for +Replace ``CHECK`` with either ``CHECK-FIXES`` or ``CHECK-MESSAGES`` for clang-tidy tests. An additional check enabled by ``check_clang_tidy.py`` ensures that @@ -590,7 +590,7 @@ appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use diagnostic messages and fixed code. It's advised to make the checks as specific as possible to avoid checks matching -to incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]`` +incorrect parts of the input. Use ``[[@LINE+X]]``/``[[@LINE-X]]`` substitutions and distinct function and variable names in the test code. Here's an example of a test using the ``check_clang_tidy.py`` script (the full @@ -606,7 +606,7 @@ source code is at `test/clang-tidy/checkers/google/readability-casting.cpp`_): // CHECK-FIXES: int b = a; } -To check more than one scenario in the same test file use +To check more than one scenario in the same test file, use ``-check-suffix=SUFFIX-NAME`` on ``check_clang_tidy.py`` command line or ``-check-suffixes=SUFFIX-NAME-1,SUFFIX-NAME-2,...``. With ``-check-suffix[es]=SUFFIX-NAME`` you need to replace your ``CHECK-*`` @@ -631,15 +631,15 @@ There are many dark corners in the C++ language, and it may be diff icult to make your check work perfectly in all cases, especially if it issues fix-it hints. The most frequent pitfalls are macros and templates: -1. code written in a macro body/template definition may have a diff erent meaning - depending on the macro expansion/template instantiation; -2. multiple macro expansions/template instantiations may result in the same code +1. Code written in a macro body/template definition may have a diff erent meaning + depending on the macro expansion/template instantiation. +2. Multiple macro expansions/template instantiations may result in the same code being inspected by the check multiple times (possibly, with diff erent meanings, see 1), and the same warning (or a slightly diff erent one) may be issued by the check multiple times; :program:`clang-tidy` will deduplicate _identical_ warnings, but if the warnings are slightly diff erent, all of them - will be shown to the user (and used for applying fixes, if any); -3. making replacements to a macro body/template definition may be fine for some + will be shown to the user (and used for applying fixes, if any). +3. Making replacements to a macro body/template definition may be fine for some macro expansions/template instantiations, but easily break some other expansions/instantiations. @@ -667,7 +667,7 @@ code quality and catch potential issues. While :program:`clang-tidy` is not currently enforced in CI, following this practice helps maintain code consistency and prevent common errors. -Here's useful command to check your staged changes: +Here's a useful command to check your staged changes: .. code-block:: console @@ -698,7 +698,7 @@ names of the checks to enable. $ clang-tidy --checks=-*,my-explicit-constructor -list-checks -load myplugin.so -There is no expectations regarding ABI and API stability, so the plugin must be +There are no expectations regarding ABI and API stability, so the plugin must be compiled against the version of clang-tidy that will be loading the plugin. The plugins can use threads, TLS, or any other facilities available to in-tree @@ -720,10 +720,10 @@ and write a version of `check_clang_tidy.py`_ to suit your needs. Running clang-tidy on LLVM -------------------------- -To test a check it's best to try it out on a larger code base. LLVM and Clang +To test a check, it's best to try it out on a larger code base. LLVM and Clang are the natural targets as you already have the source code around. The most convenient way to run :program:`clang-tidy` is with a compile command database; -CMake can automatically generate one, for a description of how to enable it see +CMake can automatically generate one; for a description of how to enable it, see `How To Setup Clang Tooling For LLVM`_. Once ``compile_commands.json`` is in place and a working version of :program:`clang-tidy` is in ``PATH`` the entire code base can be analyzed with ``clang-tidy/tool/run-clang-tidy.py``. The script @@ -735,18 +735,18 @@ warnings and errors. The script provides multiple configuration flags. * The default set of checks can be overridden using the ``-checks`` argument, - taking the identical format as :program:`clang-tidy` does. For example + taking the identical format as :program:`clang-tidy` does. For example, ``-checks=-*,modernize-use-override`` will run the ``modernize-use-override`` check only. -* To restrict the files examined you can provide one or more regex arguments +* To restrict the files examined, you can provide one or more regex arguments that the file names are matched against. ``run-clang-tidy.py clang-tidy/.*Check\.cpp`` will only analyze `clang-tidy` checks. It may also be necessary to restrict the header files that warnings are displayed from by using the ``-header-filter`` and ``-exclude-header-filter`` flags. They have the same behavior as the corresponding :program:`clang-tidy` flags. -* To apply suggested fixes ``-fix`` can be passed as an argument. This gathers +* To apply suggested fixes, ``-fix`` can be passed as an argument. This gathers all changes in a temporary directory and applies them. Passing ``-format`` will run clang-format over changed lines. @@ -795,7 +795,7 @@ There is only one argument that controls profile storage: * ``-store-check-profile=<prefix>`` - By default reports are printed in tabulated format to stderr. When this option + By default, reports are printed in tabulated format to stderr. When this option is passed, these per-TU profiles are instead stored as JSON. If the prefix is not an absolute path, it is considered to be relative to the directory from where you have run :program:`clang-tidy`. All ``.`` and ``..`` _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
