Some hygiene doc improvements

[camsteffen]

This naming has always confused me. I'm not sure what "outer" is supposed to mean. Zulip thread.

Improve some doc comments around SyntaxContext, outer_expn and friends.

[rustbot]

r? @SparrowLii

rustbot has assigned @SparrowLii.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred to the CTFE machinery

cc @RalfJung, @oli-obk, @lcnr

Some changes occurred in src/tools/clippy

cc @rust-lang/clippy

Some changes occurred in compiler/rustc_ast_lowering/src/format.rs

cc @m-ou-se

The rustc-dev-guide subtree was changed. If this PR only touches the dev guide consider submitting a PR directly to rust-lang/rustc-dev-guide otherwise thank you for updating the dev guide with your changes.

cc @BoxyUwU, @jieyouxu, @Kobzol, @tshepang

Some changes occurred in check-cfg diagnostics

cc @Urgau

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

Some changes occurred in coverage instrumentation.

cc @Zalathar

[fmease]

r? petrochenkov

[petrochenkov]

SyntaxContext potentially consists of many expansions, organized as a "child -> parent" linked list, outer_expn returns only one outermost expansion out of the whole set.
The new naming gives an impression that a span / syntax context only has one expansion.

[camsteffen]

outer_expn returns only one outermost expansion out of the whole set.

Couldn't it also be the innermost or anything in between?

I think I see where you're coming from now. "outer" means "this expansion which might have child expansions". It confused me because I thought it meant "get the parent expansion relative to this expansion". But that is parent_callsite. As a thought experiment, why not call it inner_expn in order to communicate that there could be parent expansions?

The new naming gives an impression that a span / syntax context only has one expansion.

To me it just says "give me the expansion of this span" without making any implications about parent or child expansions.

Anyways, this could just be me.

[petrochenkov]

Couldn't it also be the innermost or anything in between?

You can call it the innermost if you count from the opposite side, but certainly not something in between.
It's id(n) in "Example 1" in https://rustc-dev-guide.rust-lang.org/macro-expansion.html#the-macro-definition-hierarchy.

To me it just says "give me the expansion of this span" without making any implications about parent or child expansions.

A span (or rather SyntaxContext) doesn't have the expansion, a span is a list of expansions, that's the point.
It's different from e.g. parent_callsite stuff which is uniquely determined by ExpnId, SyntaxContext is not uniquely determined by its outer ExpnId as the dev guide explains.

[camsteffen]

I see what happened. I was thinking of SyntaxContext as being an ID for just the outer(?) expansion rather than representing the whole chain. With that shift, all the methods on SyntaxContext make much more sense now.

You can call it the innermost if you count from the opposite side

I think this is part of what stalled my understanding. I think of outer_expn as "go to the innermost expansion". The dev guide even uses the word "innermost" in this way at one point.

I can change this PR to just add some docs. Or what do you think of renaming to last_expn or inner_expn or tail_expn?

[petrochenkov]

Let's just keep the current naming to avoid churn.
Doc improvements are always welcome, though.

[camsteffen]

@rustbot ready

[Zalathar]

This PR has changed enough from its original scope that I would suggest closing it, and creating a new PR for the doc updates (with a link back to this one).

Otherwise, the change ends up being very confusing.

[camsteffen]

Ok, see #146159

[rust-log-analyzer]

The job pr-check-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

   |         +                                                          +

error: could not document `rustc_span`
warning: build failed, waiting for other jobs to finish...
Command `/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo doc --target x86_64-unknown-linux-gnu -Zbinary-dep-depinfo -j 4 -Zroot-dir=/checkout --locked --color always --release --features llvm --manifest-path /checkout/compiler/rustc/Cargo.toml -Zskip-rustdoc-fingerprint --no-deps -Zrustdoc-map -p rustc-main -p rustc_abi -p rustc_arena -p rustc_ast -p rustc_ast_ir -p rustc_ast_lowering -p rustc_ast_passes -p rustc_ast_pretty -p rustc_attr_parsing -p rustc_baked_icu_data -p rustc_borrowck -p rustc_builtin_macros -p rustc_codegen_llvm -p rustc_codegen_ssa -p rustc_const_eval -p rustc_data_structures -p rustc_driver -p rustc_driver_impl -p rustc_error_codes -p rustc_error_messages -p rustc_errors -p rustc_expand -p rustc_feature -p rustc_fluent_macro -p rustc_fs_util -p rustc_graphviz -p rustc_hashes -p rustc_hir -p rustc_hir_analysis -p rustc_hir_id -p rustc_hir_pretty -p rustc_hir_typeck -p rustc_incremental -p rustc_index -p rustc_index_macros -p rustc_infer -p rustc_interface -p rustc_lexer -p rustc_lint -p rustc_lint_defs -p rustc_llvm -p rustc_log -p rustc_macros -p rustc_metadata -p rustc_middle -p rustc_mir_build -p rustc_mir_dataflow -p rustc_mir_transform -p rustc_monomorphize -p rustc_next_trait_solver -p rustc_parse -p rustc_parse_format -p rustc_passes -p rustc_pattern_analysis -p rustc_privacy -p rustc_proc_macro -p rustc_public -p rustc_public_bridge -p rustc_query_impl -p rustc_query_system -p rustc_resolve -p rustc_sanitizers -p rustc_serialize -p rustc_session -p rustc_span -p rustc_symbol_mangling -p rustc_target -p rustc_thread_pool -p rustc_trait_selection -p rustc_traits -p rustc_transmute -p rustc_ty_utils -p rustc_type_ir -p rustc_type_ir_macros [workdir=/checkout]` failed with exit code 101
Created at: src/bootstrap/src/core/build_steps/doc.rs:877:25
Executed at: src/bootstrap/src/core/build_steps/doc.rs:937:26

Command has failed. Rerun with -v to see more details.
Bootstrap failed while executing `doc compiler --stage 1`
Build completed unsuccessfully in 0:01:47
  local time: Wed Sep  3 13:58:57 UTC 2025
  network time: Wed, 03 Sep 2025 13:58:57 GMT
##[error]Process completed with exit code 1.