Improve "Async return types" docs

[xakep139]

Summary

This PR rephrases a misleading statement regarding an awaiter type - an AsyncMethodBuilderAttribute should be applied on a type that an async method returns, not on a type that GetAwaiter() method returns.

The same requirement is showcased in the spec - https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/classes#15141-general.

As an example:

async CustomTask SomeMethodAsync() { /* ... */ }

// The attribute should be applied here:
[AsyncMethodBuilder(typeof(CustomAsyncMethodBuilder))]
class CustomTask
{
    public CustomAwaiter GetAwaiter() { /* ... */ }
}

class CustomAwaiter : INotifyCompletion
{
    public void OnCompleted(Action continuation) { /* ... */ }
}

internal class CustomAsyncMethodBuilder
{
    // The builder must implement a bunch of methods like (only a few required are listed):
    public static CustomAsyncMethodBuilder Create() { /* ... */ }
    public void SetException(Exception exception) { /* ... */ }
    public void SetResult() { /* ... */ }
    public CustomTask Task { get; }
}

Rigth now the documentation states that an AsyncMethodBuilderAttribute should be applied on a CustomAwaiter type from the example above, which is misleading.

---

Internal previews

📄 File	🔗 Preview link
docs/csharp/asynchronous-programming/async-return-types.md	Async return types (C#)

[BillWagner]

Hi @xakep139

Thanks for spotting this. However, the fix isn't correct either. I looked back at the spec and made a suggestion for different text.

[BillWagner]

Neither the original article nor this PR is correct. Let's try this instead:

Suggested change

An async method can return any type that has an accessible `GetAwaiter` method that returns an instance of an *awaiter type*. In addition, that type with a `GetAwaiter` method must have the <xref:System.Runtime.CompilerServices.AsyncMethodBuilderAttribute?displayProperty=nameWithType> attribute. You can learn more in the article on [Attributes read by the compiler](../language-reference/attributes/general.md#asyncmethodbuilder-attribute) or the C# spec for the [Task type builder pattern](~/_csharpstandard/standard/classes.md#15142-task-type-builder-pattern).

An async method can return any type that has an accessible `GetAwaiter` method that returns an instance of an *awaiter type*. In addition, the returned type must match the type of the parameter of `SetResult` and returned type of the `Task` property on the type specified by the <xref:System.Runtime.CompilerServices.AsyncMethodBuilderAttribute?displayProperty=nameWithType> attribute. You can learn more in the article on [Attributes read by the compiler](../language-reference/attributes/general.md#asyncmethodbuilder-attribute) or the C# spec for the [Task type builder pattern](~/_csharpstandard/standard/classes.md#15142-task-type-builder-pattern).