[FileCheck] Improve -dump-input documentation

[jdenny]

Summary

Document the default of fail in -help. Extend -dump-input=help
to help users find related command-line options, but let -help
provide their full documentation.

[jdenny]

Ping.

[probinson]

LGTM.

[jdenny]

Thanks!

llvm/test/FileCheck/dump-input-enable.txt

 ; END.
 
 ;--------------------------------------------------
 ; Check the output.
 ;--------------------------------------------------
 
 ; HELP-NOT: {{.}}
 ; HELP: The following description was requested by -dump-input=help
-; HELP: try{{.*}}-color
+; HELP: - colors {{.*}}
 ; HELP-NOT: {{.}}
 
 ; Trace is sometimes suppressed.
 ; TRACE:       {{.*}}remark:{{.*}}
 ; NOTRACE-NOT: remark:
 
 ; Error diagnostics are never suppressed.
 ; ERR: {{.*}}error:{{.*}}

llvm/utils/FileCheck/FileCheck.cpp

enum DumpInputValue {
   DumpInputHelp
 };
 
 static cl::list<DumpInputValue> DumpInputs(
     "dump-input",
     cl::desc("Dump input to stderr, adding annotations representing\n"
              "currently enabled diagnostics.  When there are multiple\n"
              "occurrences of this option, the <value> that appears earliest\n"
-             "in the list below has precedence.\n"),
+             "in the list below has precedence.  The default is 'fail'.\n"),
     cl::value_desc("mode"),
-    cl::values(clEnumValN(DumpInputHelp, "help",
-                          "Explain dump format and quit"),
+    cl::values(clEnumValN(DumpInputHelp, "help", "Explain input dump and quit"),
                clEnumValN(DumpInputAlways, "always", "Always dump input"),
                clEnumValN(DumpInputFail, "fail", "Dump input on failure"),
                clEnumValN(DumpInputNever, "never", "Never dump input")));
 
 typedef cl::list<std::string>::const_iterator prefix_iterator;
 
 
 
static MarkerStyle GetMarker(FileCheckDiag::MatchType MatchTy) {
   case FileCheckDiag::MatchFuzzy:
     return MarkerStyle('?', raw_ostream::MAGENTA, "possible intended match");
   }
   llvm_unreachable_internal("unexpected match type");
 }
 
 static void DumpInputAnnotationHelp(raw_ostream &OS) {
   OS << "The following description was requested by -dump-input=help to\n"
-     << "explain the input annotations printed by -dump-input=always and\n"
-     << "-dump-input=fail:\n\n";
+     << "explain the input dump printed by FileCheck.\n"
+     << "\n"
+     << "Related command-line options:\n"
+     << "  - -dump-input=<value> enables or disables the input dump\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";
 
   // Labels for input lines.
   OS << "  - ";
   WithColor(OS, raw_ostream::SAVEDCOLOR, true) << "L:";
   OS << "     labels line number L of the input file\n";
 
   // Labels for annotation lines.
   OS << "  - ";
static void DumpInputAnnotationHelp(raw_ostream &OS) {
   OS << ", ";
   WithColor(OS, raw_ostream::RED, true) << "error";
   OS << ", ";
   WithColor(OS, raw_ostream::MAGENTA, true) << "fuzzy match";
   OS << ", ";
   WithColor(OS, raw_ostream::CYAN, true, false) << "discarded match";
   OS << ", ";
   WithColor(OS, raw_ostream::CYAN, true, true) << "unmatched input";
-  OS << "\n\n"
-     << "If you are not seeing color above or in input dumps, try: -color\n";
+  OS << "\n";
 }
 
 /// An annotation for a single input line.
 struct InputAnnotation {
   /// The index of the match result across all checks
   unsigned DiagIndex;
   /// The label for this annotation.
   std::string Label;
int main(int argc, char **argv) {
   std::vector<FileCheckDiag> Diags;
   int ExitCode = FC.checkInput(SM, InputFileText,
                                DumpInput == DumpInputNever ? nullptr : &Diags)
                      ? EXIT_SUCCESS
                      : 1;
   if (DumpInput == DumpInputAlways ||
       (ExitCode == 1 && DumpInput == DumpInputFail)) {
     errs() << "\n"
-           << "Input file: "
-           << InputFilename
-           << "\n"
+           << "Input file: " << InputFilename << "\n"
            << "Check file: " << CheckFilename << "\n"
            << "\n"
-           << "-dump-input=help describes the format of the following dump.\n"
+           << "-dump-input=help explains the following input dump.\n"
            << "\n";
     std::vector<InputAnnotation> Annotations;
     unsigned LabelWidth;
     BuildInputAnnotations(SM, CheckFileBufferID, ImpPatBufferIDRange, Diags,
                           Annotations, LabelWidth);
     DumpAnnotatedInput(errs(), Req, InputFileText, Annotations, LabelWidth);
   }
 
   return ExitCode;
 }