[llvm] 6dda6ff - [FileCheck] Fix up -dump-input* docs

[Joel E. Denny via llvm-commits]

Author: Joel E. Denny
Date: 2020-07-10T17:21:01-04:00
New Revision: 6dda6ff0e094b667311dbd7a46d4e36aa787e033

URL: https://github.com/llvm/llvm-project/commit/6dda6ff0e094b667311dbd7a46d4e36aa787e033
DIFF: https://github.com/llvm/llvm-project/commit/6dda6ff0e094b667311dbd7a46d4e36aa787e033.diff

LOG: [FileCheck] Fix up -dump-input* docs

In FileCheck.rst, add `-dump-input-context` and `-dump-input-filter`,
and fix some `-dump-input` documentation.

In `FileCheck -help`, `cl::value_desc("kind")` is being ignored for
`-dump-input-filter`, so just drop it.

Extend `-dump-input=help` to mention FILECHECK_OPTS.

Added: 
    

Modified: 
    llvm/docs/CommandGuide/FileCheck.rst
    llvm/utils/FileCheck/FileCheck.cpp

Removed: 
    


################################################################################
diff  --git a/llvm/docs/CommandGuide/FileCheck.rst b/llvm/docs/CommandGuide/FileCheck.rst
index cb5db00c7b12..0a0c2c5dd25d 100644
--- a/llvm/docs/CommandGuide/FileCheck.rst
+++ b/llvm/docs/CommandGuide/FileCheck.rst
@@ -103,11 +103,37 @@ and from the command line.
   -verify``. With this option FileCheck will verify that input does not contain
   warnings not covered by any ``CHECK:`` patterns.
 
-.. option:: --dump-input <mode>
+.. option:: --dump-input <value>
 
   Dump input to stderr, adding annotations representing currently enabled
-  diagnostics.  Do this either 'always', on 'fail' (default), or 'never'.
-  Specify 'help' to explain the dump format and quit.
+  diagnostics.  When there are multiple occurrences of this option, the
+  ``<value>`` that appears earliest in the list below has precedence.  The
+  default is ``fail``.
+
+  * ``help``   - Explain input dump and quit
+  * ``always`` - Always dump input
+  * ``fail``   - Dump input on failure
+  * ``never``  - Never dump input
+
+.. option:: --dump-input-context <N>
+
+  In the dump requested by ``--dump-input``, print ``<N>`` input lines before
+  and ``<N>`` input lines after any lines specified by ``--dump-input-filter``.
+  When there are multiple occurrences of this option, the largest specified
+  ``<N>`` has precedence.  The default is 5.
+
+.. option:: --dump-input-filter <value>
+
+  In the dump requested by ``--dump-input``, print only input lines of kind
+  ``<value>`` plus any context specified by ``--dump-input-context``.  When
+  there are multiple occurrences of this option, the ``<value>`` that appears
+  earliest in the list below has precedence.  The default is ``error`` when
+  ``--dump-input=fail``, and it's ``all`` when ``--dump-input=always``.
+
+  * ``all``             - All input lines
+  * ``annotation-full`` - Input lines with annotations
+  * ``annotation``      - Input lines with starting points of annotations
+  * ``error``           - Input lines with starting points of error annotations
 
 .. option:: --enable-var-scope
 
@@ -137,15 +163,15 @@ and from the command line.
 
 .. option:: -v
 
-  Print good directive pattern matches.  However, if ``-input-dump=fail`` or
-  ``-input-dump=always``, add those matches as input annotations instead.
+  Print good directive pattern matches.  However, if ``-dump-input=fail`` or
+  ``-dump-input=always``, add those matches as input annotations instead.
 
 .. option:: -vv
 
   Print information helpful in diagnosing internal FileCheck issues, such as
   discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,
   and ``CHECK-NOT:`` patterns that do not have matches.  Implies ``-v``.
-  However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that
+  However, if ``-dump-input=fail`` or ``-dump-input=always``, just add that
   information as input annotations instead.
 
 .. option:: --allow-deprecated-dag-overlap

diff  --git a/llvm/utils/FileCheck/FileCheck.cpp b/llvm/utils/FileCheck/FileCheck.cpp
index 8bf1dd2e9b49..fa79c5e89489 100644
--- a/llvm/utils/FileCheck/FileCheck.cpp
+++ b/llvm/utils/FileCheck/FileCheck.cpp
@@ -140,12 +140,11 @@ enum DumpInputFilterValue {
 static cl::list<DumpInputFilterValue> DumpInputFilters(
     "dump-input-filter",
     cl::desc("In the dump requested by -dump-input, print only input lines of\n"
-             "kind <kind> plus any context specified by -dump-input-context.\n"
-             "When there are multiple occurrences of this option, the <kind>\n"
+             "kind <value> plus any context specified by -dump-input-context.\n"
+             "When there are multiple occurrences of this option, the <value>\n"
              "that appears earliest in the list below has precedence.  The\n"
              "default is 'error' when -dump-input=fail, and it's 'all' when\n"
              "-dump-input=always.\n"),
-    cl::value_desc("kind"),
     cl::values(clEnumValN(DumpInputFilterAll, "all", "All input lines"),
                clEnumValN(DumpInputFilterAnnotationFull, "annotation-full",
                           "Input lines with annotations"),
@@ -226,14 +225,21 @@ static void DumpInputAnnotationHelp(raw_ostream &OS) {
      << "explain the input dump printed by FileCheck.\n"
      << "\n"
      << "Related command-line options:\n"
+     << "\n"
      << "  - -dump-input=<value> enables or disables the input dump\n"
-     << "  - -dump-input-filter=<kind> filters the input lines\n"
+     << "  - -dump-input-filter=<value> filters the input lines\n"
      << "  - -dump-input-context=<N> adjusts the context of filtered lines\n"
      << "  - -v and -vv add more annotations\n"
      << "  - -color forces colors to be enabled both in the dump and below\n"
      << "  - -help documents the above options in more detail\n"
      << "\n"
-     << "Input dump annotation format:\n";
+     << "These options can also be set via FILECHECK_OPTS.  For example, for\n"
+     << "maximum debugging output on failures:\n"
+     << "\n"
+     << "  $ FILECHECK_OPTS='-dump-input-filter=all -vv -color' ninja check\n"
+     << "\n"
+     << "Input dump annotation format:\n"
+     << "\n";
 
   // Labels for input lines.
   OS << "  - ";