ConsoleAppFramework icon indicating copy to clipboard operation
ConsoleAppFramework copied to clipboard

XML tags interpreted literally when translating doc comments to help text descriptions.

Open willnationsdev opened this issue 3 weeks ago • 2 comments

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:

Image

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:

Image

Greet command help text:

Image

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 Usage section for subcommands' help text, so that's why myapp is not present in the Usage portion 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]

willnationsdev avatar Dec 11 '25 23:12 willnationsdev

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.

neuecc avatar Dec 12 '25 03:12 neuecc

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.

willnationsdev avatar Dec 12 '25 16:12 willnationsdev