proc-macro span syntax context and hygiene is underspecified and underdocumented

[jieyouxu]

zulip thread: https://rust-lang.zulipchat.com/#narrow/channel/213817-t-lang/topic/proc-macro.20span.20syntax.20context.20docs.20and.20best.20practices

Are there any clear docs or guidance about proc-macro span syntax context and hygiene? I'm asking because I've noticed that rustc lints, diagnostics, also clippy lints, all run into issues where we don't want to lint on or make suggestions on code that are generated by proc-macros, but Span::from_expansion returns false for proc-macro-generated spans that naively forwards user spans without adding distinguishable syntax context.

The best explanation about proc-macro span syntax context and hygiene I can find atm is the The Little Book of Rust Macros by @Veykril. AFAICT The reference on proc-macro span syntax context and hygiene is quite terse: https://doc.rust-lang.org/reference/procedural-macros.html?highlight=hygiene#procedural-macro-hygiene.

This causes issues where crate authors who write proc-macros use

e.g. m!(t) and the span of t is used when generating code via .set_span/quote_spanned!/etc.

Example issue I ran into when trying to implement unit_bindings: #112380 (comment) (I think I now know the fix for Rocket isn't exactly reasoned correctly but happened to add sufficient Syntax Context to suppress the lint)
Example clippy issue: rust-lang/rust-clippy#13458

From the perspective of rustc and clippy, technically it's "not our fault" because the user provided a span that has no distinguishing syntax context, but from the perspective of the user it's very confusing. It does not help rustc/clippy maintainers nor does it help users.

Zulip thread: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler/topic/proc-macro.20span.20hygiene

I don't know who's maintaining proc-macro or who has purview over the proc-macro API, I thought it was T-libs or T-libs-api but apparently it's not T-libs, and I don't know about T-libs-api. I found @petrochenkov in triagebot.toml, maybe you know more about this?

Tagging this as T-lang because it's part of the Rust language that is quite rough when in comes to interaction between compiler/tooling and user experience.

[traviscross]

cc @eholk @rust-lang/wg-async

[Alexendoo]

Also from a user perspective, it's confusing that diagnostics for expanded code can point at user written code without the note: this warning originates in the macro annotation