Enum values listed in option docs are poorly formatted

[muzimuzhi]

CLI Feedback

For example,

On https://cli.github.com/manual/gh_run_list

-s, --status <string>
Filter runs by status: {queued|completed|in_progress|requested|waiting|action_required|cancelled|failure|neutral|skipped|stale|startup_failure|success|timed_out}

On https://cli.github.com/manual/gh_cache_list

-S, --sort <string>
Sort fetched caches: {created_at|last_accessed_at|size_in_bytes}

The current plain format reduces readability.

What have you loved?

A prettier format, perhaps with some rewording.

-S, --sort <string>
Sort fetched caches: one of "created_at", "last_accessed_at", "size_in_bytes"

Anything else?

The format seems controlled by

cli/pkg/cmdutil/flags.go

Lines 27 to 46 in a74a71e

	// StringEnumFlag defines a new string flag that only allows values listed in options.
	func StringEnumFlag(cmd *cobra.Command, p *string, name, shorthand, defaultValue string, options []string, usage string) *pflag.Flag {
	*p = defaultValue
	val := &enumValue{string: p, options: options}
	f := cmd.Flags().VarPF(val, name, shorthand, fmt.Sprintf("%s: %s", usage, formatValuesForUsageDocs(options)))
	_ = cmd.RegisterFlagCompletionFunc(name, func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
	return options, cobra.ShellCompDirectiveNoFileComp
	})
	return f
	}
	func StringSliceEnumFlag(cmd *cobra.Command, p *[]string, name, shorthand string, defaultValues, options []string, usage string) *pflag.Flag {
	*p = defaultValues
	val := &enumMultiValue{value: p, options: options}
	f := cmd.Flags().VarPF(val, name, shorthand, fmt.Sprintf("%s: %s", usage, formatValuesForUsageDocs(options)))
	_ = cmd.RegisterFlagCompletionFunc(name, func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
	return options, cobra.ShellCompDirectiveNoFileComp
	})
	return f
	}

cli/pkg/cmdutil/flags.go

Lines 68 to 70 in a74a71e

	func formatValuesForUsageDocs(values []string) string {
	return fmt.Sprintf("{%s}", strings.Join(values, "|"))
	}

Loosely related to #8348

[andyfeller]

@muzimuzhi : thank you for opening this issue! 🙇

Appreciate you also looking at the code path involved! Will need to look at GitHub Docs for other examples, but I agree having some spacing would make it a little easier to read. Given this is used for the actual terminal usage and the CLI manual pages, I'm hoping the format can be the same but let's see.

[muzimuzhi]

I failed in finding a similar use example in GitHub Docs, but found one (and only one) in Git Docs,

--diff-algorithm={patience|minimal|histogram|myers}
Choose a diff algorithm. The variants are as follows:

• webpage https://git-scm.com/docs/git-diff#Documentation/git-diff.txt---diff-algorithmpatienceminimalhistogrammyers
• source https://github.com/git/git/blob/master/Documentation/diff-options.txt

[andyfeller]

You're right 🤔 The only place I might have expected something would be https://docs.github.com/en/enterprise-server@3.11/admin/administering-your-instance/administering-your-instance-from-the-command-line/command-line-utilities but nothing usage related. That makes sense as it'd be difficult keeping docs.github.com perfectly up to date.

All of that said, open to ideas and mock ups on what this would look like 👍