Zusammenfassung auf async (void) Methode: Was zurückgeben?

Question

Dies ist vielleicht eine triviale Frage, aber zur Zeit im, einige Inline-Dokumentation für künftige Mitarbeiter tun und stolperte über etwas wie das:

/// <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(() => { }); 
    } 

} 

Wie Sie vielleicht wissen, tippen 3 Schrägstriche über einer Methode/Feld/Klasse/was auch immer , löst VisualStudio aus, um die Zusammenfassung-Snippet-Vervollständigung auszuführen.

Frage

Ist Task tatsächlich ein gültiger Rückgabewert? Und wenn ja, was schreibe ich in die <returns></returns>?

Ich weiß sicherlich, ich kann das ignorieren, aber der Vollständigkeit halber bin ich bereit, Sachen dort zu schreiben.

Answer 1

Wenn wir Inspiration von API's that Microsoft haben vor kurzem produziert, Sie könnten nur Zustand:

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

I „Eine Aufgabe Objekt, das erwartet werden kann“ nicht mögen aus dem gleichen Grund habe ich eine Methode nicht schmücken würde, die zurückgibt ein int mit "eine ganze Zahl, die mit Null verglichen werden kann oder in mathematischen Operationen verwendet wird" - es beschreibt nicht den Rückgabewert der Methode, es beschreibt den Typ. Der Typ hat seine eigene Dokumentation, die konsultiert werden kann.

Answer 2

Persönlich bevorzuge ich in diesem Fall den <returns></returns> Teil zu entfernen.

Wenn Sie eine Task zurückgeben, geben Sie tatsächlich ein Objekt zurück, mit dem der Aufrufer wissen kann, wann die Methode endet (auf verschiedene Arten, von denen einer zu await ist). Sie geben tatsächlich kein Ergebnis von der Methode zurück (wie Sie es tun, wenn Sie eine Task<T> zurückgeben), so dass Sie nur eine Art der Kommunikation mit dem Anrufer zurückgeben.

Wenn Sie etwas schreiben hatte, ziehe ich es etwas, das nützlich ist, wem wird mit Hilfe der API:

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

Answer 3

Wie aus MSDN:

Jede zurück Aufgabe laufenden Arbeiten darstellt. Eine Aufgabe kapselt Informationen über den Status des asynchronen Prozesses und schließlich entweder das Endergebnis aus dem Prozess oder die Ausnahme , dass der Prozess ausgelöst wird, wenn es nicht erfolgreich ist.

So können Sie schreiben Ihre Methode ein Stück Arbeit nach Hause kommt (= eine Aufgabe, die Id argumentieren ist ein gültiger Rückgabetyp), die bei Ausführung kehrt nichts (void) in Ihrem Fall.

Answer 4

Wenn Sie vereinfachen - diese Rückkehr wie void, so können Sie sogar schreiben erwartbare void ist zurück.

Aber wenn ernst sein natürlich zurück Aufgabe ist eigentlich ein gültiger Rückgabewert.

Answer 5

Ist Task tatsächlich ein gültiger Rückgabewert?

Absolut. Dies ist, was die Async-State-Maschine auf Under-the-Cover verwendet. Semantisch gesehen gibt es immer viel Verwirrung darüber, dass ein Rückgabetyp ohne eine entsprechende return-Anweisung innerhalb des Methodenkörpers definiert wird. Diese Methode könnte stattdessen als solche geschrieben werden:

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

Was schreibe ich in der <returns></returns>?

Wenn ich die <summary></summary> Dokumentation Funktionen nutzen, ich bevölkern in der Regel nicht die <return></return> als IntelliSense werden Sie die Art sagen bereits. Zusätzlich wird es Ihnen sagen, ob es ein "(warte)" ist, was wirklich der Schlüssel hier ist. Wenn Sie zum Beispiel eine Methode schreiben, die eine Task zurückgibt, ist es wahrscheinlich und das ist wirklich der wichtigste Teil.

Wenn Sie verpflichtet fühlen, es zu beschreiben, würde ich tun, um eine solche vorschlagen:

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

Auch hier wird die IDE lassen Sie wissen, wenn Sie diese Funktion sind raubend, dass es „awaitable“ ist.

Hinweis:

AsyncFixer ist eine Erweiterung, die Sie Vorschläge für Sie, wie zu sagen, dass diese return Aussagen sollten Highlight wird tatsächlich statt, und dass die async und await Keywords nicht benötigt.