Provide metadata about symbols with DefinitionLink #415

rcjsuen · 2018-09-12T23:05:32Z

I've updated textDocument/definition, textDocument/implementation, and textDocument/typeDefinition, to potentially return a DefinitionLink. This new interface includes metadata about the ranges of both the originating source symbol and the target symbol. This will help provide more context to the user while navigating between different symbols in an editor.

For example, instead of simply highlighting a word, the editor can now understand that the source symbol's range extends beyond standard word boundaries. This will allow it to highlight/underline stuff like an entire java.util.List in a Java import statement.

This implements microsoft/language-server-protocol#524.

Enhanced textDocument/definition, textDocument/implementation, and textDocument/typeDefinition to potentially return a DefinitionLink. This new interface includes metadata about the ranges of both the originating source symbol and the target symbol. This will help provide more context to the user while navigating between different symbols in an editor. Signed-off-by: Remy Suen <remy.suen@gmail.com>

dbaeumer · 2018-09-13T08:08:05Z

types/src/main.ts

@@ -1656,7 +1696,7 @@ export interface SignatureHelp {
 * For most programming languages there is only one location at which a symbol is
 * defined. If no definition can be found `null` is returned.
 */
-export type Definition = Location | Location[] | null;
+export type Definition = Location | Location[] | DefinitionLink | DefinitionLink[] | null;


The deeper question that we need to decide is whether we want to deprecate Location for definitions and ask for providing a DefinitionLink instead. If so we shouldn't or them into the Defintion, but rather list them in the results.

Location is semantically equal to DefinitionLink if originSelectionRange and targetSelectionRange are not provided.

What is your opinion?

@dbaeumer Your suggestion seems reasonable to me. We can add a deprecation notice to Definition then to try to help discourage people from using it.

It is too bad that we cannot simply extend DefinitionLink from Location as the attribute names don't match (and range in Location as-is is a little ambiguous compared to the more specific names in DefinitionLink).

It's not clear why, but in the VS Code API, @jrieken thought it would not be a good idea to "mix DefinitionLink into Definition" as is being done here. See microsoft/vscode#54424

@rcjsuen then lets keep them different. I talked to @jrieken about why he kept them different but there was no deeper semantic meaning behind it.

dbaeumer · 2018-09-13T08:10:41Z

Other than the above comment as always a good PR.

rcjsuen · 2018-09-13T10:27:17Z

@dbaeumer I just noticed textDocument/references while going over the specification.

Should I update that one too to return Location[] | DefinitionLink[] | null?

dbaeumer · 2018-09-14T06:10:51Z

@rcjsuen let me think about the references request. Spontaneously I would say yes. But we would need a different name then since a references request returning DefinitionLink might be confusing.

dbaeumer · 2018-09-24T12:16:21Z

@rcjsuen haven't forgotten you. Was busy doing other thing. Will look into this this week.

rcjsuen · 2018-09-24T12:31:52Z

@dbaeumer No rush. We all have our own obligations and timelines. microsoft/language-server-protocol#524 has also been quiet, so... shrugs

This might get delayed either way as I'll be on/off during the first half of October.

dbaeumer · 2018-09-28T08:48:48Z

@rcjsuen we should return DefinitionLink from a references result as well. I checked with @mjbvz and @jrieken and they agree that this would even make sense in the vscode API.

However I dislike the name DefinitionLink if we return it from references results as well. Ideas are: LocationLink, SymbolLocation Has anyone else an idea?

rcjsuen · 2018-09-28T12:49:25Z

@dbaeumer I would say SymbolLink or LocationLink. I don't like SymbolLocation because there's an "origin" and a "target". The word "link" makes more sense for this relationship in my opinion.

dbaeumer · 2018-10-02T08:09:01Z

@rcjsuen almost all LSP data types do have an URI and non are called links except DocumentLink which is in most cases used to represent links. For me the DefinitionLink as definied in the API does the following:

originSelectionRange: this expands the position passsed into the request into a range in case the editor wants to give visual feedback which might be a link / underline or soemthing else
targetUri: the target URI which is the same then Location#uri
targetSelectionRange: the target range that should be selected (same as Location#range)
targetRange: the whole range of the symbol. Did not exist on Location.

Now thinking about it again this doesn't make sense for reference results since there is no origin and no target. There might be two ranges if we want to support this (match range indicating what should be selected and a reveal range).

So may be we stick with DefinitionLink. However I am not sure which of these properties should be optional.

rcjsuen · 2018-10-04T09:59:34Z

@dbaeumer Wouldn't the origin of a textDocument/references request be the position of where the cursor is when the user invoked the request? The user is interested in what other places in the opened workspace is the symbol at the current location used, no? It seems to me that the origin is the symbol at the current cursor position and the target(s) would be the "other locations".

dbaeumer · 2018-11-20T09:57:55Z

@rcjsuen sorry for the long silence. I had a discussion with @jrieken about this lately and we decided to name this LocationLink for now. We also introduced a DeclarationProvider. This and the DefinitionProvider now return LocationLink

Regarding your comment: I am not sure I understand this. Isn't this the whole purpose of the reference result to list all locations where a symbol is referenced. And the position where the cursor is is the input param to the request. If we want to expand this to a valid range then I think this need to go onto the reference result which then might look like this

interface ReferenceResult  {
   range: Range;
   locations: Location[];
}

Does that make sense ?

rcjsuen · 2018-11-20T11:52:50Z

Hi, @dbaeumer. I presume DeclarationProvider was introduced to add support for microsoft/language-server-protocol#605?

What you suggested with ReferenceResult makes sense to me. So we want to change textDocument/references from returning Location[] to Location[] | { range: Range, locations: Location[] } then, correct?

If so, since we are no longer reusing the new type for textDocument/references, perhaps that should be addressed in a separate PR?

rcjsuen · 2018-11-20T12:09:16Z

https://github.com/Microsoft/vscode-languageserver-node/blob/c80ead2e4162cf3f7b547ea2dfc57e64dbd6d423/protocol/src/protocol.ts#L1568-L1578

@dbaeumer What should we return here if we are deprecating Definition?

Definition | LocationLink[] | null
Definition | LocationLink | LocationLink[] | null
Something else?

Signed-off-by: Remy Suen <remy.suen@gmail.com>

dbaeumer · 2018-11-20T14:15:10Z

I presume DeclarationProvider was introduced to add support for microsoft/language-server-protocol#605?

Yes.

What you suggested with ReferenceResult makes sense to me. So we want to change textDocument/references from returning Location[] to Location[] | { range: Range, locations: Location[] } then, correct?

Yes and we should address this in another PR if this is necessary at all.

What should we return here if we are deprecating Definition?

After thinking about this I would actually not deprecate Location and therefore not Definition. I would simply introduce a LinkLocation and add a DefinitionLink in the form

type DefinitionLink = LinkLocation | LinkLocation[] | null;

and the change the return value of the request to Definition | DefinitionLink. We then mimic the same for Declaration.

rcjsuen · 2018-11-20T15:01:47Z

@dbaeumer Is the name DefinitionLink okay? I think we may want to reuse this type again for microsoft/language-server-protocol#605 or am I mistaken?

dbaeumer · 2018-11-20T16:33:53Z

@rcjsuen I would do the same there. Have a type alias for DeclarationLink. In general I am tending more for having unique types even if they are aliases. Makes it clearer and easier to evolve.

rcjsuen · 2018-11-20T17:12:29Z

Thank you, @dbaeumer. I understand. It is the same as what you mentioned in #346 (comment).

I will do some poking at this pull request then...

dbaeumer · 2018-12-06T15:21:14Z