Documentation for back-quoted flag usage

[calebstewart]

This may be better suited in the spf13/pflag project, but my expectation is that more people use Cobra than pflag directly. I was recently using Cobra to parse a custom repeated argument in the form --option KEY=VALUE . When using .StringArray(), the usage looks like this by default:

Flags:
  --option stringArray     My usage information

This isn't terrible, but "stringArray" is not helpful in this context. I went digging in the documentation and code and ended up finding the UnquoteUsage function. It seems that providing a usage like:

cmd.Flags().StringArray("option", nil, "Extra `KEY=VALUE` options")

Will result in the following usage:

Flags:
  --option KEY=VALUE    Extra KEY=VALUE options

This is exactly what I wanted, however there's no documentation anywhere that I could find.

If this is better opened over in pflag, let me know, and I can reopen over there. If I've missed where this functionality is documented, then no worries. I just wanted to surface it to help someone else in the future. :)

[marckhouzam]

Believe it or not I also actually found out about this a few weeks ago! So I agree that it would be nice to document in cobra. Also, shell completion which automatically provides descriptions of flags does not respect this format.

@calebstewart I encourage you to submit a PR for the documentation. And if you want, a PR for shell completion would also be appreciated

[cubxxw]

Come on!

[nirs]

I learned about this today reviewing #2105 :-)

Shouldn't this be documented in the pflags package?

[calebstewart]

I apologize for losing track of this issue. It seems from the discussion, and after reading back over everything that it makes the most sense to add this documentation to spf13/pflag and spf13/cobra.dev (to get it to the website docs). That is what I did above. I'm open to any tweaks to that documentation, but I at least took a stab at it.