Extend documentation of how to test clang-tidy checks.

[jdennett]

Summary

The documentation assumed expertise with FileCheck; many clang-tidy check
authors may not have significant exposure to FileCheck, and so it's worth
spending a few more words here to spell things out.

[alexfh]

Awesome! Thank you for adding clarity to this part.

Looks good with a couple of nits.

docs/clang-tidy/index.rst

550

Inline code snippets in rst should use double backquotes. I know, that's confusing, but it's what we have to deal with.

555

Put an underscore after FileCheck (as in line 549). This is a syntax for a named reference. See also http://llvm.org/docs/SphinxQuickstartTemplate.html

[alexfh]

docs/clang-tidy/index.rst

558

I'm not sure the term "matcher tests" is used anywhere else in our documentation. And it doesn't seem obvious to me either (if it refers to AST matchers, then it's just an implementation detail of clang-tidy checks, if it refers to the check patterns, then it's not a commonly used term for those either). I don't know what would be a good short replacement, maybe "clang-tidy lit tests" or just "clang-tidy tests".

[jdennett]

Thanks for the review. I've address your comments, and will check over the (presumed-final) diff before submitting.

docs/clang-tidy/index.rst

558

I went with clang-tidy tests. (The "matcher test" references are because I was thinking about some new matchers such as argumentsAre(arg1, ..., argn) at the same time, and didn't manage to do a complete context switch when working on these docs. Thanks for catching that.)

[jdennett]

Addressed review comments: double-backtick quoting, underscores for references
to FileCheck, and change "matcher tests" to "clang-tidy tests".

[alexfh]

docs/clang-tidy/index.rst

565

Looks like you missed this line when changing to double backquotes.

docs/clang-tidy/index.rst

 `lit`_ tests. Unit tests may be more convenient to test complex replacements
 with strict checks. `Lit`_ tests allow using partial text matching and regular
 expressions which makes them more suitable for writing compact tests for
 diagnostic messages.
 
 The ``check_clang_tidy.py`` script provides an easy way to test both
 diagnostic messages and fix-its. It filters out ``CHECK`` lines from the test
 file, runs :program:`clang-tidy` and verifies messages and fixes with two
-separate `FileCheck`_ invocations. To use the script, put a .cpp file with the
+separate `FileCheck`_ invocations: once with FileCheck's directive
+prefix set to `CHECK-MESSAGES`, validating the diagnostic messages,
+and once with the directive prefix set to `CHECK-FIXES`, running
+against the fixed code (i.e., the code after generated fixits are
+applied). In particular, `CHECK-FIXES:` can be used to check
+that code was not modified by fixits, by checking that it is present
+unchanged in the fixed code.  The full set of `FileCheck` directives
+is available (e.g., `CHECK-MESSAGES-SAME:`, `CHECK-MESSAGES-NOT:`), though
+typically the basic `CHECK` forms (`CHECK-MESSAGES` and `CHECK-FIXES`)
+are sufficient for matcher 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 matcher
+tests.
+
+An additional check enabled by ``check_clang_tidy.py`` ensures that
+if `CHECK-MESSAGES:` is used in a file then every warning or error
+must have an associated CHECK in that file.
+
+To use the ``check_clang_tidy.py`` script, put a .cpp file with the
 appropriate ``RUN`` line in the ``test/clang-tidy`` directory. Use
 ``CHECK-MESSAGES:`` and ``CHECK-FIXES:`` lines to write checks against
 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]]``
 substitutions and distinct function and variable names in the test code.