[clang] [llvm] [clang] Add `-verify-directives` cc1 flag (PR #179835)

[Erich Keane via cfe-commits]

================
@@ -3451,22 +3451,40 @@ are similar.
 Testing
 -------
 All functional changes to Clang should come with test coverage demonstrating
-the change in behavior.
+the change in behavior. There are four kinds of such tests.
+
+The first kind is unit tests. Such tests are placed in ``clang/test/unittest``.
+
+The second kind of tests ensures that only specific diagnostics are emitted at
+specific source lines. Those tests are using ``-verify`` mode of ``-cc1``,
+which is described below in
+:ref:`"Verifying Diagnostics" <verifying-diagnostics>`. Additional
+provisions for tests for C++ defect reports are described in ... section. 
+
+The third kind of tests checks AST dump. Such tests pass AST dump to
+`FileCheck <https://llvm.org/docs/CommandGuide/FileCheck.html>`_ utility,
+which check presence of certain patterns (or lack of thereof).
+
+The fourth kind of tests checks LLVM IR output of Clang in cases when checking
+diagnostics is not sufficient (e.g. when testing exception handling or object
+lifetime). Such tests pass LLVM IR output to
+`FileCheck <https://llvm.org/docs/CommandGuide/FileCheck.html>`_ utility,
+which check presence of certain IR patterns (or lack of thereof).
 
 .. _verifying-diagnostics:
 
 Verifying Diagnostics
 ^^^^^^^^^^^^^^^^^^^^^
 Clang ``-cc1`` supports the ``-verify`` command line option as a way to
-validate diagnostic behavior. This option will use special comments within the
-test file to verify that expected diagnostics appear in the correct source
-locations. If all of the expected diagnostics match the actual output of Clang,
-then the invocation will return normally. If there are discrepancies between
-the expected and actual output, Clang will emit detailed information about
-which expected diagnostics were not seen or which unexpected diagnostics were
-seen, etc. A complete example is:
+validate diagnostic behavior. This option will use special comments, called
+directives, within the test file to verify that expected diagnostics appear in
----------------
erichkeane wrote:

Hrmph... its a really bad word choice.  Let me think about it a touch.  This might just be a 'grumble and say urgh fine' kinda thing.

https://github.com/llvm/llvm-project/pull/179835