docs: improve documentation for main command

Author: simschla

README.md

@@ -113,7 +113,11 @@ output =
 Usage: spotless [-hV] [-e=<encoding>] [-l=<lineEnding>] [--log-file=<logFile>]
                 [-m=<spotlessMode>] [-p=N] [-t=<targets>]... [-q | -v [-v]...]
                 [FORMATTING_STEPS]
-Runs spotless
+
+spotless is a command line interface (CLI) for the spotless code formatter.
+It can either check if your files are formatted according to your configuration
+or apply the formatting to the files.
+
   -e, --encoding=<encoding>  The encoding of the files to format.
                              (default: UTF-8)
   -h, --help                 Show this help message and exit.
@@ -134,7 +138,11 @@ Runs spotless
   -p, --parallelity=N        The number of parallel formatter threads to run.
                              (default: #cores * 0.5)
   -q, --quiet                Disable as much output as possible.
-  -t, --target=<targets>     The target files to format.
+  -t, --target=<targets>     The target files to format. Blobs are supported.
+                             Examples:
+                             -t 'src/**/*.java'
+                             -t 'src/**/*.kt'
+                             -t 'README.md'
   -v                         Enable verbose output. Multiple -v options
                                increase the verbosity (max 5).
   -V, --version              Print version information and exit.
@@ -153,8 +161,8 @@ Possible exit codes:
          for details).
        In CHECK mode, this means some files are not formatted properly (and
          might be fixed in APPLY mode).
-  -1   Some files did not converge. This can happen in APPLY mode when the
-         formatter does not converge on the file content.
+  -1   Some files did not converge. This can happen when one formatter does not
+         converge on the file content.
   -2   An exception occurred during execution.
 ```
 

app/src/main/java/com/diffplug/spotless/cli/SpotlessCLI.java

@@ -53,7 +53,9 @@
         mixinStandardHelpOptions = true,
         usageHelpAutoWidth = true,
         versionProvider = SpotlessCLIVersionProvider.class,
-        description = "Runs spotless",
+        description =
+                "%n@|magenta spotless|@ is a command line interface (CLI) for the spotless code formatter. "
+                        + "%nIt can either check if your files are formatted according to your configuration or apply the formatting to the files.%n",
         header =
                 """
                                  __  __             \s
@@ -108,7 +110,13 @@ public class SpotlessCLI implements SpotlessAction, SpotlessCommand, SpotlessAct
 
     @CommandLine.Option(
             names = {"--target", "-t"},
-            description = "The target files to format.")
+            description =
+                    """
+        The target files to format. Blobs are supported.
+        Examples:
+        -t 'src/**/*.java'
+        -t 'src/**/*.kt'
+        -t 'README.md'""")
     public List<String> targets;
 
     @CommandLine.Option(