Provide guidance to language and extension authors

[eamodio]

• VSCode Version: Version 1.5.0-insider (1.5.0-insider) 538cd9d
• OS Version: OS X El Capitan Version 10.11.6 (15G31)

Given the power of the abstractions that vscode provides for symbols, definitions, references, etc, I think it would be great if there was some guidance (best practices) documentation on how a language should provide the information. For example, when implementing a DocumentSymbolProvider what should the range be of the symbol? TypeScript/JavaScript/JSON seem to include the body of a symbol (that has one), where as C# (Omnisharp) only provides a range covering just the keyword alone. Which one is right or more accurately which one is provides more to build upon and should be considered the better practice.

Also along the same lines -- there is a LOT of power in the vscode.executeDocumentSymbolProvider, vscode.executeReferenceProvider, and others, but from the documentation I don't think it is really clear. For example, utilizing both vscode.executeDocumentSymbolProvider and vscode.executeReferenceProvider together, once should be able to create a single extension to provide usage CodeLens support for any language that supports those providers -- without the need of every language adding that type of support.

Thoughts?

[eamodio]

Related to this I think it would be great if a symbol had 2 ranges:

1. for the symbol itself (i.e. the keyword)
2. for the "bounding" range -- the line or set of lines that cover the "contents" of the symbol

I think this would go a long way to help with confusion and differences in what the different language servers provide.

For example, an extension wishing to add a decoration to the symbol keyword would want the a range for the symbol itself, while an extension like GitLens wants the bounding range, so that it can provide rollup information about the symbol contents.

[rcjsuen]

Also see Microsoft/language-server-protocol#132 which also asks for clarity about a symbol's range. I quite like your idea of having two separate ranges to handle this case, @eamodio.

[kieferrm]

Would it help if we beef up https://code.visualstudio.com/docs/extensionAPI/language-support ?

[rcjsuen]

That would only help if the protocol was also updated and documented such that both VS Code's expectations and the protocol's expectations match. If VS Code is explicit about what it wants but the protocol doesn't then it puts language server authors in a tough spot because they need to consider the behaviour of language clients that aren't VS Code. That to me would kind of defeat the purpose of a language server if I need to worry about the clients that's calling the API.

[KamasamaK]

Separating the ranges is a good idea. Another issue when using the entire range of the construct in the SymbolInformation.location is that the "Peek Definition" functionality will highlight the entire block harming readability in my experience since it overwhelms the syntax highlighting (at least with the default theme).