Summary on async (void) Method: What to return?
Personally, I do prefer to remove that <returns></returns>
part in this case.
When you return a Task
, you're actually returning an object that allows the caller to know when the method ends (In various ways, one of which is to await
it). You're not actually returning any result from the method (The way you do when you return a Task<T>
),so you're just returning a way of communication with the caller.
If you had to write something, i prefer something that is helpful to whomever is using the API:
/// <returns>A task object that can be awaited</returns>
If we take inspiration from API's that Microsoft have produced recently, you might just state:
<returns>No object or value is returned by this method when it completes.</returns>
I dislike "A task object that can be awaited" for the same reason I wouldn't decorate a method that returns an int
with "an integer which can be compared to zero or used in mathematical operations" - it doesn't describe the return value of the method, it describes the type. The type has its own documentation which can be consulted.