Add "type" to textDocument/references results (icon, filtering)

[sean-mcmanus]

The C/C++ extension wants to be able to send back references of different types that users can determine what "type" of reference it is and filter out unwanted types -- in order to provide functionality equivalent to Visual Studio 2019. The types are

1. Confirmed reference (i.e. passes semantic checking): reference icon
2. Not a reference (i.e. has the same name, but fails semantic checking): cancel icon
3. Reference in a comment: comment icon
4. Reference in a string: string icon
5. Reference in an inactive (preprocessor) region: ? icon (or a better one, since it conflicts with 7)
6. Possible reference (Confirmation in progress): progress icon?
7. Possible reference (Confirmation canceled): ? icon (or a better one, since it conflicts with 5 and 7) -- this "type" doesn't exist in VS, but it seems like it should (at least for us).
8. Cannot confirm reference (due to some bug or "by design" limitation): ? icon

This is the screenshot from VS:

Our current "workaround" is to only send back Confirmed References (number 1), although we also plan to have some progress UI with a button that allows users to view the Confirmation in progress (number 6 items, merged in with number 1 items). We're currently implementing this for June: microsoft/vscode-cpptools#15 .

The relevant LSP that would need to be changed is at
https://microsoft.github.io/language-server-protocol/specification#textDocument_references

[dbaeumer]

@sean-mcmanus just to clarify: you are asking for a change of the LSP request and an implementation of the UI in VS Code?

[sean-mcmanus]

@dbaeumer Yes -- I wasn't sure if I should file a separate issue on the LSP site or not.

[dbaeumer]

@sean-mcmanus yes, please file a separate issue on the LSP side since this might be tackled independently from VS Code.

[jrieken]

Not a reference (i.e. has the same name, but fails semantic checking): cancel icon

This is funny. Searching for references returns references which are not references?

Confirmation in progress: progress icon?

How should that work? Will the result update when confirmation is done or does the user re-run reference search? The former doesn't fit nice into our provide-and-forget model, the latter isn't IMO the best UX

[sean-mcmanus]

Yes -- the "Not a reference" means the name is the same, but the IntelliSense type check failed. There are scenarios where users may want to still see what non-references got filtered out.

Our pending implementation for C++ Find All References is able to quickly get a list of "unconfirmed references" that match lexically, but semantic checking requires that every file with a reference needs to get compiled by our IntelliSense process, which could take a long time, so due to the inability of VS Code to allow streaming references (#20010), we're planning to show a popup progress dialog that shows the confirmation progress with buttons to allow users to show the "confirmed references" and/or "confirmation in progress" references (i.e. "unconfirmed" references), while we continue to continue to confirm the references, but the lack of "types"/icons means either the results will be ambiguously merged or only 1 "type" at a time will be shown. The user is not expected to have to re-run the references command, because our plan is to re-run it ourselves -- to enable us to return the more complete results later on. So when confirmation is 100% done (or canceled) the results will update and the progress dialog will disappear. If you have a better UX design, please let us know. I think we had an email thread on this streaming references issue a few months ago.