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;
}