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

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: https://github.com/rust-lang/rust/pull/112380#issuecomment-1657124150 (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: https://github.com/rust-lang/rust-clippy/issues/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.

Start with the Rust Reference's procedural-macro hygiene section and compare it with The Little Book of Rust Macros, then review the linked Zulip discussions and the unit_bindings and Clippy examples. Done means documenting proc-macro span syntax context and hygiene clearly enough to explain forwarded user spans, lint behavior, and recommended practices.