async (void) 方法摘要：返回什么？

Question

這可能是一個微不足道的問題，但目前我正在為未來的同事做一些內聯文檔，並偶然發現了這樣的事情：

/// <summary>
/// This Class is totaly useless
/// </summary>
public class DummyClass {

  /// <summary>
  /// Will do nothing
  /// </summary>
  public void DoNothing() {
  }

  /// <summary>
  /// Will do nothing async
  /// </summary>
  /// <returns></returns> <---- What to write here?
  public async Task DoNothingAsync() {
    await Task.Run(() => { });
  }

}

您可能知道，在 Method/Field/Class/whatever 上方鍵入 3 個斜杠，會觸發 VisualStudio 執行它的 Summary-Snippet-Completion。

問題

Task實際上是一個有效的返回值嗎？ 如果是這樣，我在<returns></returns>什么？

我當然知道，我可以忽略這一點，但為了完整起見，我願意在那里寫東西。

Answer 1

如果我們從Microsoft最近生產的API 中獲得靈感，您可能會說：

<returns>No object or value is returned by this method when it completes.</returns>

我不喜歡“可以等待的任務對象”，原因與我不會用“可以與零進行比較或用於數學運算的整數”來裝飾返回int的方法 - 它沒有描述返回方法的值，它描述了類型。 該類型有自己的文檔，可以參考。

Answer 2

就個人而言，我更喜歡在這種情況下刪除<returns></returns>部分。

當您返回Task ，您實際上是在返回一個對象，該對象允許調用者知道方法何時結束（以各種方式，其中之一是await它）。 您實際上並沒有從該方法返回任何結果（返回Task<T>時所做的方式），因此您只是返回了一種與調用者進行通信的方式。

如果你必須寫一些東西，我更喜歡那些對使用 API 的人有幫助的東西：

/// <returns>A task object that can be awaited</returns> 

Answer 3

Task 實際上是一個有效的返回值嗎？

絕對。 這就是異步狀態機在幕后所依賴的。 從語義上講，在方法主體中定義返回類型而沒有相應的return語句時，總是存在很多混淆。 這個方法可以這樣寫：

public Task DoNothingAsync()
{
    return Task.Run(() => { });
}

我在<returns></returns>寫了什么？

當我使用<summary></summary>文檔功能時，我通常不會填充<return></return>因為IntelliSense會告訴您類型。 此外，它會告訴你它是否是一個“（awaitable）”，無論如何這才是真正的關鍵。 例如，如果您正在編寫一個返回Task的方法，則它是可等待的，這確實是最重要的部分。

如果您覺得有必要描述它，我建議您這樣做：

<returns>
   A <see cref="Task"> object that represents an asynchronous operation.
</returns>

同樣，當您使用此函數時，IDE 會通知您它是“可等待的”。

注意：

AsyncFixer是一個擴展，它將為您突出顯示建議，例如告訴您這些實際上應該是return語句，並且不需要async和await關鍵字。

Answer 4

從MSDN ：

每個返回的任務代表正在進行的工作。 任務封裝了有關異步進程狀態的信息，以及最終進程的最終結果或進程在不成功時引發的異常的信息。

因此，您可以編寫方法返回一項工作（= 一個任務，我認為這是一個有效的返回類型），在您的情況下，該方法在執行時不返回任何內容（ void ）。

Answer 5

如果簡化 - 這個返回像void ，所以你甚至可以寫awaitable void is return。

但如果認真當然 return Task實際上是一個有效的返回值。

Answer 6

遵循其他方法的 Microsoft 文檔。 我們總是像這樣：

• Asynchronously does something...
• A <task> that represents the asynchronous ...

您可以看到以下示例：

• Stream.CopyToAsync 方法
• ChannelReader.ReadAsync(CancellationToken) 方法