Skip to content

Provide better guidance on the use of CompletionItem.detail and CompletionItem.documentation #1115

Open
@DanTup

Description

@DanTup

There are two fields on CompletionItem for type/docs:

	/**
	 * A human-readable string with additional information
	 * about this item, like type or symbol information.
	 */
	detail?: string;

	/**
	 * A human-readable string that represents a doc-comment.
	 */
	documentation?: string | MarkupContent;

These comments make it seem like detail is a good place to put function signatures, but this seems to not be the case because they appear quite poorly in VS Code (no highlighting - see microsoft/vscode#106862) and the recommendation is to use documentation and leave detail blank.

It's important for servers and clients to all be on the same page to ensure things are rendered well across clients, so I think the LSP spec should have clearer guidance here. For example, if a server puts signature information in detail for VS Code it's important it is not also at the top of documentation. I know LSP doesn't want to get into UI, but if it's just silent on this, clients will behave differently and then servers are stuck picking between "some information not being visible in some editors" and "some information being duplicated in some editors".

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions