How to document exceptions of async methods?
Not a direct answer, but personally I'd advise leaning towards fast-fail here; this might mean writing 2 methods:
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...
}
This pattern is also an ideal place to add "fast path" code, for example:
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);
}
Microsoft doesn't seem to differentiate between the async
method throwing an exception and the returned Task
having an exception stored in its Exception
property. E.g.:
WebClient.DownloadFileTaskAsync(string, string)
Personally, I would choose to document the exceptions as part of the documentation for the return value (i.e. the returned Task
), since the distinction may be important for clients.