Consider adding a --help option to 'dotnet complete'

[bergmeister]

dotnet complete returns only a list of suggestions. However, there is no way at getting at the help text programmmatically. IDE's like VSCode or the PowerShell ISE enable showing tooltips from the completion results, which usually include a short help text. I am not sure if a --help switch is the best option but some way of getting at it directly would be great in order to resolve this issue.

Environment data

.NET Command Line Tools (2.0.3)

Product Information:
 Version:            2.0.3
 Commit SHA-1 hash:  12f0c7efcc

Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.16299
 OS Platform: Windows
 RID:         win10-x64
 Base Path:   C:\Program Files\dotnet\sdk\2.0.3\

Microsoft .NET Core Shared Framework Host

  Version  : 2.0.3
  Build    : a9190d4a75f4a982ae4b4fa8d1a24526566c69df

[wli3]

Just giving you more detail -- currently, dotnet complete is aimed for shell tab auto complete. https://github.com/dotnet/cli/blob/master/Documentation/general/tab-completion.md

Tool-tips might be not easily co-exist with shell auto complete. Since the shell are expecting a result as command.

[bergmeister]

@wli3 The point is that if there is an API overload like e.g. a switch, then tool-tip and shell tab complete can co-exist because the shell completion still calls dotnet complete whereas the tooltip additionally calls dotnet complete --returnHelpText' or something like dotnet command --help`. I do not mind if it is a switch on one of the existing commands or a new command.

[vrushalivartak]

I can submit the PR for this. Considering the help text as below. Do share the feedback/inputs if any.

Description:
Show completion options.

Usage:
dotnet complete <COMMAND_STRING> [options]

Arguments:
<COMMAND_STRING> Dotnet command string for which completion options are required.

Options:
--position Position in command string at which completion options are required.
-?, -h, --help Show command line help.

[KalleOlaviNiemitalo]

@vrushalivartak do you intend to define a new directive, make dotnet-complete pass that to the application, and make the System.CommandLine library recognize the directive? If so:

• please document the protocol so it can also be implemented in applications that do not use the library
• how will you handle compatibility with applications using System.CommandLine library versions that do not support the directive?

[KalleOlaviNiemitalo]

Huh I thought this issue was about dotnet-suggest in the https://github.com/dotnet/command-line-api/ repo. dotnet complete does not have the same version-compatibility problem as it's shipped together with the commands that it will be able to complete.

So if I understand correctly, the request is for a feature where dotnet complete can be asked to output not only the possible completions, but also the help text for each completion. The output needs to be in a format that can be parsed by shell functions. JSON may be okay for PowerShell, but I think Bash might prefer something line-based:

completion:--some-option
help:this is the help text for --some-option.
...:It can span multiple lines.  In the line-based format, each continuation line starts with "...:".
completion:--output=
help:another option for demonstration purpose.  This one takes an argument.
syntax_help:--output=file

Same in JSON would be:

[
  {
    "completion": "--some-option",
    "help": "this is the help text for --some-option.\r\nIt can span multiple lines.  In the line-based format, each continuation line starts with \"...:\"."
  },
  {
    "completion": "--output=",
    "help": "another option for demonstration purpose.  This one takes an argument.",
    "syntax_help": "--output=file"
  }
]

Shell completion scripts could then potentially use microsoft/terminal#3121 to display these completions and help texts in Windows Terminal.

[vrushalivartak]

@KalleOlaviNiemitalo Thanks for your inputs. I now understand the ask better.
In my previous comment, I was intending to add a basic --help for dotnet-complete command which is also necessary I believe.

[KalleOlaviNiemitalo]

The dotnet complete subcommand is hidden here to prevent dotnet --help from mentioning it:

sdk/src/Cli/dotnet/commands/dotnet-complete/CompleteCommandParser.cs

Lines 26 to 28 in 67e671f

	CliCommand command = new("complete")
	{
	Hidden = true

I think that makes it less necessary for dotnet complete --help to include (localizable) descriptions for the arguments and options of dotnet complete.

[KalleOlaviNiemitalo]

dotnet complete gets CompletionItem instances from the System.CommandLine library and outputs the value of the CompletionItem.Label property:

sdk/src/Cli/dotnet/commands/dotnet-complete/CompleteCommand.cs

Line 39 in 67e671f

reporter.WriteLine(completion.Label);

I think that is already a bit wrong, and CompletionItem.InsertText should be output instead. CompletionItem.Label should be displayed in a menu, but CompletionItem.InsertText should be inserted to the command line if the user chooses the menu item; those are usually the same, but if they differ and the output format used by dotnet complete supports only one string per completion, then CompletionItem.InsertText is more important.

CompletionItem source code:

https://github.com/dotnet/command-line-api/blob/d12a6ff555b33670defb2243daecdc247caf88e8/src/System.CommandLine/Completions/CompletionItem.cs

CliCommand.AddCompletionsFor creates CompletionItem instances for the non-hidden subcommands, options, and arguments of the command. The description, which also appears in the --help output, goes to CompletionItem.Detail:

https://github.com/dotnet/command-line-api/blob/d12a6ff555b33670defb2243daecdc247caf88e8/src/System.CommandLine/CliCommand.cs#L291

The library doesn't seem to add CliOption.HelpName and CliOption.Arity to the CompletionItem. It could perhaps be changed to format those into CompletionItem.Label but keep CompletionItem.InsertText like it is now. On the other hand, if an application customises the help for an option, it is not obvious to me how the library could copy the customised syntax help into the CompletionItem — would it have to create a HelpContext for that, and would doing so slow down the completions query?

Feature request for CompletionItem.HelpLink: dotnet/command-line-api#1962 — Windows Terminal however doesn't seem to support a help URL per completion item:

https://github.com/microsoft/terminal/blob/145c4d36412ba07bbe1b7d8b49c031c337df28f3/src/cascadia/TerminalSettingsModel/Command.cpp#L667-L668

[jods4]

Nushell could take advantage of this, it supports showing completions with descriptions.

If there was a --description flag for dotnet complete, assuming its output was parseable, then it could show something like this (example git command completion):

Right now integrating dotnet complete looks like this:

[baronfel]

I would love this, we just need to ensure we're backwards-compatible in the implementation of the current complete command. If there were some toggle for complete that opted the command into returning the structured representations of the CompletionItems that System.CommandLine returns, then shells like nushell could have really awesome experiences. Are you interested in contributing this @jods4?

[jods4]

A backward-compatible way could be to create a distinct command?
Keep dotnet complete the same and add similar new command dotnet complete-described.

I would be interested in contributing something like that, but right now I'm knee-deep into adding .net 8 support to Grace... so that wouldn't be before a while.
If anyone else wants to pick it up in the meantime please go ahead.

[baronfel]

We could also add a 'flag' argument to dotnet complete like dotnet complete --full or dotnet complete --detailed that would change the output format, that would work as well.

[jods4]

The issue of dotnet complete is that anything that comes after might be a completion.
If I type dotnet --full and hit <tab> to get completions, then the shell will send the command dotnet complete --full and will not get the format it expects in return.

Granted it's a weird use case, as dotnet --full is not a meaningfull command today.

[baronfel]

Oh jeez, of course you're right. I forgot that complete doesn't take a single string argument, it takes the string[] of individual tokens. Some other shell handlers provide the partial command line as a single string separate from the other options forward to the completion command.

Yes, in that case we would need a parallel function. Good spot!