Add completion hints to maintained commands

completion.go

@@ -51,7 +51,9 @@ func validCompletionExecutable(name string) bool {
 
 // CompletionChoice is a literal suggested value and its optional description.
 type CompletionChoice struct {
-	Value       string
+	// Value is inserted as data; it is not interpreted as shell source.
+	Value string
+	// Description is optional context displayed by shells that support it.
 	Description string
 }
 
@@ -71,7 +73,10 @@ const (
 	completionDirectories
 )
 
-// CompleteChoices suggests literal values. The supplied slice is copied.
+// CompleteChoices suggests literal values matching the current value prefix.
+// The supplied slice is copied. An empty list produces no suggestions. Empty
+// values and values containing a newline, tab, or NUL cannot be presented as
+// suggestions, but remain valid input if the command's converter accepts them.
 func CompleteChoices(choices ...CompletionChoice) CompletionHint {
 	return CompletionHint{kind: completionChoices, choices: append([]CompletionChoice(nil), choices...)}
 }