You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Rule proposal: Task returns documentation must begin with standard text. #3225
It would be helpful if the return documentation for a task must start with a standard text, just like a constructor (SA1642) or property (SA1623) must start with a specific text.
/// A task that represents the asynchronous operation.
For tasks that have a result (Task<T>), the documentation can start with
/// A task that represents the asynchronous operation. The task result contains [...]
This blog post also describes an alternative where you include the operation but I don't know how well this can be included in the analyzer:
/// <summary>/// Save the details of the current instance./// </summary>/// <returns>A task that represents the asynchronous save operation.</returns>publicasyncTaskSaveAsync(){// Implementation of this method.}
Another option is that this example text for a Task is included in the documentation for SA1616ElementReturnValueDocumentationMustHaveText so it can be easier discovered by users that don't know what text to use in this case.
I'm torn. The alternative for Task<T> is to simply describe the return value as if it was just T (i.e. the result of the method is just the result of the completed task).
It would be great, if we could configure how to handle Task/ValueTask (without T) returns.
My preference is to omit the documentation for Task and ValueTask (without T) completely.
With T, I prefer to just describe the result of the completed task.
Activity
sharwell commentedon Oct 28, 2020
I'm torn. The alternative for
Task<T>is to simply describe the return value as if it was justT(i.e. the result of the method is just the result of the completed task).sven-n commentedon Jul 15, 2022
It would be great, if we could configure how to handle Task/ValueTask (without T) returns.
My preference is to omit the documentation for Task and ValueTask (without T) completely.
With T, I prefer to just describe the result of the completed task.