Update the messaging around the use of deinit for teardown

[medreisbach]

resolves rdar://132007317

Checklist:

• Code and documentation should follow the style of the Style Guide.
• If public symbols are renamed or modified, DocC references should be updated.

[grynspan]

Minor quibbles as noted.

[stmontgomery]

Thanks for improving these docs!

[stmontgomery]

Can you clarify what feature(s) of Swift concurrency, or which APIs, you mean here which assist with cleanup? I can think of defer, but I would consider that a basic language feature rather than a concurrency feature.

[FranzBusch]

I think what we should aim to push people towards is using with style methods e.g. try await withNetworkConnection { connection in ... }. This is the pattern that recommend to people to have guaranteed lifetimes with structured concurrency.

[grynspan]

That's something they have to write themselves, and explaining how to write one would get us into the weeds a bit.

[iamleeg]

There is precedent for describing how testing helps you design nicer APIs and vice versa, and it's something Apple has already published in the Xcode documentation: https://developer.apple.com/documentation/xcode/updating-your-existing-codebase-to-accommodate-unit-tests

So maybe we could take a similar approach here, where we show a with… function as an example of designing API+test together, but (as a separate task) create another doc that shows the thinking behind that design?

[grynspan]

Would this be an appropriate place to use a snippet?

[0xTim]

I think an example here would be extremely helpful for users trying to migrate