&{mut} T may (briefly) write garbage

[nia-e]

Per opsem consensus on the topic of reference validity, expand the docs on references to account for this. Though still not explicitly settled, this also includes language allowing changing a wrapping enum discriminant (e.g. in the case of an Option<bool> handing out a &mut to the inner bool).

r? RalfJung

[rustbot]

RalfJung is not on the review rotation at the moment.
They may take a while to respond.

[RalfJung]

Thanks! However if we land this as-is it is in direct contradiction to https://doc.rust-lang.org/nightly/reference/behavior-considered-undefined.html which IMO would not be a good state to be in. I think we have to update the reference first.

When I suggested FCP'ing the discriminant meant I meant an issue in https://github.com/rust-lang/unsafe-code-guidelines/ where we can gather consensus on decisions without having to also figure out how to stably document them. :)

Cc @rust-lang/opsem