Document flag declaration rules

command.go

@@ -90,10 +90,14 @@ type Supplied[T any] struct {
 
 // FlagMeta describes a command flag. Required applies when execution prepares
 // the selected command; help reports the metadata without requiring the value.
+// Invalid declarations are reported when installed.
 type FlagMeta struct {
-	// Name is the flag name without leading dashes.
+	// Name is a nonempty long name without leading dashes. It consists of
+	// Unicode lowercase letters or digits in segments separated by single
+	// hyphens; digit-leading and numeric-only names are valid. The names help,
+	// quiet, verbose, debug, progress and format are reserved.
 	Name string
-	// Short is an optional one-byte spelling.
+	// Short is an optional one-byte spelling other than '-' or the reserved 'h'.
 	Short string
 	// Usage briefly describes the flag.
 	Usage string
@@ -352,6 +356,7 @@ func Alias(path, target string) RoutingRule {
 // wherever its canonical target flag is available and contributes nothing on
 // commands without that flag. Identical mappings are accepted; different
 // targets for the same source spelling in this scope are installation errors.
+// Long and short spelling forms follow the grammar described by [FlagMeta].
 func FlagAlias(spelling, target string) RoutingRule {
 	record := &routingRuleRecord{
 		kind:       globalFlagAliasRule,
@@ -368,6 +373,7 @@ func FlagAlias(spelling, target string) RoutingRule {
 // available in the complete installation. Scoped mappings take precedence over
 // application-wide mappings with the same source spelling. Identical mappings
 // are accepted; competing targets in the same scope are installation errors.
+// Long and short spelling forms follow the grammar described by [FlagMeta].
 func FlagAliasFor(commandPath, spelling, target string) RoutingRule {
 	record := &routingRuleRecord{
 		kind:       scopedFlagAliasRule,