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:
- Inline
Options:
--target=<file|network>
- Description Segment
Options:
--target The target (whatever description, if present) [values: file, network]
-
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.
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.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:
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.