How do you document that the `async`-coroutine-bui...

# coroutines

[Astronaut4449]

How do you document that the async-coroutine-builder of the kotlinx.coroutines library can throw exceptions since the coroutine builder itself does not throw an exception but the .await() does?

/**
 * @throws[IllegalStateException] ... <- would this be correct?
 */
fun CoroutineScope.doStuffAsync() = async { ... }

[louiscad]

@Astronaut4449 Why not just use a suspending function instead of using async and its structured concurrency gotchas?

[Astronaut4449]

@louiscad Good point. I guess using async from the caller side makes more sense in almost all cases. Is there even a scenario where it makes sense to use the async builder to start off a function?

[louiscad]

I don't think so. Using launch might make sense in some cases so long the function handles errors/throwables internally (if any) and doesn't throw which would propagate to the scope.

[Erik]

Also, the Deferred that is returned has the await function, which is documented well enough. However, what it throws might be an impl detail. I'd go for a suspending function that returns the value too.

[julian]

@louiscad What do you mean by "... and its structured concurrency gotchas"?

[louiscad]

@julian I mean throwing inside the async block cancels the parent CoroutineScope

[julian]

Thanks @louiscad!