Some hygiene doc improvements

[camsteffen]

Improve some doc comments around SyntaxContext, outer_expn and friends.

Based on discussion at #146100.

r? petrochenkov

[camsteffen]

There's a couple things I'm still unclear on if you don't mind explaining.

In the dev guide section on "The Call-site Hierarchy", it says

macro bar($i: ident) { $i }
macro foo($i: ident) { $i }

foo!(bar!(baz));

For the baz AST node in the final output, the expansion-order hierarchy is ROOT -> id(foo) -> id(bar) -> baz, while the call-site hierarchy is ROOT -> baz.

But I did some testing and I think baz would just have the root SyntaxContext? So I don't know what to make of this. Also the example doesn't compile and I assume it should be macro foo($($t:tt)*)....

If I'm right about the above, is the call-site and the expansion-order hierarchies actually different? I can't think of an example where they would diverge.

I noticed when we mark spans for desugaring, we just use the root ExpnId for parent here. That seems like a potential bug.

[petrochenkov]

But I did some testing and I think baz would just have the root SyntaxContext?

Yes, baz will have root context, because the token is not produced by any macro.

Also the example doesn't compile and I assume it should be macro foo($($t:tt)*)...

Yeah, there's a mistake there, it should be $($t:tt)*.

If I'm right about the above, is the call-site and the expansion-order hierarchies actually different? I can't think of an example where they would diverge.

Yes, they are different, and the example is supposed to demonstrate exactly that.
To get baz as a part of AST (not as a token) you need to expand foo and then bar, that's the expansion order hierarchy.
But the call site is still root, because it's token-oriented rather than AST-oriented.

I noticed when we mark spans for desugaring, we just use the root ExpnId for parent. That seems like a potential bug.

Using the root SyntaxContext (not ExpnId) as SyntaxContextData::parent for a desugaring is correct, because the "definition" of that desugaring does not come from any other macro, it's a built-in.

[camsteffen]

This name is a bit unfortunate since it does not use ExpnData::parent.

[camsteffen]

@rustbot ready

[camsteffen]

Yes, baz will have root context, because the token is not produced by any macro.

I did some more testing and it seems the SyntaxContext for a Path depends on where the referenced thing is defined...which makes a a of sense.

Anyways, I think I've done enough damage here for now. I really appreciate your help with this.