doc: Put description in separate section #2344
Conversation
The `Long` description was prepended to the Synopsis section which it does not belong to - the synopsis should, by convention, only be the syntax of the command and its options. It's now added to a separate Description section.
|
|
|
I can add a test if you agree with the change. |
| } | ||
|
|
||
| if cmd.Runnable() { | ||
| if len(cmd.Long) > 0 { |
There was a problem hiding this comment.
Why would this only be printed if long > 0 now?
There was a problem hiding this comment.
That was already the case. The ### Synopsis section header was previously printed in line 67, which was only printed if len(cmd.Long) > 0.
marckhouzam
left a comment
marckhouzam
left a comment
There was a problem hiding this comment.
Can you provide some kind of reference as to why we should use the new format you suggest? I don’t want someone to come along later with a different opinion to challenge this change.
My reasoning is that the synopsis should only contain the formal description of how to run the command and what command line options it takes (e.g. |
3 participants
The
Longdescription was prepended to the Synopsis section which it does not belong to - the synopsis should, by convention, only be the syntax of the command and its options.It's now added to a separate Description section.