Skip to content

Rule proposal: Task returns documentation must begin with standard text. #3225

Open

Description

@supervos

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.

According to https://www.mking.net/blog/documenting-task-returns, the following text is mostly used:

/// 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>
public async Task SaveAsync()
{
    // 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.

Activity

  1. sharwell commented on Oct 28, 2020

    @sharwell
    Member

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

  2. sven-n commented on Jul 15, 2022

    @sven-n

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions