Skip to content

Commit 4e7e8e7

Browse files
committed
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.
1 parent be398be commit 4e7e8e7

File tree

33 files changed

+248
-189
lines changed

33 files changed

+248
-189
lines changed

compiler/rustc_ast/src/visit.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -480,7 +480,7 @@ pub fn walk_use_tree<'a, V: Visitor<'a>>(
480480
try_visit!(visitor.visit_path(&use_tree.prefix, id));
481481
match use_tree.kind {
482482
UseTreeKind::Simple(rename) => {
483-
// The extra IDs are handled during HIR lowering.
483+
// The extra IDs are handled during AST lowering.
484484
visit_opt!(visitor, visit_ident, rename);
485485
}
486486
UseTreeKind::Glob => {}

compiler/rustc_ast_lowering/src/delegation.rs

+4-3
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,12 @@
2929
//! item id (`item_id`) in case of impl trait or path resolution id (`path_id`) otherwise.
3030
//!
3131
//! Since we do not have a proper way to obtain function type information by path resolution
32-
//! in AST, we mark each function parameter type as `InferDelegation` and inherit it in `AstConv`.
32+
//! in AST, we mark each function parameter type as `InferDelegation` and inherit it during
33+
//! HIR ty lowering.
3334
//!
3435
//! Similarly generics, predicates and header are set to the "default" values.
3536
//! In case of discrepancy with callee function the `NotSupportedDelegation` error will
36-
//! also be emitted in `AstConv`.
37+
//! also be emitted during HIR ty lowering.
3738
3839
use crate::{ImplTraitPosition, ResolverAstLoweringExt};
3940

@@ -129,7 +130,7 @@ impl<'hir> LoweringContext<'_, 'hir> {
129130
) -> &'hir hir::FnDecl<'hir> {
130131
let args_count = if let Some(local_sig_id) = sig_id.as_local() {
131132
// Map may be filled incorrectly due to recursive delegation.
132-
// Error will be emmited later in astconv.
133+
// Error will be emitted later during HIR ty lowering.
133134
self.resolver.fn_parameter_counts.get(&local_sig_id).cloned().unwrap_or_default()
134135
} else {
135136
self.tcx.fn_arg_names(sig_id).len()

compiler/rustc_ast_lowering/src/item.rs

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

compiler/rustc_hir/src/hir.rs

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

compiler/rustc_hir_analysis/src/astconv/bounds.rs

+39-56
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,9 @@ use crate::bounds::Bounds;
1414
use crate::errors;
1515

1616
impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
17-
/// Sets `implicitly_sized` to true on `Bounds` if necessary
17+
/// Add a `Sized` bound to the `bounds` if appropriate.
18+
///
19+
/// Doesn't add the bound if the HIR bounds contain any of `Sized`, `?Sized` or `!Sized`.
1820
pub(crate) fn add_sized_bound(
1921
&self,
2022
bounds: &mut Bounds<'tcx>,
@@ -98,21 +100,21 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
98100
}
99101
}
100102

101-
/// This helper takes a *converted* parameter type (`param_ty`)
102-
/// and an *unconverted* list of bounds:
103+
/// Lower HIR bounds into `bounds` given the self type `param_ty`.
104+
///
105+
/// ### Example
103106
///
104-
/// ```text
105-
/// fn foo<T: Debug>
106-
/// ^ ^^^^^ `ast_bounds` parameter, in HIR form
107-
/// |
108-
/// `param_ty`, in ty form
107+
/// ```ignore (illustrative)
108+
/// fn foo<T: Debug>() { }
109+
/// // ^ ^^^^^ `ast_bounds`, in HIR form
110+
/// // |
111+
/// // `param_ty`, in ty form
109112
/// ```
110113
///
111-
/// It adds these `ast_bounds` into the `bounds` structure.
114+
/// ### A Note on Binders
112115
///
113-
/// **A note on binders:** there is an implied binder around
114-
/// `param_ty` and `ast_bounds`. See `instantiate_poly_trait_ref`
115-
/// for more details.
116+
/// There is an implied binder around `param_ty` and `ast_bounds`.
117+
/// See `lower_poly_trait_ref` for more details.
116118
#[instrument(level = "debug", skip(self, ast_bounds, bounds))]
117119
pub(crate) fn lower_poly_bounds<'hir, I: Iterator<Item = &'hir hir::GenericBound<'tcx>>>(
118120
&self,
@@ -168,22 +170,15 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
168170
}
169171
}
170172

