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

如果我们从API's that Microsoft最近产生的灵感中获取灵感，您可能会说：

<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

任务实际上是一个有效的返回值吗？

绝对。这就是异步状态机依赖于隐藏状态的原因。从语义上讲，在方法体内没有相应的return语句的情况下定义返回类型总是存在很多困惑。这种方法可以这样编写：

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

我在<returns></returns>中写了什么？

当我使用<summary></summary>文档功能时，我通常不会填充<return></return>，因为 IntelliSense 会告诉您已经输入的类型。此外，它会告诉你它是否是“（等待）”，这无论如何真的是关键。如果您正在编写一个返回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，那么您甚至可以写回等待的空白。

但是如果要认真，那么返回任务实际上是一个有效的返回值。

Answer 6

按照其他方法的Microsoft文档进行操作。我们总是这样：

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

您可以看到以下示例：

async（void）方法摘要：返回什么内容？

6 个答案: