Automatically document available options for enums.

[willnationsdev]

If I declare an enum and use it in a command's arguments or options, then the help text details the type of the value; however, there is nothing in the help text that actual communicates to me which strings can be typed to provide a valid <Target> value.

using ConsoleAppFramework;

var app = ConsoleApp.Create();

app.Add("write", (Target target) => { });

app.Run(args);

public enum Target
{
    File,
    Network
}

Options:
  --target <Target>

I obviously also don't want to hard-code the available values inside an XML doc comment because then I'd have to refactor those comments everywhere that enum is used in a command's parameters whenever I happen to change the possible values of the enum.

Some possible options for how it could be done (maybe it shifts based on how many options there are / whether they will fit in the available character range?). These could be prompted via an attribute of some sort, perhaps:

1. Inline

Options:
  --target=<file|network>

2. Description Segment

Options:
  --target        The target (whatever description, if present) [values: file, network]

3. Manual

   Some people probably want to keep the existing behavior so that they can use an independent, procedurally-generated documentation explicitly for the enum type (if its prevalent enough, I suppose), like a man page. I would assume we'd want this to remain as the default behavior, for compatibility.

If we went the extra mile (maybe deserving of its own issue), we could also make it so that XML comments on each individual value would result in a dedicated line with the value, a colon, and then the transplanted summary inside that part of the option/argument description (maybe?). And if the enum shows up more than once as a type for an argument or option in the same command, then you could just create a generated section explaining the enum in the description of the command itself.

[neuecc]

There was a recent time when I worked on the error message for Enum, and listing them in the help was also considered. #220 For example, the dotnet command hardcodes the Enum notation exactly in the description. (for example -verbosity) I would also probably hide them by default. Adding it as an option to ConsoleAppFrameworkGeneratorOptions is not out of the question.