Command Explanation

[niezbop]

Description

Add an extra section to the command help but not to the program help, by adding an attribute :explanation to the Commander::Command class.

Motivation

Working with Commander on a project, we have a command that can be difficult to understand in some aspect and we wanted a way to go in depth in the help of said command. The issue we faced was that putting too much text into the Command.description was cluttering the program help menu. We could have used the Command.examples section; but this feels more like a workaround than an actual solution. This is why we suggest to add an extra attribute to the command so that it is possible to be as lengthy as desired and keep a clean program help!

I've added some examples to the spec even though the feature is really simple!

In any case, thanks to anyone working on maintaining and improving this fantastic gem 😃

[lacostej]

@niezbop feel free to rebase your PR on master once #55 is merged to show that this PR passes as well.

[lacostej]

@ggilder if I recall, the description is used both in the command help and in the global help

We want an "explanation" (feel free to propose a better word) to contain more information. Adding more to the description would make the global help too large.

There are implementation alternatives like cutting the description to the first sentence. But that could break backwards compatibility. Any idea?

[ggilder]

I think (but please confirm) that if you provide summary for a command, that is used instead of description in the global help. Can you test that approach and see if it solves the problem?

[lacostej]

@ggilder I double checked and indeed it works. Not sure how we missed that. Sending PR #56 to improve the doc

[ggilder]

Great! Thanks for updating the docs, I agree it's not super clear.