Auto merge of #112198 - compiler-errors:rollup-o2xe4of, r=compiler-errors

Rollup of 7 pull requests

Successful merges:

 - #111670 (Require that const param tys implement `ConstParamTy`)
 - #111914 (CFI: Fix cfi with async: transform_ty: unexpected GeneratorWitness(Bi…)
 - #112030 (Migrate `item_trait_alias` to Askama)
 - #112150 (Support 128-bit atomics on all x86_64 Apple targets)
 - #112174 (Fix broken link)
 - #112190 (Improve comments on `TyCtxt` and `GlobalCtxt`.)
 - #112193 (Check tuple elements are `Sized` in `offset_of`)

Failed merges:

 - #112071 (Group rfcs tests)

r? `@ghost`
`@rustbot` modify labels: rollup

1 files changed, 12 insertions, 0 deletions

diff --git a/compiler/rustc_middle/src/ty/context.rs b/compiler/rustc_middle/src/ty/context.rs
index b05e791211d..673d09cddf4 100644
--- a/compiler/rustc_middle/src/ty/context.rs
+++ b/compiler/rustc_middle/src/ty/context.rs
@@ -478,6 +478,17 @@ impl<'tcx> TyCtxtFeed<'tcx, LocalDefId> {
 /// [rustc dev guide] for more details.
 ///
 /// [rustc dev guide]: https://rustc-dev-guide.rust-lang.org/ty.html
+///
+/// An implementation detail: `TyCtxt` is a wrapper type for [GlobalCtxt],
+/// which is the struct that actually holds all the data. `TyCtxt` derefs to
+/// `GlobalCtxt`, and in practice `TyCtxt` is passed around everywhere, and all
+/// operations are done via `TyCtxt`. A `TyCtxt` is obtained for a `GlobalCtxt`
+/// by calling `enter` with a closure `f`. That function creates both the
+/// `TyCtxt`, and an `ImplicitCtxt` around it that is put into TLS. Within `f`:
+/// - The `ImplicitCtxt` is available implicitly via TLS.
+/// - The `TyCtxt` is available explicitly via the `tcx` parameter, and also
+///   implicitly within the `ImplicitCtxt`. Explicit access is preferred when
+///   possible.
 #[derive(Copy, Clone)]
 #[rustc_diagnostic_item = "TyCtxt"]
 #[rustc_pass_by_value]
@@ -493,6 +504,7 @@ impl<'tcx> Deref for TyCtxt<'tcx> {
     }
 }
 
+/// See [TyCtxt] for details about this type.
 pub struct GlobalCtxt<'tcx> {
     pub arena: &'tcx WorkerLocal<Arena<'tcx>>,
     pub hir_arena: &'tcx WorkerLocal<hir::Arena<'tcx>>,