cmd/cue: mention vet-c's three behaviours

This improves the cue-vet help text by mentioning the different
behaviours engaged when the --concrete/-c flag is:

- absent
- present without a value / set with -c=true
- set with -c=false

The flag's tri-state behaviour is being considered in #2120 but,
irrespective of any changes that might result, the current behaviour is
undocumented outside the source code; hence this change.

The -c flag's single line help message is updated to mention -c=false.

The command is also introduced (via its opening line) with a complete
sentence that starts with a capital letter and ends with a period,
giving the Go-doc-unware user more confidence that they're reading a
complete sentence and not some truncated fragment.

Also: correct a cue/CUE capitalisation typo; make a compound sentence
flow better.

The cue-help-eval text also mentions this flag, but it's not clear to me
that its handling of this flag is identical so the same change isn't
applied there.

For #2120.

Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: I687840fe5bdcbc464ee4fdfcd6e6f0fba9ef327a
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1207991
Reviewed-by: Daniel Martí <[email protected]>
TryBot-Result: CUEcueckoo <[email protected]>

Author: jpluscplusm

cmd/cue/cmd/vet.go

@@ -22,10 +22,21 @@ import (
 	"cuelang.org/go/cue/errors"
 )
 
-const vetDoc = `vet validates CUE and other data files
+const vetDoc = `The vet command validates CUE and other data files.
 
-By default it will only validate if there are no errors.
-The -c validates that all regular fields are concrete.
+The command is silent when it succeeds, emitting no output and an exit code of
+zero. Otherwise, errors are reported and the command returns a non-zero exit
+code.
+
+vet starts by ensuring that there are no validation errors. If errors are found
+then they are reported and the command exits.
+
+If there are no validation errors then, by default, vet checks that the result
+of the evaluation is concrete. It reports an error if the evaluation contains
+any regular fields that have non-concrete values.
+Skip this step by specifying -c=false, which permits regular fields to have
+non-concrete values. Specify -c/-c=true to report errors mentioning which
+regular fields have non-concrete values.
 
 
 Checking non-CUE files
@@ -39,12 +50,12 @@ currently supported:
 	TOML       .toml
 	TEXT       .txt  (validate a single string value)
 
-To activate this mode, the non-cue files must be explicitly mentioned on the
+To activate this mode, the non-CUE files must be explicitly mentioned on the
 command line. There must also be at least one CUE file to hold the constraints.
 
 In this mode, each file will be verified against a CUE constraint. If the files
-contain multiple objects (such as using --- in YAML), they will all be verified
-individually.
+contain multiple objects (such as using --- in YAML) then each object will be
+verified individually.
 
 By default, each file is checked against the root of the loaded CUE files.
 The -d can be used to only verify files against the result of an expression
@@ -75,7 +86,7 @@ func newVetCmd(c *Command) *cobra.Command {
 	addInjectionFlags(cmd.Flags(), false, false)
 
 	cmd.Flags().BoolP(string(flagConcrete), "c", false,
-		"require the evaluation to be concrete")
+		"require the evaluation to be concrete, or set -c=false to allow incomplete values")
 
 	return cmd
 }