Annotate references with the name of the entity they occur in

[HighCommander4]

The response to textDocument/references is currently just Location[] | null.

However, clients may want to show, for each reference, information such as the name of the entity (e.g. function or class) in which the reference occurs, which they cannot easily compute on the client side.

Could the protocol be extended so the response is something like Reference[] | null, where Reference contains both a Location and possibly extra information like the name of the containing entity?

[dbaeumer]

I like the idea.

[raja-s]

Having a separate Reference structure is a good idea. There are potentially other interesting information a language server might want to include, for example the access type (read/write/both) in the case of references to a variable.

[dbaeumer]

From #1155: a preview in a reference structure would be helpful as well.

[avivdolev]

I think this proposal could also help in #763
Also, just want to +1 for adding access types (read/get | write/set) - it's super useful during debugging to know the possible places that modify something (rather than just read it).

Another implementation to consider, at least for backward-compatibility, is to keep the current Location[] | null response, and augment the Location type with a metadata field that can hold a key-value map, same way it was done for notebooks:

interface Location {
	uri: DocumentUri;
	range: Range;

          /**
	 * Additional metadata stored with the location
	 * document.
	 */
	metadata?: LSPObject;
}

[foolmoron]

Another implementation to consider, at least for backward-compatibility, is to keep the current Location[] | null response, and augment the Location type with a metadata field that can hold a key-value map, same way it was done for notebooks

It's equally BC to extend the Location interface with new props isn't it? Old usages can ignore the new props. Less data nesting that way.

[avivdolev]

@foolmoron
Yes it is- just took an example from another extension. Either way will be super helpful.
IMO one advantage for a metadata field is that each language can use its own key-value implementation of metadata, instead of finding some props that are useful to any arbitrary language.

[adonovan]

See #1911 for a generalization of 'references' queries to allow servers to offer a variety of other queries that take the same form of input (a selection) and produce the same form of results (a set of [annotated] source locations) so that the client can re-use the same UI machinery for all of them.