Update (doc) comments

Several (doc) comments were super outdated or didn't provide enough context.

Some doc comments shoved everything in a single paragraph without respecting
the fact that the first paragraph should be a single sentence because rustdoc
treats these as item descriptions / synopses on module pages.

Author: fmease

compiler/rustc_ast/src/visit.rs

@@ -480,7 +480,7 @@ pub fn walk_use_tree<'a, V: Visitor<'a>>(
     try_visit!(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.
             visit_opt!(visitor, visit_ident, rename);
         }
         UseTreeKind::Glob => {}

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};
 
@@ -129,7 +130,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

@@ -1429,8 +1429,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_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,9 @@ 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` if appropriate.
+    ///
+    /// Doesn't add the bound if the HIR bounds contain any of `Sized`, `?Sized` or `!Sized`.
     pub(crate) fn add_sized_bound(
         &self,
         bounds: &mut Bounds<'tcx>,
@@ -98,21 +100,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`.
+    ///
+    /// ### Example
     ///
-    /// ```text
-    /// fn foo<T: Debug>
-    ///        ^  ^^^^^ `ast_bounds` parameter, in HIR form
-    ///        |
-    ///        `param_ty`, in ty form
+    /// ```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_poly_bounds<'hir, I: Iterator<Item = &'hir hir::GenericBound<'tcx>>>(
         &self,
@@ -168,22 +170,15 @@ 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`.
+    /// 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.
     pub(crate) fn lower_mono_bounds(
         &self,
         param_ty: Ty<'tcx>,
@@ -225,12 +220,14 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         bounds
     }
 
-    /// Given an HIR binding like `Item = Foo` or `Item: Foo`, pushes the corresponding predicates
-    /// onto `bounds`.
+    /// 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,22 +240,6 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
         path_span: Span,
         only_self_bounds: OnlySelfBounds,
     ) -> Result<(), ErrorGuaranteed> {
-        // 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
-        // `SomeTrait`, because in that case we need to upcast.
-        //
-        // That is, consider this case:
-        //
-        // ```
-        // trait SubTrait: SuperTrait<i32> { }
-        // trait SuperTrait<A> { type T; }
-        //
-        // ... B: SubTrait<T = foo> ...
-        // ```
-        //
-        // We want to produce `<B as SuperTrait<i32>>::T == foo`.
-
         let tcx = self.tcx();
 
         let assoc_kind = if binding.gen_args.parenthesized
@@ -271,6 +252,14 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
             ty::AssocKind::Type
         };
 
+        // Given something like `U: Trait<T = X>`, we want to produce a predicate like
+        // `<U as Trait>::T = X`.
+        // This is somewhat subtle in the event that `T` is defined in a supertrait of `Trait`,
+        // because in that case we need to upcast. I.e., we want to produce
+        // `<B as SuperTrait<i32>>::T == X` for `B: SubTrait<T = X>` where
+        //
+        //     trait SubTrait: SuperTrait<i32> {}
+        //     trait SuperTrait<A> { type T; }
         let candidate = if self.probe_trait_that_defines_assoc_item(
             trait_ref.def_id(),
             assoc_kind,
@@ -457,6 +446,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(),
@@ -500,29 +491,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_poly_bounds(
                         param_ty,

compiler/rustc_hir_analysis/src/astconv/generics.rs

@@ -141,35 +141,33 @@ fn generic_arg_mismatch_err(
     err.emit()
 }
 
-/// Creates the relevant generic arguments
-/// corresponding to a set of generic parameters. This is a
-/// rather complex function. Let us try to explain the role
+/// Lower generic arguments from the HIR to the [`rustc_middle::ty`] representation.
+///
+/// This is a rather complex function. Let us try to explain the role
 /// of each of its parameters:
 ///
-/// To start, we are given the `def_id` of the thing whose generic
-/// parameters we are instantiating, and a partial set of
-/// arguments `parent_args`. In general, the generic arguments
-/// for an item begin with arguments for all the "parents" of
-/// that item -- e.g., for a method it might include the
-/// parameters from the impl.
+/// To start, we are given the `def_id` of the thing whose generic parameters we
+/// are creating, and a partial set of arguments `parent_args`. In general,
+/// the generic arguments for an item begin with arguments for all the "parents"
+/// of that item -- e.g., for a method it might include the parameters from the impl.
 ///
 /// Therefore, the method begins by walking down these parents,
 /// starting with the outermost parent and proceed inwards until
 /// it reaches `def_id`. For each parent `P`, it will check `parent_args`
 /// first to see if the parent's arguments are listed in there. If so,
-/// we can append those and move on. Otherwise, it invokes the
-/// three callback functions:
+/// we can append those and move on. Otherwise, it uses the provided
+/// [`GenericArgsLowerer`] `ctx` which has the following methods:
 ///
 /// - `args_for_def_id`: given the `DefId` `P`, supplies back the
 ///   generic arguments that were given to that parent from within
 ///   the path; so e.g., if you have `<T as Foo>::Bar`, the `DefId`
 ///   might refer to the trait `Foo`, and the arguments might be
 ///   `[T]`. The boolean value indicates whether to infer values
 ///   for arguments whose values were not explicitly provided.
-/// - `provided_kind`: given the generic parameter and the value from `args_for_def_id`,
-///   instantiate a `GenericArg`.
-/// - `inferred_kind`: if no parameter was provided, and inference is enabled, then
-///   creates a suitable inference variable.
+/// - `provided_kind`: given the generic parameter and the value
+///   from `args_for_def_id`, creating a `GenericArg`.
+/// - `inferred_kind`: if no parameter was provided, and inference
+///   is enabled, then creates a suitable inference variable.
 pub fn lower_generic_args<'tcx: 'a, 'a>(
     tcx: TyCtxt<'tcx>,
     def_id: DefId,