api-doc-tools

api-doc-tools copied to clipboard

This was previously reported at https://github.com/aspnet/EntityFramework.ApiDocs/issues/25, specifically for methods that contain cancelationToken = default, which is a really common pattern,but it could apply to other defaults, not sure.

From the original issue:

In https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.savechangesasync?view=efcore-2.1 it says signature for SaveChangesAsync is

    public virtual System.Threading.Tasks.Task<int> SaveChangesAsync (
        System.Threading.CancellationToken cancellationToken = null);

Obviously, if you try overriding SaveChangesAsync using the above example, it'll give you the following error:

Using default(CancellationToken) instead of null solves the issue:
public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default(CancellationToken))

In fact the original signature is:

    public virtual Task<int> SaveChangesAsync(
        CancellationToken cancellationToken = default)

cc @joelmartinez

So this seems to be a compiler-level thing … the assembly metadata doesn't seem to (afaik) give any indication when the user-supplied value for the parameter is null vs default.

I guess the question here is whether for C# signatures, should we switch to using default for all of these instances, rather than using null.

@dend, thoughts?

Ran into this again, hopefully someone can take a look at some point.

Hi @roji ... this definitely has not been forgotten. In fact, there's an internal issue (linking it here just for reference). I don't have an exact ETA, but it will definitely be resolved at some point :)

Thanks @joelmartinez!