Remove Command.usage in favor of Command.signature

[sgtlaggy]

trafficstars

Summary

The original implementation of Command.usage felt a bit rushed and seemed to often cause confusion. Setting signature itself directly makes more sense and should lead to less confusion.

The behavior remains the same, usage is essentially renamed/merged into signature.

Checklist

• [x] If code changes were made then they have been tested.
  • [x] I have updated the documentation to reflect the changes.
• [ ] This PR fixes an issue.
• [ ] This PR adds something new (e.g. new method or parameters).
• [x] This PR is a breaking change (e.g. methods or parameters removed/renamed)
• [ ] This PR is not a code change (e.g. documentation, README, ...)

[rtk-rnjn]

I believe Command.usage is still "fine" :thinking:

[Rapptz]

I get the intent behind this one but I think doing cmd.signature = None followed by cmd.signature and it giving you something else is more confusing than the previous set up.

[sgtlaggy]

Maybe that could be documented as restoring the original POSIX-like signature? I added the setter in case it was ever used after defining the command, as rarely as that may be done. signature is still documented as just str, so maybe it should only accept str instead of Optional[str].

If we stick with usage, changing the description to something like "An override for the default signature." and adding a note in the signature description similar to short_doc may be better, though not sure how I'd word that.

[mikeshardmind]

Maybe that could be documented as restoring the original POSIX-like signature? I added the setter in case it was ever used after defining the command, as rarely as that may be done. signature is still documented as just str, so maybe it should only accept str instead of Optional[str].

If we stick with usage, changing the description to something like "An override for the default signature." and adding a note in the signature description similar to short_doc may be better, though not sure how I'd word that.

This could be made to accept a str instead of Optional[str], and you could add a property deleter as well that is documented as resetting it.

[Rapptz]

I've decided not to pursue this breaking change.