Usage format suggests incorrect usage of custom command.

[trockefeller-pathway]

I noticed when using custom commands, the Usage: description doesn't seem to be accurate for what is described. I wrote a sample application to show the problem on dotnetfiddle.net here https://dotnetfiddle.net/Ttxv7J

What I'm seeing is that for the example program the usage of the foo command is described like this

Foo
  Executes the foo command.

Usage:
  applicationName [options] Foo <bar>

Arguments:
  <bar>  The bar argument

Options:
  --gar <gar>     The gar option [default: default gar]
  -?, -h, --help  Show help and usage information

which would suggest a usage like applicationName.exe --gar "gar option" Foo "bar argument", but this results in an "Unrecognized command or argument '--gar'"

The actual usage is more like applicationName.exe Foo "bar argument" --gar "gar option" which I would think would be described as applicationName Foo <bar> [options]

Am I using custom commands incorrectly? Is [options] referring to global options, and not command specific options? Is there a way to show command specific options in the usage syntax?

here is a copy of the code for reference

using System;
using System.CommandLine;
using System.CommandLine.Invocation;

public class Program
{
	public static void Main(string[] args)
	{
		//as far as I know, we can't pass in args in .NET fiddle
		//usage will say that to use the Foo Command, it will look like applicationName [options] Foo <bar>
		//but if I put the Foo options before the Foo command you get an "unrecognized command or argument '--gar'
		args = new string[]{"--gar", "hello gar", "Foo", "hello bar"};
		//if you put the Foo options after the <bar> argument, then things work
		args = new string[]{"Foo", "hello bar", "--gar", "hello gar"};
		var rootCommand = new RootCommand
		{
			new FooCommand()
		};
		
		rootCommand.Description = "I am root.";
		
		rootCommand.Invoke(args);		
	}

	private class FooCommand : Command
	{
		public FooCommand(): base("Foo", "Executes the foo command.")
		{
			Handler = CommandHandler.Create<string, string>((bar, gar) => doFoo(bar, gar));
			var barArgument = new Argument<string>("bar", "The bar argument");
			var garOption = new Option<string>("--gar", () => "default gar", "The gar option");
			AddArgument(barArgument);
			AddOption(garOption);
		}
													
		private void doFoo(string bar, string gar)
		{
			Console.WriteLine($"bar: {bar}    gar: {gar}");
		}
    }
}

[elgonzo]

Yup. It's an already known and confirmed bug (see here: #1334)