From 2411fbaa49f8c10d0fc8bc1a41d39d0df2f73f0f Mon Sep 17 00:00:00 2001 From: Boxy Date: Wed, 18 Jun 2025 15:58:00 +0100 Subject: [PATCH] Link to dev-guide docs --- compiler/rustc_hir/src/hir.rs | 32 ++++++++++++++++++++-------- compiler/rustc_hir/src/intravisit.rs | 22 +++++++++++++++---- 2 files changed, 41 insertions(+), 13 deletions(-) diff --git a/compiler/rustc_hir/src/hir.rs b/compiler/rustc_hir/src/hir.rs index 556f50a85af7..bd59ad613d63 100644 --- a/compiler/rustc_hir/src/hir.rs +++ b/compiler/rustc_hir/src/hir.rs @@ -407,10 +407,8 @@ impl<'hir> PathSegment<'hir> { /// that are [just paths](ConstArgKind::Path) (currently just bare const params) /// versus const args that are literals or have arbitrary computations (e.g., `{ 1 + 3 }`). /// -/// The `Unambig` generic parameter represents whether the position this const is from is -/// unambiguously a const or ambiguous as to whether it is a type or a const. When in an -/// ambiguous context the parameter is instantiated with an uninhabited type making the -/// [`ConstArgKind::Infer`] variant unusable and [`GenericArg::Infer`] is used instead. +/// For an explanation of the `Unambig` generic parameter see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html #[derive(Clone, Copy, Debug, HashStable_Generic)] #[repr(C)] pub struct ConstArg<'hir, Unambig = ()> { @@ -429,6 +427,9 @@ impl<'hir> ConstArg<'hir, AmbigArg> { /// In practice this may mean overriding the [`Visitor::visit_infer`][visit_infer] method on hir visitors, or /// specifically matching on [`GenericArg::Infer`] when handling generic arguments. /// + /// For an explanation of what it means for a const arg to be ambig or unambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html + /// /// [visit_infer]: [rustc_hir::intravisit::Visitor::visit_infer] pub fn as_unambig_ct(&self) -> &ConstArg<'hir> { // SAFETY: `ConstArg` is `repr(C)` and `ConstArgKind` is marked `repr(u8)` so that the @@ -444,6 +445,9 @@ impl<'hir> ConstArg<'hir> { /// /// Functions accepting ambiguous consts will not handle the [`ConstArgKind::Infer`] variant, if /// infer consts are relevant to you then care should be taken to handle them separately. + /// + /// For an explanation of what it means for a const arg to be ambig or unambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub fn try_as_ambig_ct(&self) -> Option<&ConstArg<'hir, AmbigArg>> { if let ConstArgKind::Infer(_, ()) = self.kind { return None; @@ -475,6 +479,9 @@ impl<'hir, Unambig> ConstArg<'hir, Unambig> { } /// See [`ConstArg`]. +/// +/// For an explanation of the `Unambig` generic parameter see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html #[derive(Clone, Copy, Debug, HashStable_Generic)] #[repr(u8, C)] pub enum ConstArgKind<'hir, Unambig = ()> { @@ -3302,10 +3309,8 @@ pub enum AmbigArg {} #[repr(C)] /// Represents a type in the `HIR`. /// -/// The `Unambig` generic parameter represents whether the position this type is from is -/// unambiguously a type or ambiguous as to whether it is a type or a const. When in an -/// ambiguous context the parameter is instantiated with an uninhabited type making the -/// [`TyKind::Infer`] variant unusable and [`GenericArg::Infer`] is used instead. +/// For an explanation of the `Unambig` generic parameter see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub struct Ty<'hir, Unambig = ()> { #[stable_hasher(ignore)] pub hir_id: HirId, @@ -3323,6 +3328,9 @@ impl<'hir> Ty<'hir, AmbigArg> { /// In practice this may mean overriding the [`Visitor::visit_infer`][visit_infer] method on hir visitors, or /// specifically matching on [`GenericArg::Infer`] when handling generic arguments. /// + /// For an explanation of what it means for a type to be ambig or unambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html + /// /// [visit_infer]: [rustc_hir::intravisit::Visitor::visit_infer] pub fn as_unambig_ty(&self) -> &Ty<'hir> { // SAFETY: `Ty` is `repr(C)` and `TyKind` is marked `repr(u8)` so that the layout is @@ -3338,6 +3346,9 @@ impl<'hir> Ty<'hir> { /// /// Functions accepting ambiguous types will not handle the [`TyKind::Infer`] variant, if /// infer types are relevant to you then care should be taken to handle them separately. + /// + /// For an explanation of what it means for a type to be ambig or unambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub fn try_as_ambig_ty(&self) -> Option<&Ty<'hir, AmbigArg>> { if let TyKind::Infer(()) = self.kind { return None; @@ -3640,9 +3651,12 @@ pub enum InferDelegationKind { } /// The various kinds of types recognized by the compiler. -#[derive(Debug, Clone, Copy, HashStable_Generic)] +/// +/// For an explanation of the `Unambig` generic parameter see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html // SAFETY: `repr(u8)` is required so that `TyKind<()>` and `TyKind` are layout compatible #[repr(u8, C)] +#[derive(Debug, Clone, Copy, HashStable_Generic)] pub enum TyKind<'hir, Unambig = ()> { /// Actual type should be inherited from `DefId` signature InferDelegation(DefId, InferDelegationKind), diff --git a/compiler/rustc_hir/src/intravisit.rs b/compiler/rustc_hir/src/intravisit.rs index cb971bedecd2..95fee05a71b9 100644 --- a/compiler/rustc_hir/src/intravisit.rs +++ b/compiler/rustc_hir/src/intravisit.rs @@ -364,8 +364,8 @@ pub trait Visitor<'v>: Sized { /// All types are treated as ambiguous types for the purposes of hir visiting in /// order to ensure that visitors can handle infer vars without it being too error-prone. /// - /// See the doc comments on [`Ty`] for an explanation of what it means for a type to be - /// ambiguous. + /// For an explanation of what it means for a type to be ambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html /// /// The [`Visitor::visit_infer`] method should be overridden in order to handle infer vars. fn visit_ty(&mut self, t: &'v Ty<'v, AmbigArg>) -> Self::Result { @@ -375,8 +375,8 @@ pub trait Visitor<'v>: Sized { /// All consts are treated as ambiguous consts for the purposes of hir visiting in /// order to ensure that visitors can handle infer vars without it being too error-prone. /// - /// See the doc comments on [`ConstArg`] for an explanation of what it means for a const to be - /// ambiguous. + /// For an explanation of what it means for a const arg to be ambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html /// /// The [`Visitor::visit_infer`] method should be overridden in order to handle infer vars. fn visit_const_arg(&mut self, c: &'v ConstArg<'v, AmbigArg>) -> Self::Result { @@ -516,6 +516,9 @@ pub trait VisitorExt<'v>: Visitor<'v> { /// /// Named `visit_ty_unambig` instead of `visit_unambig_ty` to aid in discovery /// by IDes when `v.visit_ty` is written. + /// + /// For an explanation of what it means for a type to be unambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html fn visit_ty_unambig(&mut self, t: &'v Ty<'v>) -> Self::Result { walk_unambig_ty(self, t) } @@ -524,6 +527,9 @@ pub trait VisitorExt<'v>: Visitor<'v> { /// /// Named `visit_const_arg_unambig` instead of `visit_unambig_const_arg` to aid in /// discovery by IDes when `v.visit_const_arg` is written. + /// + /// For an explanation of what it means for a const arg to be unambig, see the dev-guide: + /// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html fn visit_const_arg_unambig(&mut self, c: &'v ConstArg<'v>) -> Self::Result { walk_unambig_const_arg(self, c) } @@ -975,6 +981,8 @@ pub fn walk_generic_arg<'v, V: Visitor<'v>>( } } +/// For an explanation of what it means for a type to be unambig, see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub fn walk_unambig_ty<'v, V: Visitor<'v>>(visitor: &mut V, typ: &'v Ty<'v>) -> V::Result { match typ.try_as_ambig_ty() { Some(ambig_ty) => visitor.visit_ty(ambig_ty), @@ -985,6 +993,8 @@ pub fn walk_unambig_ty<'v, V: Visitor<'v>>(visitor: &mut V, typ: &'v Ty<'v>) -> } } +/// For an explanation of what it means for a type to be ambig, see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub fn walk_ty<'v, V: Visitor<'v>>(visitor: &mut V, typ: &'v Ty<'v, AmbigArg>) -> V::Result { let Ty { hir_id, span: _, kind } = typ; try_visit!(visitor.visit_id(*hir_id)); @@ -1037,6 +1047,8 @@ pub fn walk_ty<'v, V: Visitor<'v>>(visitor: &mut V, typ: &'v Ty<'v, AmbigArg>) - V::Result::output() } +/// For an explanation of what it means for a const arg to be unambig, see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub fn walk_unambig_const_arg<'v, V: Visitor<'v>>( visitor: &mut V, const_arg: &'v ConstArg<'v>, @@ -1050,6 +1062,8 @@ pub fn walk_unambig_const_arg<'v, V: Visitor<'v>>( } } +/// For an explanation of what it means for a const arg to be ambig, see the dev-guide: +/// https://rustc-dev-guide.rust-lang.org/hir/ambig-unambig-ty-and-consts.html pub fn walk_const_arg<'v, V: Visitor<'v>>( visitor: &mut V, const_arg: &'v ConstArg<'v, AmbigArg>,