Applied suggestions from code review.

Author: Alexander Regueiro

src/librustc/traits/auto_trait.rs

@@ -233,44 +233,45 @@ impl<'tcx> AutoTraitFinder<'tcx> {
 }
 
 impl AutoTraitFinder<'tcx> {
- // The core logic responsible for computing the bounds for our synthesized impl.
- //
- // To calculate the bounds, we call `SelectionContext.select` in a loop. Like
- // `FulfillmentContext`, we recursively select the nested obligations of predicates we
- // encounter. However, whenever we encounter an `UnimplementedError` involving a type parameter,
- // we add it to our `ParamEnv`. Since our goal is to determine when a particular type implements
- // an auto trait, Unimplemented errors tell us what conditions need to be met.
- //
- // This method ends up working somewhat similarly to `FulfillmentContext`, but with a few key
- // differences. `FulfillmentContext` works under the assumption that it's dealing with concrete
- // user code. According, it considers all possible ways that a `Predicate` could be met, which
- // isn't always what we want for a synthesized impl. For example, given the predicate `T:
- // Iterator`, `FulfillmentContext` can end up reporting an Unimplemented error for `T:
- // IntoIterator` -- since there's an implementation of `Iterator` where `T: IntoIterator`,
- // `FulfillmentContext` will drive `SelectionContext` to consider that impl before giving up. If
- // we were to rely on `FulfillmentContext`'s decision, we might end up synthesizing an impl like
- // this:
- //
- // impl<T> Send for Foo<T> where T: IntoIterator
- //
- // While it might be technically true that Foo implements Send where `T: IntoIterator`,
- // the bound is overly restrictive - it's really only necessary that `T: Iterator`.
- //
- // For this reason, `evaluate_predicates` handles predicates with type variables specially. When
- // we encounter an `Unimplemented` error for a bound such as `T: Iterator`, we immediately add
- // it to our `ParamEnv`, and add it to our stack for recursive evaluation. When we later select
- // it, we'll pick up any nested bounds, without ever inferring that `T: IntoIterator` needs to
- // hold.
- //
- // One additional consideration is supertrait bounds. Normally, a `ParamEnv` is only ever
- // constructed once for a given type. As part of the construction process, the `ParamEnv` will
- // have any supertrait bounds normalized -- e.g., if we have a type `struct Foo<T: Copy>`, the
- // `ParamEnv` will contain `T: Copy` and `T: Clone`, since `Copy: Clone`. When we construct our
- // own `ParamEnv`, we need to do this ourselves, through `traits::elaborate_predicates`, or else
- // `SelectionContext` will choke on the missing predicates. However, this should never show up
- // in the final synthesized generics: we don't want our generated docs page to contain something
- // like `T: Copy + Clone`, as that's redundant. Therefore, we keep track of a separate
- // `user_env`, which only holds the predicates that will actually be displayed to the user.
+ /// The core logic responsible for computing the bounds for our synthesized impl.
+ ///
+ /// To calculate the bounds, we call `SelectionContext.select` in a loop. Like
+ /// `FulfillmentContext`, we recursively select the nested obligations of predicates we
+ /// encounter. However, whenever we encounter an `UnimplementedError` involving a type
+ /// parameter, we add it to our `ParamEnv`. Since our goal is to determine when a particular
+ /// type implements an auto trait, Unimplemented errors tell us what conditions need to be met.
+ ///
+ /// This method ends up working somewhat similarly to `FulfillmentContext`, but with a few key
+ /// differences. `FulfillmentContext` works under the assumption that it's dealing with concrete
+ /// user code. According, it considers all possible ways that a `Predicate` could be met, which
+ /// isn't always what we want for a synthesized impl. For example, given the predicate `T:
+ /// Iterator`, `FulfillmentContext` can end up reporting an Unimplemented error for `T:
+ /// IntoIterator` -- since there's an implementation of `Iterator` where `T: IntoIterator`,
+ /// `FulfillmentContext` will drive `SelectionContext` to consider that impl before giving up.
+ /// If we were to rely on `FulfillmentContext`s decision, we might end up synthesizing an impl
+ /// like this:
+ ///
+ /// impl<T> Send for Foo<T> where T: IntoIterator
+ ///
+ /// While it might be technically true that Foo implements Send where `T: IntoIterator`,
+ /// the bound is overly restrictive - it's really only necessary that `T: Iterator`.
+ ///
+ /// For this reason, `evaluate_predicates` handles predicates with type variables specially.
+ /// When we encounter an `Unimplemented` error for a bound such as `T: Iterator`, we immediately
+ /// add it to our `ParamEnv`, and add it to our stack for recursive evaluation. When we later
+ /// select it, we'll pick up any nested bounds, without ever inferring that `T: IntoIterator`
+ /// needs to hold.
+ ///
+ /// One additional consideration is supertrait bounds. Normally, a `ParamEnv` is only ever
+ /// constructed once for a given type. As part of the construction process, the `ParamEnv` will
+ /// have any supertrait bounds normalized -- e.g., if we have a type `struct Foo<T: Copy>`, the
+ /// `ParamEnv` will contain `T: Copy` and `T: Clone`, since `Copy: Clone`. When we construct our
+ /// own `ParamEnv`, we need to do this ourselves, through `traits::elaborate_predicates`, or
+ /// else `SelectionContext` will choke on the missing predicates. However, this should never
+ /// show up in the final synthesized generics: we don't want our generated docs page to contain
+ /// something like `T: Copy + Clone`, as that's redundant. Therefore, we keep track of a
+ /// separate `user_env`, which only holds the predicates that will actually be displayed to the
+ /// user.
  fn evaluate_predicates(
  &self,
  infcx: &InferCtxt<'_, 'tcx>,
@@ -393,29 +394,29 @@ impl AutoTraitFinder<'tcx> {
  return Some((new_env, final_user_env));
  }
 
