[Help] Description text missing for commands

[mayurid]

Here is what we see:-
az role -h

Group
az role

Subgroups:
assignment

Commands:
create : Create a custom role.
delete
list
update

We should have some description text for delete, list and update or simply remove the create text
Similar issues are seen in az vm -h as well.

[tjprescott]

@mayurid this is the case for 95%+ of the commands. The short description is only set by the help files (@BurtBiel correct me if I'm wrong), the majority of which don't yet exist. We will probably need some script to take a "snapshot" of the help that is currently patched together like some Frankenstein monster to use as a starting point for those help files.

[mayurid]

@JasonRShaver : Something for you to look at in the next couple of sprints. This is important F&F item.

[tjprescott]

@mayurid @JasonRShaver resolving issue #365 should greatly alleviate this problem.

[yugangw-msft]

FYI, i will move the description of Create a custom role. to "long-summary", so it won't show up on az role -h. The command name is pretty self-descriptive, so we don't need it everywhere.

[tjprescott]

@yugangw-msft if the help text is obvious, I would argue that is shouldn't be in long summary either and should be removed altogether.

Also, if the plan is to only provide help when the command's function is not obvious, we should revert PR #365 because otherwise 80%+ of our commands will have short and long help text.

[BurtBiel]

@tjprescott I think there is value in surfacing the SDK comments. Depending on the usefulness of the commands, we could selectively clear out help. My biggest concern is that I haven't seen any another command line tools with partial help files--the simple fields still have text.

from man --help:

  -?, --help                 give this help list
      --usage                give a short usage message
  -V, --version              print program version

We should discuss further with the whole team before making any sweeping changes.

[yugangw-msft]

@BurtBiel @tjprescott , I am fine that each custom command should have short description. It is not that much of maintenance burden. Once agreed, I will add short summary to all role definition commands and other command groups moving forward.
At the same time, want to confirm, for auto-command, we do have a straightforward way to override the descriptions from SDK, right? Travis just now let me try out network nic, almost all description are not accurate, or just wrong. Same with network vnet. To me, integrating doc-strings from SDK is harder to maintain as the authors of rest specs don't pay attention to those and hence every SDK integrations might break some helps

Pasting nic command help for reference:

Group
    az network nic

Commands:
    create   : Create or update a virtual machine.
    delete   : The delete netwokInterface operation deletes the specified netwokInterface.
    list
    show     : The Get ntework interface operation retreives information about the specified network
               interface.
    update

[tjprescott]

@yugangw-msft the priority for help currently is:

1. help file
2. parameter aliases
3. docstring (SDK or custom command)

We can override the docstring for short/long summary through the help files.

[yugangw-msft]

thanks, I will try out the help file first.

[mayurid]

Making this sprint 3 to see what all we address in the first phase that @JasonRShaver is working on

[tjprescott]

@yugangw-msft @JasonRShaver I noticed that appservice web and it's subcommand groups are generally missing a lot of help short summaries.

[yugangw-msft]

Correct, we are still missing summaries on the web.
As you can tell, with each PR like the plan one, I am filling up the summaries, and I will keep on doing that

[mayurid]

@yugangw-msft and @tjprescott : Shall we open a separate issue to track this? This should be closed IMO as we have the first phase of help text in. We can now track help issues per group (like appservice, vm). Thoughts?

[tjprescott]

@mayurid a separate issue works fine

[yugangw-msft]

Open #1019 for 'appservice'