Feature: allow --help for individual options

Sometimes an option is more complex than the command itself. What if a command has a lot of (complex) options, how do you cover it all in the usage/help section for the command? What if you have only one command, but lots of options, wouldn’t you want to provide users the same help facility with options that is currently only possible with commands?

It might be useful to be able to provide help for individual options, so where the following triggers regular usage display:

command --help [--option 1 2 3]

The following might display the usage for a specific option:

command --option --help, or
command --option--help

The alternative is a 20 page usage display for that single command.

Thoughts?

[remkop]

If --option--help or --option:help is acceptable, you can already accomplish this to some extend. First for each complex option (example: -xxx), define a companion help option (example: -xxx:help):

@Option(names = "--xxx:help", help = true)
boolean showHelpForXxx;

@Option(names = "--xxx")
String xxx;

Then, in the application, check if help for this option is requested and print its specialized help:

if (showHelpForXxx) {
  showUsageForOptionXxx(); 
  return;
}

The help = true attribute is like usageHelp = true in that it prevents a MissingParameterException being thrown for missing required options/positional parameters. It differs from usageHelp in that it won’t automatically print help for the command.

[bbottema]

It’s still a kind of hack having a shadow - - option–help for each - -option, but it works. I’d rather see it as 1st class API, but I don’t think this is in scope for picocli. Closing issue…