XML tags interpreted literally when translating doc comments to help text descriptions.
If I have the given Program.cs:
using ConsoleAppFramework;
var app = ConsoleApp.Create();
app.Add<BasicCommands>();
app.Run(args);
public class BasicCommands
{
/// <summary>
/// <para>Displays a hello message.</para>
/// <para>Example:</para>
/// <para>
/// <code>
/// myapp greet -m "Daniel"
/// </code>
/// </para>
/// <para>Output:</para>
/// <para>
/// <code>
/// Hello, Daniel
/// </code>
/// </para>
/// </summary>
/// <param name="message">-m, Message to show.</param>
public void Greet(string message) => Console.Write($"Hello, {message}");
}
This creates the kind of XML doc comment that looks very good in Visual Studio's hover UI:
However, the output observed in the help pages display this information literally, damaging the user experience considerably (forgive the additional silent/verbose global options, which are irrelevant and come from my own code outside the example).
Root command help text:
Greet command help text:
What I would expect to see, especially coupled with #230 would be something like this:
On a separate note, I'm unsure from the README how to get the application name into the
Usagesection for subcommands' help text, so that's whymyappis not present in theUsageportion of my samples.
Root Command help text:
Usage: [options...] [-h|--help] [--version]
Commands:
greet Displays a hello message.
Greet command help text:
Usage: greet [options...] [-h|--help] [--version]
Displays a hello message.
Example:
myapp greet -m "Daniel"
Output:
Hello, Daniel
Options:
-m, --message Message to show. [Required]
The Visual Studio hover is just a byproduct, and commands are never called directly from code, so I don't think there's value in strictly applying this. But well, I'll think about it.
Hmm. That is fair. While it functionally works now (since you're right, those methods are never explicitly called and thus don't technically need to be documented in the same manner), it just feels awkward to use XML doc comments in purposefully incorrect ways, syntax-wise. And I still often use them - even with private methods - so that I can document behavior and usage examples of code for the sake of other team members with whom I share a codebase.