Function rustc_expand::mbe::transcribe::maybe_use_metavar_location

fn maybe_use_metavar_location(
    cx: &ExtCtxt<'_>,
    stack: &[Frame<'_>],
    metavar_span: Span,
    orig_tt: &TokenTree
) -> TokenTree

Usually metavariables $var produce interpolated tokens, which have an additional place for keeping both the original span and the metavariable span. For tt metavariables that’s not the case however, and there’s no place for keeping a second span. So we try to give the single produced span a location that would be most useful in practice (the hygiene part of the span must not be changed).

Different locations are useful for different purposes:

• The original location is useful when we need to report a diagnostic for the original token in isolation, without combining it with any surrounding tokens. This case occurs, but it is not very common in practice.
• The metavariable location is useful when we need to somehow combine the token span with spans of its surrounding tokens. This is the most common way to use token spans.

So this function replaces the original location with the metavariable location in all cases except these two:

• The metavariable is an element of undelimited sequence $($tt)*. These are typically used for passing larger amounts of code, and tokens in that code usually combine with each other and not with tokens outside of the sequence.
• The metavariable span comes from a different crate, then we prefer the more local span.

FIXME: Find a way to keep both original and metavariable spans for all tokens without regressing compilation time too much. Several experiments for adding such spans were made in the past (PR #95580, #118517, #118671) and all showed some regressions.