Runtime: Document that CancellationToken.None is default(CancellationToken)

[scalablecory]

I feel that current practice of providing two overloads for cancellable async methods is overly verbose and leads to bloated APIs and error-prone implementation.

Task DoAsync()
Task DoAsync(CancellationToken token)

It would be much easier to use default parameters, for instance:

Task DoAsync(CancellationToken token = default(CancellationToken))

This currently works, but default(CancellationToken) being equivalent to CancellationToken.None is undocumented behavior (not mentioned in comments or MSDN) and thus not something we can 100% count on working in the future.

I'd like to propose the simple change of making this a documented feature.

[stephentoub]

You can definitely count on this being the case; even if we wanted to change it (we don't), we wouldn't be able to as too much code depends on it. But your suggestion to improve the docs with the information is a good one.

[rpetrusha]

We'll update the documentation to note that default(CancellationToken) is equivalent to default(CancellationToken). The changes should appear in the next documentation update later this month.

Thanks for making this suggestion.

[stephentoub]

Thanks, @rpetrusha.

[scalablecory]

Thanks.

[stephentoub]

Thanks for the suggestion.

[ohadschn]

I think the wording could be better.

The description says:

Returns an empty CancellationToken value.

The remarks section says:

You can also use the C# default(CancellationToken) statement to create an empty cancellation token.

So it's clear that both methods create empty cancellation tokens, but nothing defines exactly what an "empty" cancellation token means, and specifically it's not clear that two "empty" cancellation token are guaranteed to be equal.

[ohadschn]

@scalablecory If you agree with me, perhaps re-open this issue?

[svick]

@ohadschn Issues in .Net documentation on docs.microsoft.com belong to the dotnet/docs repo, so I think you should create an issue there, instead of reopening it here. Or you could even submit a PR fixing it yourself.

[ohadschn]

@svick done: https://github.com/dotnet/docs/pull/3787.