Links to members from other types are currently confusing

[KevinCathcart]

Right now, for a referencing a member just the member's name is shown, (and linked). That is ideal for members on the current type or a base type. However, it is often rather suboptimal when referencing a member from a different type.

For example in the docs for JsonSourceGenerationMode, one of the enum values is described as:

When specified on GenerationMode, indicates that both type-metadata initialization logic and optimized serialization logic should be generated for all types. When specified on GenerationMode, indicates that the setting on GenerationMode should be used.

Given that two members with the same name on different types are being discussed, this is basically unreadable. The only way to understand what this is saying to click on each link in turn, and looking at which type is referenced.

But as bad as that is, things can be worse, like when a member from a different type is being referenced that has the same name as a member from the current type. Readers could very easily misunderstand what is being said, potentially with significant consequences. There are similar readability issues in many places. Indeed I'd argue that most references to a member from another type (other than a base class) have similar readability problems, with the exception of enum values, since the relevant enum type is often obvious from context.

But for the most art it would be far preferable if the members that are neither part of the current type, nor a base type were rendered qualified like so:

When specified on JsonSourceGenerationOptionsAttribute.GenerationMode, indicates that both type-metadata initialization logic and optimized serialization logic should be generated for all types. When specified on JsonSerializableAttribute.GenerationMode, indicates that the setting on JsonSourceGenerationOptionsAttribute.GenerationMode should be used.

Sure, those names look large and busy, but at least you can understand them when you read them.

[dotnet-policy-service[bot]]

Tagging subscribers to this area: @dotnet/area-system-runtime

[KevinCathcart]

This is more a general issue, so area-Meta may be the better tag?