XML doc comments need to respect accessibility limitations for referenced assemblies

[jaredpar]

XML doc comments do not respect accessibility today when referring to symbols in assemblies. Instead they act as if they have [InternalsVisibleTo] any assembly. This is behavior that goes back to C# 1.0 but it is becoming a problem in today's ecosystem where there is an increasing amount of shared code between assemblies and source generators that produce types with identical FQN. When this happens XML doc comment references to such types become ambiguous and the only resolution available to customers is extern alias's.

A real world example of this problem is winforms PR 10320. In this case the CSWin32 generator is used in two assemblies: System.Drawing.Common and System.Windows.Forms.Primitives. The consuming assembly has IVT for one but not the other. That means uses of the types in code is fine because the compiler only considers the assembly with IVT. Yet the exact same references in XML doc comments are ambiguous because they have effectively IVT to both assemblies.

This feels like a problem that we're going to hit more and more as source generators and shared code increase in popularity. Starting in .NET 9 I think we need to consider changing XML doc comments to respect accessibility when using language version 13.0 or higher. That is a breaking change and it's likely to impact a non-trivial number of customers as this is behavior that goes back to C# 1.0. To mitigate we should introduce a feature flag to control this behavior: XmlDocLegacyVisibility. When set to true or language version is 12 or earlier the compiler will exhibit the existing behavior, otherwise it will use normal accessibility when considering external symbols.

Note: no change is being proposed for XML doc accessibility to symbols in the same assembly. Those will continue to have unrestricted access.

Issues for context:

• XML comment crefs unusable with shared/duplicate CsWin32 winforms#10524
• Start using CsWin32 in System.Drawing.Common winforms#10320 (comment)

[elachlan]

Related:
#4033
#51013

[sharwell]

In the past, this issue has been fairly easy to resolve with using alias directives. This includes dotnet/winforms#10525 and dotnet/winforms#10320.

[JeremyKuhne]

In the past, this issue has been fairly easy to resolve with using alias directives. This includes dotnet/winforms#10525 and dotnet/winforms#10320.

@sharwell If this involves manually creating an alias for every single conflicting type I wouldn't call this easy. We have a significant amount of interop (thousands of definitions).

[sharwell]

@JeremyKuhne It only applies to identifiers that appear in a cref attribute, which is many fewer than exist.

Note that one possible resolution to the issue is for the C# compiler to silently prefer accessible symbols before issuing ambiguity warnings.

[JeremyKuhne]

It only applies to identifiers that appear in a cref attribute, which is many fewer than exist.

I also applies to <inheritdoc>, which we're also doing.

[sharwell]

Also related to #77