171-
/// Translates a list of bounds from the HIR into the `Bounds` data structure.
172-
/// The self-type for the bounds is given by `param_ty`.
173+
/// Lower HIR bounds into `bounds` given the self type `param_ty`.
173174
///
174-
/// Example:
175+
/// ### Example
175176
///
176177
/// ```ignore (illustrative)
177178
/// fn foo<T: Bar + Baz>() { }
178179
/// // ^ ^^^^^^^^^ ast_bounds
179180
/// // param_ty
180181
/// ```
181-
///
182-
/// The `sized_by_default` parameter indicates if, in this context, the `param_ty` should be
183-
/// considered `Sized` unless there is an explicit `?Sized` bound. This would be true in the
184-
/// example above, but is not true in supertrait listings like `trait Foo: Bar + Baz`.
185-
///
186-
/// `span` should be the declaration size of the parameter.
187182
pub(crate) fn lower_mono_bounds(
188183
&self,
189184
param_ty: Ty<'tcx>,
@@ -225,12 +220,14 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
225220
bounds
226221
}
227222

228-
/// Given an HIR binding like `Item = Foo` or `Item: Foo`, pushes the corresponding predicates
229-
/// onto `bounds`.
223+
/// Lower an associated item binding from HIR into `bounds`.
224+
///
225+
/// ### A Note on Binders
230226
///
231-
/// **A note on binders:** given something like `T: for<'a> Iterator<Item = &'a u32>`, the
232-
/// `trait_ref` here will be `for<'a> T: Iterator`. The `binding` data however is from *inside*
233-
/// the binder (e.g., `&'a u32`) and hence may reference bound regions.
227+
/// Given something like `T: for<'a> Iterator<Item = &'a u32>`,
228+
/// the `trait_ref` here will be `for<'a> T: Iterator`.
229+
/// The `binding` data however is from *inside* the binder
230+
/// (e.g., `&'a u32`) and hence may reference bound regions.
234231
#[instrument(level = "debug", skip(self, bounds, speculative, dup_bindings, path_span))]
235232
pub(super) fn lower_assoc_item_binding(
236233
&self,
@@ -243,22 +240,6 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
243240
path_span: Span,
244241
only_self_bounds: OnlySelfBounds,
245242
) -> Result<(), ErrorGuaranteed> {
246-
// Given something like `U: SomeTrait<T = X>`, we want to produce a
247-
// predicate like `<U as SomeTrait>::T = X`. This is somewhat
248-
// subtle in the event that `T` is defined in a supertrait of
249-
// `SomeTrait`, because in that case we need to upcast.
250-
//
251-
// That is, consider this case:
252-
//
253-
// ```
254-
// trait SubTrait: SuperTrait<i32> { }
255-
// trait SuperTrait<A> { type T; }
256-
//
257-
// ... B: SubTrait<T = foo> ...
258-
// ```
259-
//
260-
// We want to produce `<B as SuperTrait<i32>>::T == foo`.
261-
262243
let tcx = self.tcx();
263244

264245
let assoc_kind = if binding.gen_args.parenthesized
@@ -271,6 +252,14 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
271252
ty::AssocKind::Type
272253
};
273254

255+
// Given something like `U: Trait<T = X>`, we want to produce a predicate like
256+
// `<U as Trait>::T = X`.
257+
// This is somewhat subtle in the event that `T` is defined in a supertrait of `Trait`,
258+
// because in that case we need to upcast. I.e., we want to produce
259+
// `<B as SuperTrait<i32>>::T == X` for `B: SubTrait<T = X>` where
260+
//
261+
// trait SubTrait: SuperTrait<i32> {}
262+
// trait SuperTrait<A> { type T; }
274263
let candidate = if self.probe_trait_that_defines_assoc_item(
275264
trait_ref.def_id(),
276265
assoc_kind,
@@ -457,6 +446,8 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
457446
span: binding.span,
458447
}));
459448
}
449+
// Lower an equality constraint like `Item = u32` as found in HIR bound `T: Iterator<Item = u32>`
450+
// to a projection predicate: `<T as Iterator>::Item = u32`.
460451
hir::TypeBindingKind::Equality { term } => {
461452
let term = match term {
462453
hir::Term::Ty(ty) => self.lower_ty(ty).into(),
@@ -500,29 +491,21 @@ impl<'tcx> dyn HirTyLowerer<'tcx> + '_ {
500491
);
501492
}
502493

