Implement find all references to preprocessing symbols

[Rekkonnect]

Closes #66009

Implementation Notes

This implementation adds support for finding references to preprocessing symbols.

A new symbol reference finder was added for preprocessing symbols. The projects that the finder is performed on are not filtered, just like namespaces. This decision was made as the name of the preprocessing symbol is the only factor determining equality against another preprocessing symbol.

Preprocessing symbols now implement Accept(SymbolVisitor) methods to support the visitor that yields the FAR results to the LSP. Also, more support was added for preprocessing symbols in LSP content, including the classification type.

CanBeReferencedByName also supports preprocessing symbols.

OrderLocations now compares against nullable location instances, to correctly enable ordering of location instances. This was required for cases where a symbol does not have a single source definition like global namespaces, assembly or module symbols. Thus, Location is marked as nullable in VSInternalReferenceItem, and is treated as such in code that may include null Location instances.

Public API

An API proposal has been opened to cover the newly introduced public APIs: #66510
Only CreatePreprocessingSymbol is added in this PR and is mentioned in the API proposal.

CreatePreprocessingSymbol is useful for the resolution of the symbol in PreprocessingSymbolKey, as well as the retrieval of the preprocessing symbol in the custom implementation of getting the preprocessing symbol at the given syntax node, in Workspaces.

Tests

There are unit tests covering:

• the references of preprocessing symbols across
  • a single document
  • multiple documents
  • multiple projects
  • between C# and VB projects
• placing the caret on top of a preprocessing symbol name
  • when defining the preprocessing symbol in #define, #undef and #Const statements
  • inside a #Const assignment expression
  • in #if, #elif, #If, #ElseIf statements
• appearing multiple times in the same line
• not being referred within #region, #endregion, #pragma warning disable/restore
  • this is specifically handled manually until GetPreprocessingSymbolInfo returns info when inside #pragma warning directive #72907 is resolved

[CyrusNajmabadi]

Can you explain why you you needed to make the compiler level changes here?

[Rekkonnect]

The symbol finder uses a mechanism to determine the documents to search for, which is also determined by the containing assembly of the symbol (if I understood correctly), which I thought required implementing the appropriate properties, and also enhancing resolution of certain properties of the nodes and tokens.

[CyrusNajmabadi]

The symbol finder can do whatever it needs on a per symbol basis. In other words, the logic can be entirely different depending on what type of symbol is being searched for.

It's not clear to me yet what it would need those properties for in the case of pp symbols. Thanks!

[Rekkonnect]

It seems like the finder is flexible enough, so if I understand correctly it would be best avoided to implement the containing assembly and module symbols, if possible.

However, from what I've seen the symbol visitors need to stay in place and be implemented during traversal.

[CyrusNajmabadi]

Not sure what you are referring to when you say "symbol visitor"

[Rekkonnect]

I'm referring to the Accept methods on the PreprocessingSymbol classes that take a SymbolVisitor to operate a visit on the symbol, which were previously throwing a NotSupportedException. Since the visitors were visiting preprocessing symbols, the exception was being thrown, and I thought they had to be adjusted to accept visits using the DefaultVisit method.

[jcouv]

You'll need to go through API review process for proposed public API addition.
https://github.com/dotnet/roslyn/blob/main/docs/contributing/API%20Review%20Process.md

Tagging @333fred as FYI

[Rekkonnect]

There's even more coming, will push my progress tomorrow

[333fred]

@Rekkonnect please follow our public API process before proposing PRs, as we documented in the process: https://github.com/dotnet/roslyn/blob/main/docs/contributing/API%20Review%20Process.md#pull-requests.

[AlekseyTs]

LGTM (commit 89), pending new API review.

[AlekseyTs]

@dotnet/roslyn-compiler For the second review.

[Rekkonnect]

@dotnet/roslyn-compiler the API proposal was approved, pending second review

[AlekseyTs]

@dotnet/roslyn-compiler For the second review

[AlekseyTs]

@dotnet/roslyn-compiler For the second review

[AlekseyTs]

@dotnet/roslyn-compiler For the second review

[AlekseyTs]

@333fred, @dotnet/roslyn-compiler For the second review for a community PR

[333fred]

Compiler changes lgtm

[CyrusNajmabadi]

This has two compiler sign offs, and IDE sign off. My intent is to check this in tomorrow. Just giving it time in case anyone is surpirsed by that and wanted to bring up any final issues.