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

如果我们从最近微软生产的API中获取灵感,您可能只会声明:

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

我不喜欢"可以等待的任务对象",出于同样的原因,我不会修饰一个方法,该方法返回一个int"可以比较为零或在数学运算中使用的整数" - 它没有描述返回值该方法,它描述了类型.该类型有自己的文档,可以参考.

Answer 2

就个人而言,<returns></returns>在这种情况下,我更愿意删除该部分.

当你返回a时Task,你实际上正在返回一个对象,该对象允许调用者知道方法何时结束(以各种方式,其中之一就是await它).你实际上并没有从方法返回任何结果(你返回时的方式Task<T>),所以你只是返回一种与调用者通信的方式.

如果你不得不写一些东西,我更喜欢一些对使用API​​有帮助的东西:

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