Add some commenting

compiler/rustc_lint/src/impl_trait_overcaptures.rs

@@ -24,8 +24,8 @@ declare_lint! {
 }
 
 declare_lint_pass!(
-    /// Lint for use of `async fn` in the definition of a publicly-reachable
-    /// trait.
+    /// Lint for opaque types that will begin capturing in-scope but unmentioned lifetimes
+    /// in edition 2024.
     ImplTraitOvercaptures => [IMPL_TRAIT_OVERCAPTURES]
 );
 
@@ -50,7 +50,7 @@ impl<'tcx> LateLintPass<'tcx> for ImplTraitOvercaptures {
                 }
             }
             DefKind::Fn => {
-                // All freee functions need to check for overcaptures.
+                // All free functions need to check for overcaptures.
             }
             DefKind::Closure => return,
             kind => {
@@ -64,6 +64,7 @@ impl<'tcx> LateLintPass<'tcx> for ImplTraitOvercaptures {
         let sig = cx.tcx.fn_sig(parent_def_id).instantiate_identity();
 
         let mut in_scope_parameters = FxIndexSet::default();
+        // Populate the in_scope_parameters list first with all of the generics in scope
         let mut current_def_id = Some(parent_def_id.to_def_id());
         while let Some(def_id) = current_def_id {
             let generics = cx.tcx.generics_of(def_id);
@@ -73,6 +74,8 @@ impl<'tcx> LateLintPass<'tcx> for ImplTraitOvercaptures {
             current_def_id = generics.parent;
         }
 
+        // Then visit the signature to walk through all the binders (incl. the late-bound
+        // vars on the function itself, which we need to count too).
         sig.visit_with(&mut VisitOpaqueTypes {
             tcx: cx.tcx,
             parent_def_id,
@@ -94,6 +97,7 @@ impl<'tcx> TypeVisitor<TyCtxt<'tcx>> for VisitOpaqueTypes<'tcx> {
         &mut self,
         t: &ty::Binder<'tcx, T>,
     ) -> Self::Result {
+        // When we get into a binder, we need to add its own bound vars to the scope.
         let mut added = vec![];
         for arg in t.bound_vars() {
             let arg: ty::BoundVariableKind = arg;
@@ -117,6 +121,8 @@ impl<'tcx> TypeVisitor<TyCtxt<'tcx>> for VisitOpaqueTypes<'tcx> {
 
         t.super_visit_with(self);
 
+        // And remove them. The `shift_remove` should be `O(1)` since we're popping
+        // them off from the end.
         for arg in added.into_iter().rev() {
             self.in_scope_parameters.shift_remove(&arg);
         }
@@ -129,22 +135,29 @@ impl<'tcx> TypeVisitor<TyCtxt<'tcx>> for VisitOpaqueTypes<'tcx> {
 
         if let ty::Alias(ty::Opaque, opaque_ty) = *t.kind()
             && let Some(opaque_def_id) = opaque_ty.def_id.as_local()
+            // Don't recurse infinitely on an opaque
             && self.seen.insert(opaque_def_id)
+            // If it's owned by this function
             && let opaque =
                 self.tcx.hir_node_by_def_id(opaque_def_id).expect_item().expect_opaque_ty()
             && let hir::OpaqueTyOrigin::FnReturn(parent_def_id) = opaque.origin
             && parent_def_id == self.parent_def_id
+            // And if the opaque doesn't already have `use<>` syntax on it...
             && opaque.precise_capturing_args.is_none()
         {
+            // Compute the set of args that are captured by the opaque...
             let mut captured = UnordSet::default();
             let variances = self.tcx.variances_of(opaque_def_id);
             let mut current_def_id = Some(opaque_def_id.to_def_id());
             while let Some(def_id) = current_def_id {
                 let generics = self.tcx.generics_of(def_id);
-                for param in &generics.params {
+                for param in &generics.own_params {
+                    // A param is captured if it's invariant.
                     if variances[param.index as usize] != ty::Invariant {
                         continue;
                     }
+                    // We need to turn all `ty::Param`/`ConstKind::Param` and
+                    // `ReEarlyParam`/`ReBound` into def ids.
                     captured.insert(extract_def_id_from_arg(
                         self.tcx,
                         generics,
@@ -154,6 +167,8 @@ impl<'tcx> TypeVisitor<TyCtxt<'tcx>> for VisitOpaqueTypes<'tcx> {
                 current_def_id = generics.parent;
             }
 
+            // Compute the set of in scope params that are not captured. Get their spans,
+            // since that's all we really care about them for emitting the diagnostic.
             let uncaptured_spans: Vec<_> = self
                 .in_scope_parameters
                 .iter()
@@ -174,6 +189,10 @@ impl<'tcx> TypeVisitor<TyCtxt<'tcx>> for VisitOpaqueTypes<'tcx> {
                 );
             }
 
+            // Walk into the bounds of the opaque, too, since we want to get nested opaques
+            // in this lint as well. Interestingly, one place that I expect this lint to fire
+            // is for `impl for<'a> Bound<Out = impl Other>`, since `impl Other` will begin
+            // to capture `'a` in e2024 (even though late-bound vars in opaques are not allowed).
             for clause in
                 self.tcx.item_bounds(opaque_ty.def_id).iter_instantiated(self.tcx, opaque_ty.args)
             {