It's sometimes difficult to know what to put in the <returns> element of C# XML Documentation Comments when you are documenting a method that returns a Task. Should you note that a task is being returned, or should you describe the result of the task?
Having a look at the conventions across a number of C# projects (both Microsoft and OSS), I've settled on the following conventions as a 'best practice'.
For a simple Task with no result type, the following documentation style should be used:
/// A task that represents the asynchronous operation.
An alternative is to describe the operation. For example, a 'save' operation could be documented as follows:
/// A task that represents the asynchronous save operation.
For a Task
/// A task that represents the asynchronous operation. /// The task result contains the number of state entries written to the database.
Thanks for reading. I hope this post helps you document your methods.