CODEWITHSUNDEEP
c#visual-studioasync-await
lokusking
lokusking

Reputation: 7456

Summary on async (void) Method: What to return?

This is maybe a trivial question but currently im doing some Inline-Documentation for future Coworkers and stumbled upon something like that:

/// <summary>
/// This Class is totaly useless
/// </summary>
public class DummyClass {

  /// <summary>
  /// Will do nothing
  /// </summary>
  public void DoNothing() {
  }

  /// <summary>
  /// Will do nothing async
  /// </summary>
  /// <returns></returns> <---- What to write here?
  public async Task DoNothingAsync() {
    await Task.Run(() => { });
  }

}

As you might know, typing 3 slashes above an Method/Field/Class/whatever, triggers VisualStudio to perform its Summary-Snippet-Completion.

Question

Is Task actually a valid return-value? And if so, what do i write in the <returns></returns>?

I surely do know, i can ignore this, but for the sake of completeness im willing to write stuff there.

Upvotes: 29

Views: 4013

Answers (6)

Leandro Pereira
Leandro Pereira

Reputation: 1

Following the Microsoft docs of other methods. We have always something like:

  • Asynchronously does something...
  • A <task> that represents the asynchronous ...

You can see examples such as:

Upvotes: 0

David Pine
David Pine

Reputation: 24535

Is Task actually a valid return-value?

Absolutely. This is what the async-state machine relies on under-the-covers. Semantically speaking, there is always a lot of confusion around having a return type defined without a corresponding return statement within the method body. This method could be written as such instead:

public Task DoNothingAsync()
{
    return Task.Run(() => { });
}

What do I write in the <returns></returns>?

When I utilize the <summary></summary> documentation features, I usually do not populate the <return></return> as IntelliSense will tell you the type already. Additionally, it will tell you if it is an "(awaitable)" which is really the key here anyways. If you're writing a method that returns a Task for example, it is awaitable and that is really the most important part.

If you feel obligated to describe it, I would suggest doing so as such:

<returns>
   A <see cref="Task"> object that represents an asynchronous operation.
</returns>

Again, the IDE will let you know when you're consuming this function that it is "awaitable".

enter image description here

Note:

AsyncFixer is an extension that will highlight suggestions for you, such as telling you that these should actually be return statements instead and that the async and await keywords are not needed.

Upvotes: 3

Zein Makki
Zein Makki

Reputation: 30032

Personally, I do prefer to remove that <returns></returns> part in this case.

When you return a Task, you're actually returning an object that allows the caller to know when the method ends (In various ways, one of which is to await it). You're not actually returning any result from the method (The way you do when you return a Task<T>),so you're just returning a way of communication with the caller.

If you had to write something, i prefer something that is helpful to whomever is using the API:

/// <returns>A task object that can be awaited</returns>

Upvotes: 12

Damien_The_Unbeliever
Damien_The_Unbeliever

Reputation: 239724

If we take inspiration from API's that Microsoft have produced recently, you might just state:

<returns>No object or value is returned by this method when it completes.</returns>

I dislike "A task object that can be awaited" for the same reason I wouldn't decorate a method that returns an int with "an integer which can be compared to zero or used in mathematical operations" - it doesn't describe the return value of the method, it describes the type. The type has its own documentation which can be consulted.

Upvotes: 23

MakePeaceGreatAgain
MakePeaceGreatAgain

Reputation: 37020

As from MSDN:

Each returned task represents ongoing work. A task encapsulates information about the state of the asynchronous process and, eventually, either the final result from the process or the exception that the process raises if it doesn't succeed.

So you can write your method returns a piece of work (= a task, which I´d argue is a valid return-type) that when executed returns nothing (void) in your case.

Upvotes: 2

Aleksandr Zolotov
Aleksandr Zolotov

Reputation: 1100

If simplify - this return like void , so you can even write awaitable void is return.

But if be serious of course return Task is actually a valid return-value.

Upvotes: 2

Related Questions