Document the -analyze opt flag in the LLVM testing guide (NFC)

[mehdi_amini]

Summary

This came up in a recent review, @mtrofin was wondering were was
this all documented and I couldn't find a reference to provide.

[mehdi_amini]

(minor rewording)

[aeubanks]

I'm trying to deprecate -analyze, given it doesn't really apply to NPM and there are better alternatives.
http://lists.llvm.org/pipermail/llvm-dev/2020-July/143372.html

One example of it making things harder is https://reviews.llvm.org/D83798.

[mehdi_amini]

Refer to the new PM convention instead of -analyze

[aeubanks]

lgtm with some minor wording nits

llvm/docs/TestingGuide.rst

50

reserved to test -> reserved to tests?

71

grammar nit: "An analysis is a pass that infers..." (or some other way)

[mehdi_amini]

Adjust wordings as suggested

[mehdi_amini]

(minor wording change)

llvm/docs/TestingGuide.rst

 in use although we run them much more often than nightly.
 
 Unit tests
 ----------
 
 Unit tests are written using `Google Test <https://github.com/google/googletest/blob/master/googletest/docs/primer.md>`_
 and `Google Mock <https://github.com/google/googletest/blob/master/googlemock/docs/for_dummies.md>`_
 and are located in the ``llvm/unittests`` directory.
+In general unit tests are reserved for targeting the support library and other
+generic data structure, we prefer relying on regression tests for testing
+transformations and analysis on the IR.
 
 Regression tests
 ----------------
 
 The regression tests are small pieces of code that test a specific
 feature of LLVM or trigger a specific bug in LLVM. The language they are
 written in depends on the part of LLVM being tested. These tests are driven by
 the :doc:`Lit <CommandGuide/lit>` testing tool (which is part of LLVM), and
 are located in the ``llvm/test`` directory.
 
 Typically when a bug is found in LLVM, a regression test containing just
 enough code to reproduce the problem should be written and placed
 somewhere underneath this directory. For example, it can be a small
 piece of LLVM IR distilled from an actual application or benchmark.
 
+Testing Analysis
+----------------
+
+An analysis is a pass that infer properties on some part of the IR and not
+transforming it. They are tested in general using the same infrastructure as the
+regression tests, by creating a separate "Printer" pass to consume the analysis
+result and print it on the standard output in a textual format suitable for
+FileCheck.
+See `llvm/test/Analysis/BranchProbabilityInfo/loop.ll <https://github.com/llvm/llvm-project/blob/master/llvm/test/Analysis/BranchProbabilityInfo/loop.ll>`_
+for an example of such test.
+
 ``test-suite``
 --------------
 
 The test suite contains whole programs, which are pieces of code which
 can be compiled and linked into a stand-alone program that can be
 executed. These programs are generally written in high level languages
 such as C or C++.
 

 to enable testing with valgrind and with leak checking enabled.
 
 To run individual tests or subsets of tests, you can use the ``llvm-lit``
 script which is built as part of LLVM. For example, to run the
 ``Integer/BitPacked.ll`` test by itself you can run:
 
 .. code-block:: bash
 
-    % llvm-lit ~/llvm/test/Integer/BitPacked.ll 
+    % llvm-lit ~/llvm/test/Integer/BitPacked.ll
 
 or to run all of the ARM CodeGen tests:
 
 .. code-block:: bash
 
     % llvm-lit ~/llvm/test/CodeGen/ARM
 
 For more information on using the :program:`lit` tool, see ``llvm-lit --help``

 various features of LLVM and to ensure that regressions do not occur.
 The directory is broken into several sub-directories, each focused on a
 particular area of LLVM.
 
 Writing new regression tests
 ----------------------------
 
 The regression test structure is very simple, but does require some
-information to be set. This information is gathered via ``configure``
+information to be set. This information is gathered via ``cmake``
 and is written to a file, ``test/lit.site.cfg`` in the build directory.
 The ``llvm/test`` Makefile does this work for you.
 
 In order for the regression tests to work, each directory of tests must
 have a ``lit.local.cfg`` file. :program:`lit` looks for this file to determine
 how to run the tests. This file is just Python code and thus is very
 flexible, but we've standardized it for the LLVM regression tests. If
 you're adding a directory of tests, just copy ``lit.local.cfg`` from
.. code-block:: llvm
     ; This test is disabled on Linux.
     ; UNSUPPORTED: -linux-
     ; This test is expected to fail on PowerPC.
     ; XFAIL: powerpc
 
 ``REQUIRES`` and ``UNSUPPORTED`` and ``XFAIL`` all accept a comma-separated
 list of boolean expressions. The values in each expression may be:
 
-- Features added to ``config.available_features`` by 
+- Features added to ``config.available_features`` by
   configuration files such as ``lit.cfg``.
 - Substrings of the target triple (``UNSUPPORTED`` and ``XFAIL`` only).
 
 | ``REQUIRES`` enables the test if all expressions are true.
 | ``UNSUPPORTED`` disables the test if any expression is true.
 | ``XFAIL`` expects the test to fail if any expression is true.
 
 As a special case, ``XFAIL: *`` is expected to fail everywhere.
``%{pathsep}``
    Expands to the path separator, i.e. ``:`` (or ``;`` on Windows).
 
 ``%/s, %/S, %/t, %/T:``
 
   Act like the corresponding substitution above but replace any ``\``
   character with a ``/``. This is useful to normalize path separators.
 
    Example: ``%s:  C:\Desktop Files/foo_test.s.tmp``
-   
    Example: ``%/s: C:/Desktop Files/foo_test.s.tmp``
 
 ``%:s, %:S, %:t, %:T:``
 
   Act like the corresponding substitution above but remove colons at
   the beginning of Windows paths. This is useful to allow concatenation
   of absolute paths on Windows to produce a legal path.