Please document CompletionItem.Kind more

[KalleOlaviNiemitalo]

I was implementing a CompletionDelegate in my command-line application. That returns IEnumerable<CompletionItem> so my completion method needs to call the CompletionItem constructor. This constructor takes a string kind = "Value" parameter but it is not clear how to decide whether the default value "Value" is correct or the caller should pass in something else. The documentation of this parameter is just "The kind of completion item." and the documentation of the CompletionItem.Kind property is the same.

From the source code, I found the internal class CompletionItemKind, which defines "Keyword" and "Value". However, that does not document their meanings either and instead references https://microsoft.github.io/language-server-protocol/specifications/specification-3-17/#textDocument_completion, and that page no longer exists.

Please expand the documentation of the parameter and the property to list the completion item kinds that have been defined, or to point to other documentation that provides this information.

[KalleOlaviNiemitalo]

Blaming microsoft/language-server-protocol@ed80401 for the broken link. I suppose https://github.com/microsoft/language-server-protocol/blob/da484ec54f069a192814a4425b6f430ff1097d24/_specifications/lsp/3.17/language/completion.md would be a stable URL for the list of completion token kinds, but it still doesn't really say what they mean.

[baronfel]

From an LSP perspective, that field is used to sort/classify completions to implicitly filter them based on the context that the user requested completions in. For example take this F# for loops - for x of y|, where | is the completion trigger point. A LSP server may know that the completion position is in an 'identifier' space, and so keyword completions should be filtered out.

The thought here was that similar logic might be useful, but it's not currently being used. This was a bit of a forward-thinking API.

[KalleOlaviNiemitalo]

Would be useful in #1220, I suppose. But this would need a new directive, as SuggestDirectiveResult only outputs CompletionItem.Label (not even CompletionItem.InsertText). So a completion delegate that enumerates CompletionItem instances has currently no advantages over one that enumerates plain strings.

command-line-api/src/System.CommandLine/Invocation/SuggestDirectiveResult.cs

Lines 25 to 30 in 209b724

	var completions = completionParseResult.GetCompletions(_position);
	context.Console.Out.WriteLine(
	string.Join(
	Environment.NewLine,
	completions));

command-line-api/src/System.CommandLine/Completions/CompletionItem.cs

Line 64 in 209b724

public override string ToString() => Label;

[baronfel]

You're exactly correct - the existing suggest needs to be updated to use the new API shapes more effectively. That's something we want to do, it just hasn't come to fruition yet!