[console] Use the description when no help is available #15601
Conversation
| Q | A |
|---|---|
| Bug fix? | no |
| New feature? | yes |
| BC breaks? | no |
| Deprecations? | no |
| Tests pass? | yes |
| Fixed tickets | #15498 |
| License | MIT |
| Doc PR |
0fc7268 to
641f859
Compare
|
👍 |
641f859 to
34144f9
Compare
|
👍 Status: reviewed |
|
👎 Help and description are not the same. If help is empty for some command, they should be added instead. |
|
They may not be the same but in fact the help is often the description rephrased and with two example to illustrate the usage of one or two options. And people could prefer to not duplicate the information and save time for the translators. It can be done manually for each command or automatically with a fallback. Personally I truly believe it should be done automatically (especially because we don't want to display the description when there is an help block). Have a look to |
| @@ -131,6 +131,8 @@ public function testGetSetHelp() | |||
| $ret = $command->setHelp('help1'); | |||
| $this->assertEquals($command, $ret, '->setHelp() implements a fluent interface'); | |||
| $this->assertEquals('help1', $command->getHelp(), '->setHelp() sets the help'); | |||
| $command->setHelp(null); | |||
There was a problem hiding this comment.
setHelp and getHelp both except/return a string. So setting null is not allowed. Btw, the properties in the command should be initialized as empty string. otherwise the phpdoc is also wrong before calling the setters.
There was a problem hiding this comment.
you are right, it is initialized to an empty string. Fixed
34144f9 to
e5d3f25
Compare
|
@fabpot help is the extended version of description. While description only describes what a command does, help also describes how to use the command. If there is no docs on how to use something, it's still usefull to know what it does. Currently, |
|
Thank you @Nicofuma. |
…icofuma) This PR was merged into the 2.3 branch. Discussion ---------- [console] Use the description when no help is available | Q | A | ------------- | --- | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #15498 | License | MIT | Doc PR | Commits ------- e5d3f25 [console] Use the description when no help is available
This PR was merged into the 2.3 branch. Discussion ---------- [Console] do not make the getHelp() method smart | Q | A | ------------- | --- | Bug fix? | kind of | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | In my opinion, the way to always display a help message to the user was implemented in #15601 is not good enough. The getter method for the help should only return the actual value. Otherwise, user's would not have a way to check if a command really has a help message (for example, when building their own CLI applications or whatever). Instead, we should only return the description as a fallback of the help message when it is processed to present it to the user. Commits ------- cdf1f00 [Console] do not make the getHelp() method smart