Skip to content

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

@willnationsdev

Description

@willnationsdev

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]

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions