Update (doc) comments

Author: fmease

compiler/rustc_ast/src/visit.rs

@@ -466,7 +466,7 @@ pub fn walk_use_tree<'a, V: Visitor<'a>>(visitor: &mut V, use_tree: &'a UseTree,
     visitor.visit_path(&use_tree.prefix, id);
     match &use_tree.kind {
         UseTreeKind::Simple(rename) => {
-            // The extra IDs are handled during HIR lowering.
+            // The extra IDs are handled during AST lowering.
             if let &Some(rename) = rename {
                 visitor.visit_ident(rename);
             }

compiler/rustc_ast_lowering/src/delegation.rs

@@ -29,11 +29,12 @@
 //! item id (`item_id`) in case of impl trait or path resolution id (`path_id`) otherwise.
 //!
 //! Since we do not have a proper way to obtain function type information by path resolution
-//! in AST, we mark each function parameter type as `InferDelegation` and inherit it in `AstConv`.
+//! in AST, we mark each function parameter type as `InferDelegation` and inherit it during
+//! HIR ty lowering.
 //!
 //! Similarly generics, predicates and header are set to the "default" values.
 //! In case of discrepancy with callee function the `NotSupportedDelegation` error will
-//! also be emitted in `AstConv`.
+//! also be emitted during HIR ty lowering.
 
 use crate::{ImplTraitPosition, ResolverAstLoweringExt};
 
@@ -133,7 +134,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
     ) -> &'hir hir::FnDecl<'hir> {
         let args_count = if let Some(local_sig_id) = sig_id.as_local() {
             // Map may be filled incorrectly due to recursive delegation.
-            // Error will be emmited later in astconv.
+            // Error will be emitted later during HIR ty lowering.
             self.resolver.fn_parameter_counts.get(&local_sig_id).cloned().unwrap_or_default()
         } else {
             self.tcx.fn_arg_names(sig_id).len()

compiler/rustc_ast_lowering/src/item.rs

@@ -1416,8 +1416,8 @@ impl<'hir> LoweringContext<'_, 'hir> {
         // Error if `?Trait` bounds in where clauses don't refer directly to type parameters.
         // Note: we used to clone these bounds directly onto the type parameter (and avoid lowering
         // these into hir when we lower thee where clauses), but this makes it quite difficult to
-        // keep track of the Span info. Now, `add_implicitly_sized` in `AstConv` checks both param bounds and
-        // where clauses for `?Sized`.
+        // keep track of the Span info. Now, `<dyn HirTyLowerer>::add_implicitly_sized` checks both
+        // param bounds and where clauses for `?Sized`.
         for pred in &generics.where_clause.predicates {
             let WherePredicate::BoundPredicate(bound_pred) = pred else {
                 continue;

compiler/rustc_borrowck/src/diagnostics/region_name.rs

@@ -626,7 +626,7 @@ impl<'tcx> MirBorrowckCtxt<'_, 'tcx> {
                     | GenericArgKind::Const(_),
                     _,
                 ) => {
-                    // HIR lowering sometimes doesn't catch this in erroneous
+                    // HIR ty lowering sometimes doesn't catch this in erroneous
                     // programs, so we need to use span_delayed_bug here. See #82126.
                     self.dcx().span_delayed_bug(
                         hir_arg.span(),

compiler/rustc_hir/src/hir.rs

@@ -1845,7 +1845,7 @@ pub enum ExprKind<'hir> {
     /// Wraps the expression in a terminating scope.
     /// This makes it semantically equivalent to `{ let _t = expr; _t }`.
     ///
-    /// This construct only exists to tweak the drop order in HIR lowering.
+    /// This construct only exists to tweak the drop order in AST lowering.
     /// An example of that is the desugaring of `for` loops.
     DropTemps(&'hir Expr<'hir>),
     /// A `let $pat = $expr` expression.
@@ -2278,7 +2278,7 @@ pub enum ImplItemKind<'hir> {
 /// Bind a type to an associated type (i.e., `A = Foo`).
 ///
 /// Bindings like `A: Debug` are represented as a special type `A =
-/// $::Debug` that is understood by the astconv code.
+/// $::Debug` that is understood by the HIR ty lowering code.
 ///
 /// FIXME(alexreg): why have a separate type for the binding case,
 /// wouldn't it be better to make the `ty` field an enum like the

compiler/rustc_hir_analysis/src/astconv/bounds.rs

@@ -16,7 +16,8 @@ use crate::bounds::Bounds;
 use crate::errors;
 
 impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
-    /// Sets `implicitly_sized` to true on `Bounds` if necessary
+    /// Adds a `Sized` bound to the list of `bounds` unless the HIR bounds contain any of
+    /// `Sized`, `?Sized` or `!Sized`.
     pub(crate) fn add_implicitly_sized(
         &self,
         bounds: &mut Bounds<'tcx>,
@@ -100,8 +101,7 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         }
     }
 
-    /// This helper takes a *converted* parameter type (`param_ty`)
-    /// and an *unconverted* list of bounds:
+    /// Lower bounds into `bounds`.
     ///
     /// ```text
     /// fn foo<T: Debug>
@@ -110,8 +110,6 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
     ///        `param_ty`, in ty form
     /// ```
     ///
-    /// It adds these `ast_bounds` into the `bounds` structure.
-    ///
     /// **A note on binders:** there is an implied binder around
     /// `param_ty` and `ast_bounds`. See `instantiate_poly_trait_ref`
     /// for more details.

compiler/rustc_hir_analysis/src/astconv/mod.rs

@@ -1,6 +1,11 @@
-//! Conversion from AST representation of types to the `ty.rs` representation.
-//! The main routine here is `ast_ty_to_ty()`; each use is parameterized by an
-//! instance of `AstConv`.
+//! HIR ty lowering: Lowers type-system entities from HIR to `rustc_middle::ty` representation.
+//!
+//! Not to be confused with *AST lowering* which lowers AST constructs to HIR ones.
+//!
+//! The main routine here is `<dyn HirTyLowerer>::lower_ty()`. The other routines
+//! are defined on `dyn HirTyLowerer` (see [`HirTyLowerer`]).
+//!
+//! This module used to be called `astconv`.
 
 mod bounds;
 mod errors;
@@ -69,6 +74,9 @@ pub enum PredicateFilter {
     SelfAndAssociatedTypeBounds,
 }
 
+/// A context which can lower type-system entities from [HIR][hir] to [`rustc_middle::ty`] representation.
+///
+/// This trait used to be called `AstConv`.
 pub trait HirTyLowerer<'tcx> {
     fn tcx(&self) -> TyCtxt<'tcx>;
 
@@ -127,6 +135,7 @@ pub trait HirTyLowerer<'tcx> {
     ) -> Ty<'tcx>;
 
     /// Returns `AdtDef` if `ty` is an ADT.
+    ///
     /// Note that `ty` might be a projection type that needs normalization.
     /// This used to get the enum variants in scope of the type.
     /// For example, `Self::A` could refer to an associated type
@@ -214,6 +223,7 @@ pub struct GenericArgCountResult {
     pub correct: Result<(), GenericArgCountMismatch>,
 }
 
+/// A context which can lower HIR's [`GenericArg`] to `rustc_middle`'s [`ty::GenericArg`].
 pub trait GenericArgsLowerer<'a, 'tcx> {
     fn args_for_def_id(&mut self, def_id: DefId) -> (Option<&'a GenericArgs<'tcx>>, bool);
 
@@ -309,7 +319,6 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         if let Some(b) = item_segment.args().bindings.first() {
             prohibit_assoc_ty_binding(self.tcx(), b.span, Some((item_segment, span)));
         }
-
         args
     }
 
@@ -593,7 +602,7 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         &self,
         generic_args: &'a hir::GenericArgs<'tcx>,
     ) -> Vec<LoweredBinding<'a, 'tcx>> {
-        // Convert associated-type bindings or constraints into a separate vector.
+        // Lower associated-type bindings or constraints into a separate vector.
         // Example: Given this:
         //
         //     T: Iterator<Item = u32>
@@ -655,11 +664,9 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
             None,
             ty::BoundConstness::NotConst,
         );
-
         if let Some(b) = item_segment.args().bindings.first() {
             prohibit_assoc_ty_binding(self.tcx(), b.span, Some((item_segment, span)));
         }
-
         args
     }
 
@@ -786,7 +793,7 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         self_ty: Ty<'tcx>,
         trait_segment: &hir::PathSegment<'tcx>,
         is_impl: bool,
-        // FIXME(effects) move all host param things in astconv to hir lowering
+        // FIXME(effects): Move all host param things in HIR ty lowering to AST lowering.
         constness: ty::BoundConstness,
     ) -> ty::TraitRef<'tcx> {
         let (generic_args, _) = self.lower_args_for_trait_ref(
@@ -973,10 +980,11 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         reported
     }
 
-    // Search for a bound on a type parameter which includes the associated item
-    // given by `assoc_name`. `ty_param_def_id` is the `DefId` of the type parameter
-    // This function will fail if there are no suitable bounds or there is
-    // any ambiguity.
+    /// Search for a bound on a type parameter which includes the associated item given by `assoc_name`.
+    ///
+    /// `ty_param_def_id` is the `DefId` of the type parameter.
+    /// This function will fail if there are no suitable bounds or there is any ambiguity.
+    #[instrument(level = "debug", skip(self), ret)]
     fn find_bound_for_assoc_item(
         &self,
         ty_param_def_id: LocalDefId,
@@ -1015,8 +1023,8 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         )
     }
 
-    // Checks that `bounds` contains exactly one element and reports appropriate
-    // errors otherwise.
+    // FIXME(fmease): This also *resolves* the bound. Update docs!
+    /// Checks that `bounds` contains exactly one element and reports appropriate errors otherwise.
     #[instrument(level = "debug", skip(self, all_candidates, ty_param_name, binding), ret)]
     fn one_bound_for_assoc_item<I>(
         &self,
@@ -1133,12 +1141,14 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         Ok(bound)
     }
 
-    // Create a type from a path to an associated type or to an enum variant.
-    // For a path `A::B::C::D`, `qself_ty` and `qself_def` are the type and def for `A::B::C`
-    // and item_segment is the path segment for `D`. We return a type and a def for
-    // the whole path.
-    // Will fail except for `T::A` and `Self::A`; i.e., if `qself_ty`/`qself_def` are not a type
-    // parameter or `Self`.
+    /// Create a type from a path to an associated type or to an enum variant.
+    ///
+    /// For a path `A::B::C::D`, `qself_ty` and `qself` are the type and def for `A::B::C`
+    /// and item_segment is the path segment for `D`. We return a type and a def for
+    /// the whole path.
+    ///
+    /// Will fail except for `T::A` and `Self::A`; i.e., if `qself_ty`/`qself` are not a type
+    /// parameter or `Self`.
     // NOTE: When this function starts resolving `Trait::AssocTy` successfully
     // it should also start reporting the `BARE_TRAIT_OBJECTS` lint.
     #[instrument(level = "debug", skip(self, hir_ref_id, span, qself, assoc_segment), fields(assoc_ident=?assoc_segment.ident), ret)]
@@ -1436,8 +1446,9 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         // Don't attempt to look up inherent associated types when the feature is not enabled.
         // Theoretically it'd be fine to do so since we feature-gate their definition site.
         // However, due to current limitations of the implementation (caused by us performing
-        // selection in AstConv), IATs can lead to cycle errors (#108491, #110106) which mask the
-        // feature-gate error, needlessly confusing users that use IATs by accident (#113265).
+        // selection during HIR ty lowering instead of in the trait solver), IATs can lead to cycle
+        // errors (#108491, #110106) which mask the feature-gate error, needlessly confusing users
+        // who use IATs by accident (#113265).
         if !tcx.features().inherent_associated_types {
             return Ok(None);
         }
@@ -2013,7 +2024,7 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         path_segs
     }
 
