[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]

Mayuri Diwan (@mayurid) this is the case for 95%+ of the commands. The short description is only set by the help files (Burt Bielicki (@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]

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

[tjprescott]

Mayuri Diwan (@mayurid) Jason R. Shaver (@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]

Yugang Wang (@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]

Travis Prescott (@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]

Burt Bielicki (@BurtBiel) Travis Prescott (@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]

Yugang Wang (@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.