Add SymbolDisplayGenericsOptions.IncludeArity as an alternative to SymbolDisplayGenericsOptions.IncludeTypeParameters

[ericstj]

Background and Motivation

Today the only value for SymbolDisplayGenericsOptions that shows the number of type parameters is IncludeTypeParameters which includes all the parameter names.

Parameter names are not strictly speaking part of the surface area. Derived types can use different parameter names, and changing the generic parameter name is not breaking.

APICompat uses SymbolDisplayGenericsOptions when producing a comparison key for API. PublicApiAnalyzer does as well. As a result both of these tools prohibit changing the name of a generic parameter.

Proposed API

namespace Microsoft.CodeAnalysis
{
    /// <summary>
    /// Specifies the options for how generics are displayed in the description of a symbol.
    /// </summary>
    [Flags]
    public enum SymbolDisplayGenericsOptions
    {
        /// <summary>
        /// Omits the type parameter list entirely.
        /// </summary>
        None = 0,

        /// <summary>
        /// Includes the type parameters. 
        /// For example, "Goo&lt;T&gt;" in C# or "Goo(Of T)" in Visual Basic.
        /// </summary>
        IncludeTypeParameters = 1 << 0,

        /// <summary>
        /// Includes type parameters and constraints.
        /// For example, "where T : new()" in C# or "Of T as New" in Visual Basic.
        /// </summary>
        IncludeTypeConstraints = 1 << 1,

        /// <summary>
        /// Includes <c>in</c> or <c>out</c> keywords before variant type parameters.
        /// For example, "Goo&lt;out T&gt;" in C# or (Goo Of Out T" in Visual Basic.
        /// </summary>
        IncludeVariance = 1 << 2,

+        /// <summary>
+        /// Represents the arity while omitting the actual type parameter names.
+        /// For example, "Dictionary&lt;,&gt;" in C# or "Dictionary(Of ,)" in Visual Basic.
+        /// </summary>
+        IncludeArity = 1 << 3,
    }
}

Usage Examples

using Microsoft.CodeAnalysis;
using Microsoft.CodeAnalysis.CSharp;

// Create a format with specific options
var format = SymbolDisplayFormat.FullyQualifiedFormat.WithGenericsOptions(SymbolDisplayGenericsOptions.IncludeArity);

var type = typeof(Dictionary<,>);
MetadataReference mdRef = MetadataReference.CreateFromFile(type.Assembly.Location);

var cSharpCompilation = CSharpCompilation.Create($"AssemblyLoader_{DateTime.Now:MM_dd_yy_HH_mm_ss_FFF}")
    .AddReferences(mdRef);

var typeSymbol = cSharpCompilation.GetTypeByMetadataName(type.FullName);

var formattedType = typeSymbol.ToDisplayString(format);

Console.WriteLine($"Formatted type: {formattedType}");

Expected output:

Formatted type: global::System.Collections.Generic.Dictionary<,>

Alternative Designs

Some alternate API for rendering a symbol - like fetching a DocID or using SyntaxGenerator.

Risks

[CyrusNajmabadi]

@ericstj I'm not quite getting the use case. CAn you flesh out the example more, including where generics are used today, and why the actual type argument values are a problem?

[ericstj]

Here are two cases:
https://github.com/dotnet/sdk/blob/26854d4fe75c45af1c17e696d98ca4c8b509f170/src/Compatibility/ApiCompat/Microsoft.DotNet.ApiCompatibility/Comparing/SymbolEqualityComparer.cs#L40
https://github.com/dotnet/roslyn-analyzers/blob/b07c100bfc66013a8444172d00cfa04c9ceb5a97/src/PublicApiAnalyzers/Core/Analyzers/DeclarePublicApiAnalyzer.cs#L74

It's actually non-breaking to change the name of a type parameter, however we'd like to make that an optional rule that folks can enable. To do this we'd like to have a symbol representation that omits the generic parameter names, but still represents the arity. That way we can create a key that represents the API without including non-essential information (parameter names). It's a similar scenario to the format of typeof and the docID syntax - which both omit the generic parameter names. If there's an existing API we should be using here I can also investigate changing how we produce the key string.

[CyrusNajmabadi]

I'd probably prefer emitting as List`1. So something about wanting emitting the rarity instead.

[ericstj]

I'm not picky on the precise format here. It just needs to represent the number of generic parameters and not their names.

[CyrusNajmabadi]

I bring it up because compiler has UseArityForGenericTypes as an internal option currently.

[ericstj]

Maybe we can just use GetDocumentationCommentId. That does format like we'd want. I might give it a try and see if its' reasonable.

[ericstj]

One downside I see for swapping to different methods for this is that we call it a lot. So much that I've been thinking about adding a cache for these strings. It would be nice if ISymbol would cache some of these. Maybe we should wrap all the ISymbol interfaces and add caching for the methods/properties we call the most.

[ericstj]

Looks like GetDocumentationCommentId isn't sufficient as this omits return value. I think exposing UseArityForGenericTypes would work for us.

[ericstj]

Ok I tested out using UseArityForGenericTypes by setting through reflection. This worked well for classes, but not methods. I would also like a similar setting for methods.

[CyrusNajmabadi]

in cases like this, where you're making a domain-specific key, our recommendation usually becomes: figure out what your domain needs, and extract out of the symbols. We're unlikely to add a feature (like for methods) that nothing else uses. We end up just chasing how the feature works, as opposed to some facility intrinsic to what the language is modeling.

[ericstj]

I was able to make this work by combining the DocId with the DocID of the type/return-value for members. This gives me what I need.

[ericstj]

Actually, I see there's a SymbolDisplayParts API, that might be a better way to handle this. I'll experiment with that.

[CyrusNajmabadi]

And with the SymbolDisplayParts, you can see which are TypeParameter symbols. And you could elide those or transform them into anything you want.

[ericstj]

Exactly, that's what I'm doing. 👍 I'll close this as I think I have what I need.