503-
// "Desugar" a constraint like `T: Iterator<Item = u32>` this to
504-
// the "projection predicate" for:
505-
//
506-
// `<T as Iterator>::Item = u32`
507494
bounds.push_projection_bound(
508495
tcx,
509496
projection_ty
510497
.map_bound(|projection_ty| ty::ProjectionPredicate { projection_ty, term }),
511498
binding.span,
512499
);
513500
}
501+
// Lower a constraint like `Item: Debug` as found in HIR bound `T: Iterator<Item: Debug>`
502+
// to a bound involving a projection: `<T as Iterator>::Item: Debug`.
514503
hir::TypeBindingKind::Constraint { bounds: ast_bounds } => {
515-
// "Desugar" a constraint like `T: Iterator<Item: Debug>` to
516-
//
517-
// `<T as Iterator>::Item: Debug`
518-
//
519-
// Calling `skip_binder` is okay, because `add_bounds` expects the `param_ty`
520-
// parameter to have a skipped binder.
521-
//
522-
// NOTE: If `only_self_bounds` is true, do NOT expand this associated
523-
// type bound into a trait predicate, since we only want to add predicates
524-
// for the `Self` type.
504+
// NOTE: If `only_self_bounds` is true, do NOT expand this associated type bound into
505+
// a trait predicate, since we only want to add predicates for the `Self` type.
525506
if !only_self_bounds.0 {
507+
// Calling `skip_binder` is okay, because `lower_bounds` expects the `param_ty`
508+
// parameter to have a skipped binder.
526509
let param_ty = Ty::new_alias(tcx, ty::Projection, projection_ty.skip_binder());
527510
self.lower_poly_bounds(
528511
param_ty,

compiler/rustc_hir_analysis/src/astconv/generics.rs

+13-15
Original file line numberDiff line numberDiff line change
@@ -141,35 +141,33 @@ fn generic_arg_mismatch_err(
141141
err.emit()
142142
}
143143

144-
/// Creates the relevant generic arguments
145-
/// corresponding to a set of generic parameters. This is a
146-
/// rather complex function. Let us try to explain the role
144+
/// Lower generic arguments from the HIR to the [`rustc_middle::ty`] representation.
145+
///
146+
/// This is a rather complex function. Let us try to explain the role
147147
/// of each of its parameters:
148148
///
149-
/// To start, we are given the `def_id` of the thing whose generic
150-
/// parameters we are instantiating, and a partial set of
151-
/// arguments `parent_args`. In general, the generic arguments
152-
/// for an item begin with arguments for all the "parents" of
153-
/// that item -- e.g., for a method it might include the
154-
/// parameters from the impl.
149+
/// To start, we are given the `def_id` of the thing whose generic parameters we
150+
/// are creating, and a partial set of arguments `parent_args`. In general,
151+
/// the generic arguments for an item begin with arguments for all the "parents"
152+
/// of that item -- e.g., for a method it might include the parameters from the impl.
155153
///
156154
/// Therefore, the method begins by walking down these parents,
157155
/// starting with the outermost parent and proceed inwards until
158156
/// it reaches `def_id`. For each parent `P`, it will check `parent_args`
159157
/// first to see if the parent's arguments are listed in there. If so,
160-
/// we can append those and move on. Otherwise, it invokes the
161-
/// three callback functions:
158+
/// we can append those and move on. Otherwise, it uses the provided
159+
/// [`GenericArgsLowerer`] `ctx` which has the following methods:
162160
///
163161
/// - `args_for_def_id`: given the `DefId` `P`, supplies back the
164162
/// generic arguments that were given to that parent from within
165163
/// the path; so e.g., if you have `<T as Foo>::Bar`, the `DefId`
166164
/// might refer to the trait `Foo`, and the arguments might be
167165
/// `[T]`. The boolean value indicates whether to infer values
168166
/// for arguments whose values were not explicitly provided.
169-
/// - `provided_kind`: given the generic parameter and the value from `args_for_def_id`,
170-
/// instantiate a `GenericArg`.
171-
/// - `inferred_kind`: if no parameter was provided, and inference is enabled, then
172-
/// creates a suitable inference variable.
167+
/// - `provided_kind`: given the generic parameter and the value
168+
/// from `args_for_def_id`, creating a `GenericArg`.
169+
/// - `inferred_kind`: if no parameter was provided, and inference
170+
/// is enabled, then creates a suitable inference variable.
173171
pub fn lower_generic_args<'tcx: 'a, 'a>(
174172
tcx: TyCtxt<'tcx>,
175173
def_id: DefId,

0 commit comments

Comments
 (0)