Document edition hygiene.

[ehuss]

I believe there is some relationship between editions and spans, or at least with macros, dealing with crates of different editions. This should be documented. I'm not sure where to start here.

[ehuss]

I've been contemplating this recently, and have been wondering if we should document the precise behavior of how spans are used to detect edition behavior. Should we document exactly which tokens are used to determine a change in behavior? In most cases it is the first token of the thing that triggers the new behavior. For example, for the static_mut_refs, I believe it is the first token of the path to the static in the static expression (which oddly also includes field projections, when does that happen?). So for example, in unsafe { &crate::foo::my_static } the relevant token is crate (the edition of all other tokens does not matter). In other cases it is the innocent open brace token (rust-lang/rust#132963).

I'm a little on the fence about that level of specificity. But with the regressions we are encountering with 2024, I feel like it would be helpful to know exactly how things work, since seemingly innocent macros are causing problems.

I'm guessing that not much thought has gone into this, and thus the behavior is possibly not 100% intentional. That gives me pause to specify it, since in theory we could come up with better heuristics for detecting this.

EDIT: See rust-lang/rust#86539 for an identical request.

[petrochenkov]

There's an old issue about this (opened when the edition mechanism was introduced), and I recently wrote some update on the current state of affairs - rust-lang/rust#50122 (comment).
Given that I wouldn't want to document this in too much detail.