Document auto trait inference for async blocks

[eholk]

We are in the process of changing this (rust-lang/rust#69663), but it would be good to document the existing rules before changing them. This should also help explain the compilation errors people are getting in the meantime.

[pnkfelix]

I think this documentation would be improved if it had examples of both sides of the coin. Think of it as how some theorems are illuminated by showing both examples and counter-examples.

E.g. you have shown a case where bar() overlaps the foo().await, and thus its auto-traits end up applying to the future produced by the async block.

So I think the other thing I would show is some other bit of code, perhaps as close as possible to the provided example, (or even modify the existing example), where some temporary baz() does not overlap the foo().await, and so its auto-traits do not apply to the future.

[eholk]

I added a couple more examples, one that's a slightly more complex version of the previous example, and another that shows a small change to remove a borrow from the scope.

I'm not convinced these are the best examples, but they're an example of the cases I've looked closest at and they do highlight some of the trickier issues here.

What do you think?

[ehuss]

@pnkfelix Did you have any more comments on this?