Completion helper

[ccoVeille]

Following #2220

Right now the format for completion is not obvious. I discovered in ov tool

rootCmd.PersistentFlags().IntP("tab-width", "x", 8, "tab stop width")
_ = rootCmd.RegisterFlagCompletionFunc("tab-width", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
	return []string{"3\ttab width", "2\ttab width", "4\ttab width", "8\ttab width"}, cobra.ShellCompDirectiveNoFileComp
})

https://github.com/noborus/ov/blob/4f4e9e5c266ec4815c5a166718e318992ea47751/main.go#L431-433

By not .obvious, I mean the tab is logic but not something you will think of, when you easily find out in the documentation.

I opened an issue as it requires some design

• Adding a struct, with Text and description

• validation might be needed

• Generic could help, but the Go version 1.15 is go.mod broke my dreams 😅

• a fmt.Stringer art, but it doesn't bring much

I might be overthinking and what is needed is simply about adding documentation about the format in the methods

So, let's talk 😁

[ccoVeille]

Of course, we could start by adding Go Examples to these methods.

Then implements something with an helper

[marckhouzam]

There is a small mention of this in the completions README:

cobra/site/content/completions/_index.md

Line 373 in 6c3c116

Cobra allows you to add descriptions to your own completions. Simply add the description text after each completion, following a `\t` separator. This technique applies to completions returned by `ValidArgs`, `ValidArgsFunction` and `RegisterFlagCompletionFunc()`. For example:

But any improvement to make this more obvious is welcomed

[ccoVeille]

Indeed https://github.com/spf13/cobra/blob/6c3c1163c6df19860515103199e880122ba49e80/site%2Fcontent%2Fcompletions%2F_index.md#descriptions-for-completions