Removing comments so won't overwrite doc changes

[JimDaly]

Changes I made in dotnet/dotnet-api-docs#7968 were overwritten because the code comments replaced what was in the docs. According to @carlossanlop, this will happen until the code comments are removed.

Comments from @stephentoub in dotnet/dotnet-api-docs#7941 were:

Now, there's the related question of "what about GetAwaiter().GetResult() on a Task rather than on a configured awaiter, as those docs also say the same thing". When all of this support was introduced, the intent was in fact that no one should ever be using these directly, that they were purely for compiler consumption. However, there's a behavioral difference between task.Wait() and task.GetAwaiter().GetResult(), which is that, while functionally identical in terms of how they wait, the latter propagates the first exception that faulted/canceled the task whereas the former wraps the one or more exceptions into an AggregateException and throws that wrapper. As such, developers that want the original exception propagated often use .GetAwaiter().GetResult() instead of Wait. At this point, the right thing for TaskAwaiter and TaskAwaiter is probably to just strike those sentence from the docs, though some extra verbiage around the distinction from Task.Wait would be welcome. No one should be using GetAwaiter().GetResult() on any of the ValueTask variants for all the reasons discussed in https://devblogs.microsoft.com/dotnet/understanding-the-whys-whats-and-whens-of-valuetask/.

[ghost]

Tagging subscribers to this area: @dotnet/area-system-threading-tasks
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Changes I made in dotnet/dotnet-api-docs#7968 were overwritten because the code comments replaced what was in the docs. According to @carlossanlop, this will happen until the code comments are removed.

Comments from @stephentoub in dotnet/dotnet-api-docs#7941 were:

Now, there's the related question of "what about GetAwaiter().GetResult() on a Task rather than on a configured awaiter, as those docs also say the same thing". When all of this support was introduced, the intent was in fact that no one should ever be using these directly, that they were purely for compiler consumption. However, there's a behavioral difference between task.Wait() and task.GetAwaiter().GetResult(), which is that, while functionally identical in terms of how they wait, the latter propagates the first exception that faulted/canceled the task whereas the former wraps the one or more exceptions into an AggregateException and throws that wrapper. As such, developers that want the original exception propagated often use .GetAwaiter().GetResult() instead of Wait. At this point, the right thing for TaskAwaiter and TaskAwaiter is probably to just strike those sentence from the docs, though some extra verbiage around the distinction from Task.Wait would be welcome. No one should be using GetAwaiter().GetResult() on any of the ValueTask variants for all the reasons discussed in https://devblogs.microsoft.com/dotnet/understanding-the-whys-whats-and-whens-of-valuetask/.

Author:	JimDaly
Assignees:	-
Labels:	area-System.Threading.Tasks
Milestone:	-

[carlossanlop]

Thanks for submitting the change, @JimDaly. And sorry again that the comments got overwritten. I'll make sure your changes get brought back in dotnet-api-docs.

Actually, there are two additional places that also need to be removed: the remark on top of the generic TaskAwaiter<TResult> class:

runtime/src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/TaskAwaiter.cs

Line 312 in b37d604

/// <remarks>This type is intended for compiler use only.</remarks>

And in Future.cs, the GetAwaiter() method of the Task<TResult> generic class:

runtime/src/libraries/System.Private.CoreLib/src/System/Threading/Tasks/Future.cs

Line 519 in b37d604

/// <remarks>This method is intended for compiler use rather than use directly in code.</remarks>

The docs porting PR brought that remark again too: https://github.com/dotnet/dotnet-api-docs/pull/8004/files

[JimDaly]

Thanks for submitting the change, @JimDaly. And sorry again that the comments got overwritten. I'll make sure your changes get brought back in dotnet-api-docs.

Actually, there are two additional places that also need to be removed: the remark on top of the generic TaskAwaiter<TResult> class:

runtime/src/libraries/System.Private.CoreLib/src/System/Runtime/CompilerServices/TaskAwaiter.cs

Line 312 in b37d604

/// <remarks>This type is intended for compiler use only.</remarks>

And in Future.cs, the GetAwaiter() method of the Task<TResult> generic class:

runtime/src/libraries/System.Private.CoreLib/src/System/Threading/Tasks/Future.cs

Line 519 in b37d604

/// <remarks>This method is intended for compiler use rather than use directly in code.</remarks>

The docs porting PR brought that remark again too: https://github.com/dotnet/dotnet-api-docs/pull/8004/files
@carlossanlop I have applied these changes

[carlossanlop]

Thanks, @JimDaly !

I'll merge when the CI finishes.