Documenting Task returns (in C# XML Documentation Comments)

Some recommendations on how to write XML Documentation Comments for methods that return a Task object.


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.


Posted by Matthew King on 16 February 2017
Permission is granted to use all code snippets under CC BY-SA 3.0 (just like StackOverflow), or the MIT license - your choice!