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_implicit_sized_bound`
+        // 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

@@ -14,7 +14,8 @@ use crate::bounds::Bounds;
 use crate::errors;
 
 impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
-    /// Sets `implicitly_sized` to true on `Bounds` if necessary
+    /// Add a `Sized` bound to the `bounds` unless the HIR bounds contain any of
+    /// `Sized`, `?Sized` or `!Sized`.
     pub(crate) fn add_implicit_sized_bound(
         &self,
         bounds: &mut Bounds<'tcx>,
@@ -98,21 +99,21 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         }
     }
 
-    /// This helper takes a *converted* parameter type (`param_ty`)
-    /// and an *unconverted* list of bounds:
+    /// Lower HIR bounds into `bounds` given the self type `param_ty`.
     ///
-    /// ```text
-    /// fn foo<T: Debug>
-    ///        ^  ^^^^^ `ast_bounds` parameter, in HIR form
+    /// ### Example
+    ///
+    /// ```ignore (illustrative)
+    /// fn foo<T: Debug>() { }
+    ///        ^  ^^^^^ `ast_bounds`, in HIR form
     ///        |
     ///        `param_ty`, in ty form
     /// ```
     ///
-    /// It adds these `ast_bounds` into the `bounds` structure.
+    /// ### A Note on Binders
     ///
-    /// **A note on binders:** there is an implied binder around
-    /// `param_ty` and `ast_bounds`. See `instantiate_poly_trait_ref`
-    /// for more details.
+    /// There is an implied binder around `param_ty` and `ast_bounds`.
+    /// See `lower_poly_trait_ref` for more details.
     #[instrument(level = "debug", skip(self, ast_bounds, bounds))]
     pub(crate) fn lower_bounds<'hir, I: Iterator<Item = &'hir hir::GenericBound<'tcx>>>(
         &self,
@@ -168,22 +169,18 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         }
     }
 
-    /// Translates a list of bounds from the HIR into the `Bounds` data structure.
-    /// The self-type for the bounds is given by `param_ty`.
+    // FIXME(astconv-no-mo): Currently this has the same docs as `lower_bounds`.
+    /// Lower HIR bounds into `bounds` given the self type `param_ty`.
     ///
-    /// Example:
+    /// ### Example
     ///
     /// ```ignore (illustrative)
     /// fn foo<T: Bar + Baz>() { }
     /// //     ^  ^^^^^^^^^ ast_bounds
     /// //     param_ty
     /// ```
-    ///
-    /// The `sized_by_default` parameter indicates if, in this context, the `param_ty` should be
-    /// considered `Sized` unless there is an explicit `?Sized` bound. This would be true in the
-    /// example above, but is not true in supertrait listings like `trait Foo: Bar + Baz`.
-    ///
-    /// `span` should be the declaration size of the parameter.
+    // FIXME(astconv-no-more): This should renamed to make it clear how it differs from `lower_bounds`
+    //                         Maybe `lower_mono_bounds` (as in no bound vars)?
     pub(crate) fn compute_bounds(
         &self,
         param_ty: Ty<'tcx>,
@@ -225,12 +222,14 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         bounds
     }
 
-    /// Given an HIR binding like `Item = Foo` or `Item: Foo`, pushes the corresponding predicates
-    /// onto `bounds`.
+    // FIXME(astconv-no-mo): Expand these docs!
+    /// Lower an associated item binding from HIR into `bounds`.
+    ///
+    /// ### A Note on Binders
     ///
-    /// **A note on binders:** given something like `T: for<'a> Iterator<Item = &'a u32>`, the
-    /// `trait_ref` here will be `for<'a> T: Iterator`. The `binding` data however is from *inside*
-    /// the binder (e.g., `&'a u32`) and hence may reference bound regions.
+    /// Given something like `T: for<'a> Iterator<Item = &'a u32>`, the `trait_ref` here will be
+    /// `for<'a> T: Iterator`. The `binding` data however is from *inside* the binder (e.g., `&'a u32`)
+    /// and hence may reference bound regions.
     #[instrument(level = "debug", skip(self, bounds, speculative, dup_bindings, path_span))]
     pub(super) fn lower_assoc_item_binding(
         &self,
@@ -243,6 +242,7 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         path_span: Span,
         only_self_bounds: OnlySelfBounds,
     ) -> Result<(), ErrorGuaranteed> {
+        // FIXME(astconv-no-mo): Update this comment / move it someplace better.
         // Given something like `U: SomeTrait<T = X>`, we want to produce a
         // predicate like `<U as SomeTrait>::T = X`. This is somewhat
         // subtle in the event that `T` is defined in a supertrait of
@@ -436,6 +436,8 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
                     span: binding.span,
                 }));
             }
+            // Lower an equality constraint like `Item = u32` as found in HIR bound `T: Iterator<Item = u32>`
+            // to a projection predicate: `<T as Iterator>::Item = u32`.
             hir::TypeBindingKind::Equality { term } => {
                 let term = match term {
                     hir::Term::Ty(ty) => self.lower_ty(ty).into(),
@@ -479,29 +481,21 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
                     );
                 }
 
-                // "Desugar" a constraint like `T: Iterator<Item = u32>` this to
-                // the "projection predicate" for:
-                //
-                // `<T as Iterator>::Item = u32`
                 bounds.push_projection_bound(
                     tcx,
                     projection_ty
                         .map_bound(|projection_ty| ty::ProjectionPredicate { projection_ty, term }),
                     binding.span,
                 );
             }
+            // Lower a constraint like `Item: Debug` as found in HIR bound `T: Iterator<Item: Debug>`
+            // to a bound involving a projection: `<T as Iterator>::Item: Debug`.
             hir::TypeBindingKind::Constraint { bounds: ast_bounds } => {
-                // "Desugar" a constraint like `T: Iterator<Item: Debug>` to
-                //
-                // `<T as Iterator>::Item: Debug`
-                //
-                // Calling `skip_binder` is okay, because `add_bounds` expects the `param_ty`
-                // parameter to have a skipped binder.
-                //
-                // NOTE: If `only_self_bounds` is true, do NOT expand this associated
-                // type bound into a trait predicate, since we only want to add predicates
-                // for the `Self` type.
+                // NOTE: If `only_self_bounds` is true, do NOT expand this associated type bound into
+                // a trait predicate, since we only want to add predicates for the `Self` type.
                 if !only_self_bounds.0 {
+                    // Calling `skip_binder` is okay, because `lower_bounds` expects the `param_ty`
+                    // parameter to have a skipped binder.
                     let param_ty = Ty::new_alias(tcx, ty::Projection, projection_ty.skip_binder());
                     self.lower_bounds(
                         param_ty,