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 with a result type, some details about the task result should be included. For example, a 'save' operation could be documented as follows:

/// 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.