Come documentare le eccezioni dei metodi asincroni?

Question

Metodo campione con documentazione 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) genera un'eccezione come previsto. Ecco un metodo asincrono:

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

    // async stuff... 
} 

WriteAsync(null), non sarà un'eccezione fino atteso. Devo specificare loin un tag exception? Penso che sarebbe rendere il consumatore pensa che chiamare WriteAsync potrebbe generare un ArgumentNullException e scrivere qualcosa del genere:

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

Qual è la migliore pratica per documentare eccezioni a metodi asincroni?

Answer 1

Non è una risposta diretta, ma personalmente consiglierei di appoggiarmi verso il fallimento veloce qui; questo potrebbe significare la scrittura 2 metodi:

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

Questo modello è anche un luogo ideale per aggiungere "percorso veloce" codice, ad esempio:

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 non sembra distinguere tra il metodo async lanciando un'eccezione e restituita Task con un'eccezione memorizzata nella proprietà Exception. Es .:

WebClient.DownloadFileTaskAsync(string, string)

Personalmente, io sceglierei di documentare le eccezioni, come parte della documentazione per il valore di ritorno (vale a dire l'restituita Task), dal momento che la distinzione può essere importante per i clienti.