Резюме по async (void) Метод: Что вернуть?

Это может быть тривиальный вопрос, но в настоящее время я делаю некоторые Inline-Documentation для будущих сотрудников и наткнулся на что-то вроде этого:

/// <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(() => { });
  }

}

Как вы, возможно, знаете, набрав 3 слэша над методом/полем/классом/независимо, запускает VisualStudio для выполнения сводки-сниппета-завершения.

Вопрос

Действительно ли Task действительное возвращаемое значение? И если да, то что я пишу в <returns></returns>?

Я, конечно, знаю, я могу игнорировать это, но ради полноты я готов написать там материал.

Ответ 1

Если мы вдохнемся из API, который недавно выпустил Microsoft, вы можете просто указать:

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

Мне не нравится "Объект задачи, который можно ждать" по той же причине, что я бы не украшал метод, который возвращает int с "целым числом, которое можно сравнить с нолем или использовать в математических операциях" - это не так 't описываем возвращаемое значение метода, оно описывает тип. Тип имеет собственную документацию, с которой можно ознакомиться.

Ответ 2

Лично я предпочитаю удалить эту часть <returns></returns> в этом случае.

Когда вы возвращаете Task, вы фактически возвращаете объект, который позволяет вызывающему пользователю узнать, когда заканчивается метод (разными способами, один из которых - await). Вы фактически не возвращаете никакого результата из метода (как вы это делаете, когда возвращаете Task<T>), так что вы просто возвращаете способ общения с вызывающим.

Если вам нужно что-то написать, я предпочитаю то, что полезно для тех, кто использует API:

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

Ответ 3

Как из MSDN:

Каждая возвращенная задача представляет собой текущую работу. Задача инкапсулирует информацию о состоянии асинхронного процесса и, в конечном итоге, либо конечный результат процесса, либо исключение что процесс поднимается, если это не удается.

Итак, вы можете написать свой метод, возвращая часть работы (= задание, которое, как я утверждаю, является допустимым возвращаемым типом), которое при выполнении ничего не возвращает (void) в вашем случае.

Ответ 4

Действительно ли задание является действительным возвращаемым значением?

Совершенно верно. Это то, что машина с асинхронным состоянием зависит от подкрылок. Семантически говоря, всегда существует много путаницы вокруг того, что тип возвращаемого значения определяется без соответствующего оператора 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 не нужны.

Ответ 5

Если упростить - это возврат как void, поэтому вы даже можете написать ожидаемый void.

Но если серьезно, верните Задача действительно действительное возвращаемое значение.