Podsumowanie na async (void) Metoda: Co zwrócić?

Question

To może trywialne pytanie, ale obecnie im jakiejś inline-dokumentacja dla przyszłych współpracowników i natknął się na coś takiego:

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

} 

Jak pewnie wiesz, wpisując 3 ukośniki powyżej metodę/Pole/klasy/whatever , uruchamia VisualStudio, aby wykonać jego Podsumowanie-Snippet-Completion.

Pytanie

Czy Task rzeczywiście ważny zwrot wartość? A jeśli tak, to co napiszę w <returns></returns>?

Z pewnością wiem, mogę to zignorować, ale ze względu na całkowitą gotowość do napisania tam rzeczy.

Answer 1

Jeśli weźmiemy inspirację z API's that Microsoft przyniosły niedawno, może po prostu stan:

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

Nie lubię „obiektu zadania, które mogą być oczekiwany” z tego samego powodu nie będę ozdobić metodę, która zwraca int z "liczbą całkowitą, która może być porównywana do zera lub używana w operacjach matematycznych" - nie opisuje wartości zwracanej metody, opisuje typ. Typ ma własną dokumentację, z którą można się zapoznać.

Answer 2

Osobiście wolę usunąć tę część <returns></returns> w tym przypadku.

Po zwrocie numeru Task faktycznie zwracasz obiekt, który pozwala dzwoniącemu dowiedzieć się, kiedy kończy się metoda (na różne sposoby, z których jeden to await). W rzeczywistości nie zwracasz żadnych wyników z metody (Sposób, w jaki robisz, gdy zwracasz numer Task<T>), więc właśnie zwracasz sposób komunikacji z dzwoniącym.

Jeśli miał coś napisać, wolę coś, co jest pomocne dla każdego, kto korzysta z API:

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

Answer 3

począwszy od MSDN:

Każdy zwracany reprezentuje zadanie trwające prace. Zadanie obejmuje informacje o stanie procesu asynchronicznego i, ostatecznie, ostateczny wynik procesu lub wyjątku, który proces podnosi, jeśli nie powiedzie się.

Więc można napisać metoda zwraca dzieło (= zadanie, którego bym kłótnie jest ważny zwrot-type), który po uruchomieniu nic nie zwraca (void) w Twoim przypadku.

Answer 4

Jeśli to uprościć - ten powrót jest taki, jak void, dzięki czemu można nawet napisać niezapomniana pustka jest powrotem.

Ale jeśli będzie poważny, oczywiście powróci Zadanie jest rzeczywiście poprawną wartością zwracaną.

Answer 5

Czy Zadanie jest rzeczywiście poprawną wartością zwracaną?

Absolutnie. Oto, na czym polega maszyna stanu asynchronicznego na under-the-covers. Semantycznie rzecz biorąc, zawsze istnieje wiele nieporozumień związanych z typem zwrotnym zdefiniowanym bez odpowiadającego oświadczenia return w treści metody. Metoda ta może być zapisana jako takich zamiast:

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

Co mam napisać w <returns></returns>?

Kiedy wykorzystać <summary></summary> możliwości dokumentacja, zazwyczaj nie wypełnienia pól <return></return> jak IntelliSense powie typ już. Dodatkowo poinformuje Cię, czy jest to "(godny zaufania)", który tak naprawdę jest tutaj kluczem. Jeśli piszesz metodę, która zwraca na przykład Task, jest ona nieoceniona i to naprawdę jest najważniejsza część.

Jeśli czujesz się zobowiązany, żeby to opisać, proponuję robić to jako takie:

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

Ponownie IDE pozwoli Ci wiedzieć, kiedy jesteś spożywania tej funkcji, że jest „awaitable”.

Uwaga:

AsyncFixer jest rozszerzeniem, które zaprezentuje propozycje dla Ciebie, takie jak mówienie, że powinny one być w rzeczywistości return oświadczenia zamiast i że te async i await słów kluczowych nie są potrzebne.