-    /// Check a type `Path` and convert it to a `Ty`.
+    /// Check a type `Path` and lower it to a `Ty`.
     pub fn lower_res_to_ty(
         &self,
         opt_self_ty: Option<Ty<'tcx>>,
@@ -2053,7 +2064,7 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
                 self.lower_path_to_ty(span, did, path.segments.last().unwrap())
             }
             Res::Def(kind @ DefKind::Variant, def_id) if permit_variants => {
-                // Convert "variant type" as if it were a real type.
+                // Lower "variant type" as if it were a real type.
                 // The resulting `Ty` is type of the variant's enum for now.
                 assert_eq!(opt_self_ty, None);
 
@@ -2254,8 +2265,8 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         }
     }
 
-    // Converts a hir id corresponding to a type parameter to
-    // a early-bound `ty::Param` or late-bound `ty::Bound`.
+    /// Lower a `HirId` corresponding to a type parameter to an early-bound
+    /// [`ty::Param`] or late-bound [`ty::Bound`].
     pub(crate) fn lower_type_param(&self, hir_id: hir::HirId) -> Ty<'tcx> {
         let tcx = self.tcx();
         match tcx.named_bound_var(hir_id) {
@@ -2279,8 +2290,8 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         }
     }
 
-    // Converts a hir id corresponding to a const parameter to
-    // a early-bound `ConstKind::Param` or late-bound `ConstKind::Bound`.
+    /// Lower a `HirId` corresponding to a const parameter to an early-bound
+    /// [`ty::ConstKind::Param`] or late-bound [`ty::ConstKind::Bound`].
     pub(crate) fn lower_const_param(&self, hir_id: hir::HirId, param_ty: Ty<'tcx>) -> Const<'tcx> {
         let tcx = self.tcx();
         match tcx.named_bound_var(hir_id) {
@@ -2421,8 +2432,10 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
         }
     }
 
-    /// Turns a `hir::Ty` into a `Ty`. For diagnostics' purposes we keep track of whether trait
-    /// objects are borrowed like `&dyn Trait` to avoid emitting redundant errors.
+    /// Lowers a [`hir::Ty`] to a [`Ty`].
+    ///
+    /// For diagnostics' purposes we keep track of whether trait objects are
+    /// borrowed like `&dyn Trait` to avoid emitting redundant errors.
     #[instrument(level = "debug", skip(self), ret)]
     fn lower_ty_inner(&self, ast_ty: &hir::Ty<'tcx>, borrowed: bool, in_path: bool) -> Ty<'tcx> {
         let tcx = self.tcx();
@@ -2822,7 +2835,9 @@ impl<'o, 'tcx> dyn HirTyLowerer<'tcx> + 'o {
     }
 
     /// Given the bounds on an object, determines what single region bound (if any) we can
-    /// use to summarize this type. The basic idea is that we will use the bound the user
+    /// use to summarize this type.
+    ///
+    /// The basic idea is that we will use the bound the user
     /// provided, if they provided one, and otherwise search the supertypes of trait bounds
     /// for region bounds. It may be that we can derive no bound at all, in which case
     /// we return `None`.

compiler/rustc_hir_analysis/src/bounds.rs

@@ -1,5 +1,5 @@
-//! Bounds are restrictions applied to some types after they've been converted into the
-//! `ty` form from the HIR.
+//! Bounds are restrictions applied to some types after they've been lowered from the HIR to the
+//! [`rustc_middle::ty`] form.
 
 use rustc_hir::LangItem;
 use rustc_middle::ty::{self, ToPredicate, Ty, TyCtxt};

compiler/rustc_hir_analysis/src/check/compare_impl_item.rs

@@ -745,7 +745,7 @@ pub(super) fn collect_return_position_impl_trait_in_trait_tys<'tcx>(
 
     // We may not collect all RPITITs that we see in the HIR for a trait signature
     // because an RPITIT was located within a missing item. Like if we have a sig
-    // returning `-> Missing<impl Sized>`, that gets converted to `-> [type error]`,
+    // returning `-> Missing<impl Sized>`, that gets converted to `-> {type error}`,
     // and when walking through the signature we end up never collecting the def id
     // of the `impl Sized`. Insert that here, so we don't ICE later.
     for assoc_item in tcx.associated_types_for_impl_traits_in_associated_fn(trait_m.def_id) {

compiler/rustc_hir_analysis/src/check/region.rs

@@ -760,7 +760,7 @@ impl<'tcx> RegionResolutionVisitor<'tcx> {
 
     fn enter_node_scope_with_dtor(&mut self, id: hir::ItemLocalId) {
         // If node was previously marked as a terminating scope during the
-        // recursive visit of its parent node in the AST, then we need to
+        // recursive visit of its parent node in the HIR, then we need to
         // account for the destruction scope representing the scope of
         // the destructors that run immediately after it completes.
         if self.terminating_scopes.contains(&id) {