Jak dokumentować wyjątki metod asynchronicznych?

Question

Sposób próbki z dokumentacją XML:

// summary and param tags are here when you're not looking. 
/// <exception cref="ArgumentNullException> 
/// <paramref name="text" /> is null. 
/// </exception> 
public void Write(string text) 
{ 
    if (text == null) 
     throw new ArgumentNullException("text", "Text must not be null."); 

    // sync stuff... 
} 

Write(null) zgłasza wyjątek, zgodnie z oczekiwaniami. Oto sposób asynchroniczny:

public async Task WriteAsync(string text) 
{ 
    if (text == null) 
     throw new ArgumentNullException("text", "Text must not be null."); 

    // async stuff... 
} 

WriteAsync(null), nie rzuci wyjątek aż oczekiwany. Czy mimo to należy podać ArgumentNullException w tagu exception? Myślę, że byłoby to zrobić konsument uważa, że ​​powołanie WriteAsync może rzucić ArgumentNullException i napisać coś takiego:

Task t; 
try 
{ 
    t = foo.WriteAsync(text); 
} 
catch (ArgumentNullException) 
{ 
    // handling stuff. 
} 

Jaka jest najlepsza praktyka dokumentowania wyjątków w zakresie metod asynchronicznych?

Answer 1

Bezpośrednia odpowiedź: Bezpośrednia, ale osobiście radziłbym, aby skłonić się do szybkiego porażki; Może to oznaczać, pisząc 2 metody:

public Task WriteAsync(string text) // no "async" 
{ 
    // validation 
    if (text == null) 
     throw new ArgumentNullException("text", "Text must not be null."); 

    return WriteAsyncImpl(text); 
} 
private async Task WriteAsyncImpl(string text) 
{ 
    // async stuff... 
} 

Ten wzór jest również idealnym miejscem, aby dodać „szybką ścieżkę” kod, na przykład:

public Task WriteAsync(string text) // no "async" 
{ 
    // validation 
    if (text == null) 
     throw new ArgumentNullException("text", "Text must not be null."); 

    if (some condition) 
     return Task.FromResult(0); // or similar; also returning a pre-existing 
            // Task instance can be useful 

    return WriteAsyncImpl(text); 
} 

Answer 2

Microsoft wydaje się nie rozróżniać metody async zgłaszanie wyjątku i zwróconego Task z wyjątkiem zapisanym we właściwości Exception. Np .:

WebClient.DownloadFileTaskAsync(string, string)

Osobiście wybrałbym udokumentowanie wyjątków jako część dokumentacji zwracanej wartości (czyli zwracane Task), ponieważ różnica może być ważne dla klientów.