Unable to differentiate command summary from detailed command description. #230
Description
If I define a public method in a command class that I have registered explicitly with Add<T>(), then I can, per the docs, add doc comments to that public method, and its <summary> contents will be injected as the command description when running -h/--help from the root command.
using ConsoleAppFramework;
var app = ConsoleApp.Create();
app.Add<Commands>();
app.Run(args);
public class Commands
{
/// <summary>
/// Display Hello.
/// </summary>
/// <param name="message">-m, Message to show.</param>
public void Greet(string message) => Console.Write($"Hello, {message}");
}
Usage: [options...] [-h|--help] [--version]
Commands:
greet Display Hello.
However, if I want to provide a more detailed explanation of the command's features and behavior for when someone runs myapp greet -h, then I have no way of differentiating the output. If I try to add multiple lines of description in the <summary> element, then it just ends up displaying ALL of this information beside the command name in the root program's help text as well, which ruins the user experience. And for that matter, attempting to put a detailed description in proper XML doc comments (with uses of <list>, <item>, <c>, <code>, <para>, and/or <see> just results in it all being displayed raw rather than fully interpreted and adapted to the extent it can be. I'll raise a separate issue for that though).
I would recommend that the project be updated to defer to <remarks> instead of <summary> when displaying help text for a specific command, if that section is present in the XML doc comments. If it is not present, then perhaps only grab the first line of the doc comment's <summary> tag when constructing the command summary for the parent command's nested command list.