search

Azure / azure-dev

A developer CLI that reduces the time it takes for you to get started on Azure. The Azure Developer CLI (azd) provides a set of developer-friendly commands that map to key stages in your workflow - code, build, deploy, monitor, repeat.
https://aka.ms/azd
MIT License
408 stars 196 forks source link

fix inconsistent help text for commands #4480

Open weikanglim opened 4 days ago

weikanglim commented 4 days ago

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:

Image

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"

Image

This makes it hard for users to differentiate the important command-specific help from the less import global help flags.

As reported by @SophCarp

weikanglim commented 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:

  1. 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
  1. If we are creating additional properties that "build up to" a help text, they should be prefixed with 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.