- // This method is designed to work around the following issue:
- // When we compute auto trait bounds, we repeatedly call `SelectionContext.select`,
- // progressively building a `ParamEnv` based on the results we get.
- // However, our usage of `SelectionContext` differs from its normal use within the compiler,
- // in that we capture and re-reprocess predicates from `Unimplemented` errors.
- //
- // This can lead to a corner case when dealing with region parameters.
- // During our selection loop in `evaluate_predicates`, we might end up with
- // two trait predicates that differ only in their region parameters:
- // one containing a HRTB lifetime parameter, and one containing a 'normal'
- // lifetime parameter. For example:
- //
- // T as MyTrait<'a>
- // T as MyTrait<'static>
- //
- // If we put both of these predicates in our computed `ParamEnv`, we'll
- // confuse `SelectionContext`, since it will (correctly) view both as being applicable.
- //
- // To solve this, we pick the 'more strict' lifetime bound -- i.e., the HRTB
- // Our end goal is to generate a user-visible description of the conditions
- // under which a type implements an auto trait. A trait predicate involving
- // a HRTB means that the type needs to work with any choice of lifetime,
- // not just one specific lifetime (e.g., `'static`).
+ /// This method is designed to work around the following issue:
+ /// When we compute auto trait bounds, we repeatedly call `SelectionContext.select`,
+ /// progressively building a `ParamEnv` based on the results we get.
+ /// However, our usage of `SelectionContext` differs from its normal use within the compiler,
+ /// in that we capture and re-reprocess predicates from `Unimplemented` errors.
+ ///
+ /// This can lead to a corner case when dealing with region parameters.
+ /// During our selection loop in `evaluate_predicates`, we might end up with
+ /// two trait predicates that differ only in their region parameters:
+ /// one containing a HRTB lifetime parameter, and one containing a 'normal'
+ /// lifetime parameter. For example:
+ ///
+ /// T as MyTrait<'a>
+ /// T as MyTrait<'static>
+ ///
+ /// If we put both of these predicates in our computed `ParamEnv`, we'll
+ /// confuse `SelectionContext`, since it will (correctly) view both as being applicable.
+ ///
+ /// To solve this, we pick the 'more strict' lifetime bound -- i.e., the HRTB
+ /// Our end goal is to generate a user-visible description of the conditions
+ /// under which a type implements an auto trait. A trait predicate involving
+ /// a HRTB means that the type needs to work with any choice of lifetime,
+ /// not just one specific lifetime (e.g., `'static`).
  fn add_user_pred<'c>(
  &self,
  user_computed_preds: &mut FxHashSet<ty::Predicate<'c>>,
