Clean up commentary for new code

Author: osiewicz

src/cargo/ops/cargo_clean.rs

@@ -171,6 +171,8 @@ fn clean_specs(
 
     clean_ctx.progress = Box::new(CleaningPackagesBar::new(clean_ctx.gctx, packages.len()));
 
+    // Try to reduce the amount of times we iterate over the same target directory by storing away
+    // the directories we've iterated over (and cleaned for a given package).
     let mut cleaned_packages: HashMap<_, HashSet<_>> = HashMap::default();
     for pkg in packages {
         let pkg_dir = format!("{}-*", pkg.name());
@@ -236,11 +238,8 @@ fn clean_specs(
                             clean_ctx.rm_rf(&dep_info)?;
                         }
                     }
-                    // Remove dep-info file generated by rustc. It is not tracked in
-                    // file_types. It does not have a prefix.
                     let unhashed_dep_info = dir.join(format!("{}.d", crate_name));
                     clean_ctx.rm_rf(&unhashed_dep_info)?;
-                    // Remove split-debuginfo files generated by rustc.
 
                     if !dir_glob_str.ends_with(std::path::MAIN_SEPARATOR) {
                         dir_glob_str.push(std::path::MAIN_SEPARATOR);
@@ -253,7 +252,10 @@ fn clean_specs(
                         .insert(crate_name.clone())
                     {
                         let paths = [
+                            // Remove dep-info file generated by rustc. It is not tracked in
+                            // file_types. It does not have a prefix.
                             (path_dash.clone(), ".d"),
+                            // Remove split-debuginfo files generated by rustc.
                             (path_dot.clone(), ".o"),
                             (path_dot.clone(), ".dwo"),
                             (path_dot.clone(), ".dwp"),
@@ -339,13 +341,14 @@ impl<'gctx> CleanContext<'gctx> {
         Ok(())
     }
 
+    /// Iterates over files matching a glob (`pattern`), removing any files whose filenames start and end with provided prefix/suffix pair.
+    /// Compared to multiple separate calls to [`Self::rm_rf_glob`], this method iterates over the directory just once, which is why
+    /// it may be preferable for working with multiple prefix/suffix pairs.
     fn rm_rf_prefix_list(
         &mut self,
         pattern: &str,
         path_matchers: &[(Rc<str>, &str)],
     ) -> CargoResult<()> {
-        // TODO: Display utf8 warning to user?  Or switch to globset?
-
         for path in glob::glob(pattern)? {
             let path = path?;
             let filename = path.file_name().and_then(|name| name.to_str()).unwrap();