Why does withContext await for the completion of child coroutines

Question

The documentation of withContext states

Calls the specified suspending block with a given coroutine context, suspends until it completes, and returns

Answer 1

withContext creates a new job. This means that all coroutines launched inside are children of this job. It only returns when the job is finished. Because of structured concurrency, it only finishes when all child coroutines are finished too.

When any of the child jobs fails, the parent job is canceled. This will also cancel all other child jobs. Since withContext returns a result, the exception is thrown.

The documentation of CoroutineScope is helpful in this regards:

Every coroutine builder (like launch, async, etc) and every scoping function (like coroutineScope, withContext, etc) provides its own scope with its own Job instance into the inner block of code it runs. By convention, they all wait for all the coroutines inside their block to complete before completing themselves, thus enforcing the discipline of structured concurrency.

I think the documentation of withContext could be improved too. The documentation of Job and CoroutineContext are very helpful as they provide a more high-level point of view.

Furthermore, does that mean that we can use coroutineScope and withContext(coroutineContext) interchangeably, the only difference being a bit less boilerplate?

Yes, they should behave the same way. They are intended for different use cases though.

coroutineScope is meant to provide a scope for multiple parallel coroutines in which all will be canceled, if any fails.

withContext is designed to be used to switch the context (eg. the Dispatcher) for the given block of code.

Here is a similar question I recently asked on the kotlin discussion forums. The thread contains some more similar cases and further insight.