@@ -506,8 +507,8 @@ impl AutoTraitFinder<'tcx> {
  }
  }
 
- // This is very similar to `handle_lifetimes`. However, instead of matching `ty::Region`'s
- // to each other, we match `ty::RegionVid`'s to `ty::Region`'s.
+ /// This is very similar to `handle_lifetimes`. However, instead of matching `ty::Region`s
+ /// to each other, we match `ty::RegionVid`s to `ty::Region`s.
  fn map_vid_to_region<'cx>(
  &self,
  regions: &RegionConstraintData<'cx>,

src/librustc/traits/mod.rs

@@ -191,7 +191,7 @@ pub enum ObligationCauseCode<'tcx> {
  /// Obligation incurred due to a coercion.
  Coercion { source: Ty<'tcx>, target: Ty<'tcx> },
 
- // Various cases where expressions must be `Sized` / `Copy` / etc.
+ /// Various cases where expressions must be `Sized` / `Copy` / etc.
  /// `L = X` implies that `L` is `Sized`.
  AssignmentLhsSized,
  /// `(x1, .., xn)` must be `Sized`.

src/librustc/traits/select.rs

@@ -1198,26 +1198,26 @@ impl<'cx, 'tcx> SelectionContext<'cx, 'tcx> {
  .insert(trait_ref, WithDepNode::new(dep_node, result));
  }
 
- // For various reasons, it's possible for a subobligation
- // to have a *lower* recursion_depth than the obligation used to create it.
- // Projection sub-obligations may be returned from the projection cache,
- // which results in obligations with an 'old' `recursion_depth`.
- // Additionally, methods like `ty::wf::obligations` and
- // `InferCtxt.subtype_predicate` produce subobligations without
- // taking in a 'parent' depth, causing the generated subobligations
- // to have a `recursion_depth` of `0`.
- //
- // To ensure that obligation_depth never decreasees, we force all subobligations
- // to have at least the depth of the original obligation.
+ /// For various reasons, it's possible for a subobligation
+ /// to have a *lower* recursion_depth than the obligation used to create it.
+ /// Projection sub-obligations may be returned from the projection cache,
+ /// which results in obligations with an 'old' `recursion_depth`.
+ /// Additionally, methods like `ty::wf::obligations` and
+ /// `InferCtxt.subtype_predicate` produce subobligations without
+ /// taking in a 'parent' depth, causing the generated subobligations
+ /// to have a `recursion_depth` of `0`.
+ ///
+ /// To ensure that obligation_depth never decreasees, we force all subobligations
+ /// to have at least the depth of the original obligation.
  fn add_depth<T: 'cx, I: Iterator<Item = &'cx mut Obligation<'tcx, T>>>(&self, it: I,
  min_depth: usize) {
  it.for_each(|o| o.recursion_depth = cmp::max(min_depth, o.recursion_depth) + 1);
  }
 
