mainargs icon indicating copy to clipboard operation
mainargs copied to clipboard

Add new documentation annotation for program level help text

Open jk-1 opened this issue 2 years ago • 1 comments

Please add new documentation annotation for program level help text. Place for this text could be before "Available subcommands:" so at the very top or at the bottom or both depending on the size of the program. If just one place accepted then I prefer to place it at the bottom.

Annotations could be e.g. @begindoc, @enddoc

Program level help text should be visible when user runs program --help -command.

Reason: Many larger programs contain multiple subcommands and are part of a longer task process. A subcommand help contains instructions how to run that subcommand but program level documentation can help the user to understand the longer process: What subcommands are run in what order, describle one or more simple workflows how to use subcommands to manage the whole task process from begin to end.

Program level help text can also be used for any other information common to all / multiple subcommands, where to find more information, author of the program, copyright etc.

jk-1 avatar Jun 02 '22 10:06 jk-1