[clang-tidy] Proofread Contributing.rst (#149831)

Author: kazutakahirata

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 difficult 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 different 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 different 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 different
    meanings, see 1), and the same warning (or a slightly different one) may be
    issued by the check multiple times; :program:`clang-tidy` will deduplicate
    _identical_ warnings, but if the warnings are slightly different, 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 ``..``