- // Checks that the recursion limit has not been exceeded.
- //
- // The weird return type of this function allows it to be used with the `try` (`?`)
- // operator within certain functions.
+ /// Checks that the recursion limit has not been exceeded.
+ ///
+ /// The weird return type of this function allows it to be used with the `try` (`?`)
+ /// operator within certain functions.
  fn check_recursion_limit<T: Display + TypeFoldable<'tcx>, V: Display + TypeFoldable<'tcx>>(
  &self,
  obligation: &Obligation<'tcx, T>,

src/librustc_codegen_llvm/debuginfo/metadata.rs

@@ -91,19 +91,19 @@ pub const NO_SCOPE_METADATA: Option<&DIScope> = None;
 #[derive(Copy, Debug, Hash, Eq, PartialEq, Clone)]
 pub struct UniqueTypeId(ast::Name);
 
-// The `TypeMap` is where the `CrateDebugContext` holds the type metadata nodes
-// created so far. The metadata nodes are indexed by `UniqueTypeId`, and, for
-// faster lookup, also by `Ty`. The `TypeMap` is responsible for creating
-// `UniqueTypeId`s.
+/// The `TypeMap` is where the `CrateDebugContext` holds the type metadata nodes
+/// created so far. The metadata nodes are indexed by `UniqueTypeId`, and, for
+/// faster lookup, also by `Ty`. The `TypeMap` is responsible for creating
+/// `UniqueTypeId`s.
 #[derive(Default)]
 pub struct TypeMap<'ll, 'tcx> {
- // The `UniqueTypeId`s created so far.
+ /// The `UniqueTypeId`s created so far.
  unique_id_interner: Interner,
- // A map from `UniqueTypeId` to debuginfo metadata for that type. This is a 1:1 mapping.
+ /// A map from `UniqueTypeId` to debuginfo metadata for that type. This is a 1:1 mapping.
  unique_id_to_metadata: FxHashMap<UniqueTypeId, &'ll DIType>,
- // A map from types to debuginfo metadata. This is an N:1 mapping.
+ /// A map from types to debuginfo metadata. This is an N:1 mapping.
  type_to_metadata: FxHashMap<Ty<'tcx>, &'ll DIType>,
- // A map from types to `UniqueTypeId`. This is an N:1 mapping.
+ /// A map from types to `UniqueTypeId`. This is an N:1 mapping.
  type_to_unique_id: FxHashMap<Ty<'tcx>, UniqueTypeId>
 }
 
@@ -203,9 +203,9 @@ impl TypeMap<'ll, 'tcx> {
  return UniqueTypeId(key);
  }
 
- // Get the `UniqueTypeId` for an enum variant. Enum variants are not really
- // types of their own, so they need special handling. We still need a
- // UniqueTypeId for them, since to debuginfo they *are* real types.
+ /// Gets the `UniqueTypeId` for an enum variant. Enum variants are not really
+ /// types of their own, so they need special handling. We still need a
+ /// `UniqueTypeId` for them, since to debuginfo they *are* real types.
  fn get_unique_type_id_of_enum_variant<'a>(&mut self,
  cx: &CodegenCx<'a, 'tcx>,
  enum_type: Ty<'tcx>,
@@ -219,9 +219,9 @@ impl TypeMap<'ll, 'tcx> {
  UniqueTypeId(interner_key)
  }
 
- // Get the unique type ID string for an enum variant part.
- // Variant parts are not types and shouldn't really have their own ID,
- // but it makes `set_members_of_composite_type()` simpler.
+ /// Gets the unique type ID string for an enum variant part.
+ /// Variant parts are not types and shouldn't really have their own ID,
+ /// but it makes `set_members_of_composite_type()` simpler.
  fn get_unique_type_id_str_of_enum_variant_part(&mut self, enum_type_id: UniqueTypeId) -> &str {
  let variant_part_type_id = format!("{}_variant_part",
  self.get_unique_type_id_as_string(enum_type_id));
@@ -1027,7 +1027,7 @@ impl MetadataCreationResult<'ll> {
  }
 }
 
-// Description of a type member, which can either be a regular field (as in
+/// Description of a type member, which can either be a regular field (as in
 /// structs or tuples) or an enum variant.
 #[derive(Debug)]
 struct MemberDescription<'ll> {