docs(fingerprint): reorganize rustdoc fingerprint docs

Author: weihanglo

src/cargo/core/compiler/build_runner/mod.rs

@@ -174,14 +174,9 @@ impl<'a, 'gctx> BuildRunner<'a, 'gctx> {
         self.check_collisions()?;
         self.compute_metadata_for_doc_units();
 
-        // We need to make sure that if there were any previous docs
-        // already compiled, they were compiled with the same Rustc version that we're currently
-        // using. Otherwise we must remove the `doc/` folder and compile again forcing a rebuild.
-        //
-        // This is important because the `.js`/`.html` & `.css` files that are generated by Rustc don't have
-        // any versioning (See https://github.com/rust-lang/cargo/issues/8461).
-        // Therefore, we can end up with weird bugs and behaviours if we mix different
-        // versions of these files.
+        // We need to make sure that if there were any previous docs already compiled,
+        // they were compiled with the same Rustc version that we're currently using.
+        // See the function doc comment for more.
         if self.bcx.build_config.intent.is_doc() {
             RustDocFingerprint::check_rustdoc_fingerprint(&self)?
         }

src/cargo/core/compiler/fingerprint/rustdoc.rs

@@ -9,20 +9,31 @@ use crate::CargoResult;
 use crate::core::compiler::BuildRunner;
 
 /// Structure used to deal with Rustdoc fingerprinting
+///
+/// This is important because the `.js`/`.html` & `.css` files
+/// that are generated by Rustc don't have any versioning yet
+/// (see <https://github.com/rust-lang/cargo/issues/8461>).
+/// Therefore, we can end up with weird bugs and behaviours
+/// if we mix different versions of these files.
+///
+/// We need to make sure that if there were any previous docs already compiled,
+/// they were compiled with the same Rustc version that we're currently using.
+/// Otherwise we must remove the `doc/` folder and compile again forcing a rebuild.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct RustDocFingerprint {
+    /// `rustc -vV` verbose version output.
     pub rustc_vv: String,
 }
 
 impl RustDocFingerprint {
-    /// This function checks whether the latest version of `Rustc` used to compile this
-    /// `Workspace`'s docs was the same as the one is currently being used in this `cargo doc`
-    /// call.
+    /// Checks whether the latest version of rustc used to compile this workspace's docs
+    /// was the same as the one is currently being used in this `cargo doc` call.
     ///
-    /// In case it's not, it takes care of removing the `doc/` folder as well as overwriting
-    /// the rustdoc fingerprint info in order to guarantee that we won't end up with mixed
-    /// versions of the `js/html/css` files that `rustdoc` autogenerates which do not have
-    /// any versioning.
+    /// In case it's not,
+    /// it takes care of removing the `<artifact-dir>/doc/` folder
+    /// as well as overwriting the rustdoc fingerprint info.
+    /// This is to guarantee that we won't end up with mixed versions of the `js/html/css` files
+    /// which `rustdoc` autogenerates without any versioning.
     pub fn check_rustdoc_fingerprint(build_runner: &BuildRunner<'_, '_>) -> CargoResult<()> {
         if build_runner
             .bcx