Open weikanglim opened 4 days ago
Based on a quick look on the existing code, I do feel that the source of these inconsistencies is due to the extra indirection we've added to "ActionDescriptor" which then translates these into unknown quantities in cobra.Command
.
My strong inclination here is to fix the issue at the root: let's try to find ways to avoid the indirection. If we do need the extra indirection, let's make sure the new properties we're adding is honoring the invariants already set by cobra.Command
.
Here's an example of what we could do:
cobra.Command
has a Short
and a Long
property, with well-documented usage of the end-to-end experience:// Short is the short description shown in the 'help' output.
Short string
// Long is the long message shown in the 'help <this-command>' output.
Long string
// Example is examples of how to use the command.
Example string
Short<xx>
to indicate how it would be translated to cobra command help text, which affects the overall end-to-end experience.Otherwise, as we do today, we risk introducing "new help properties" that map incorrectly to places of unintended usage and the help text shows up weirdly for our users. Let's really think about the end-to-end user experience here.
EDIT: I was able to figure out that HelpOptions
just configures Help
and nothing else. We just duplicate the text between Short
and Help
to format it differently. I'm still wondering if there are better ways to do this. For example, we could set a HelpFunc
that gives us the customization we want and have default functions that apply the right set of templating based on existing command metadata.
There are a few inconsistencies in our help text:
Issue 1: Inconsistent use of
Short
.Example: in our help text for
azd template source add
, we have a multi-line Short description:This also affects our
docgen
process as reported by @alexwolfmsft.Issue 2: Flags listed as global flags.
In our help text for all commands, we have
--docs
and--help
listed as "Flags" and not "Global Flags"This makes it hard for users to differentiate the important command-specific help from the less import global help flags.
As reported by @SophCarp