refactor(package): add comments

Author: weihanglo

src/cargo/ops/cargo_package/mod.rs

@@ -79,7 +79,7 @@ enum GeneratedFile {
     Manifest,
     /// Generates `Cargo.lock` in some cases (like if there is a binary).
     Lockfile,
-    /// Adds a `.cargo_vcs_info.json` file if in a (clean) git repo.
+    /// Adds a `.cargo_vcs_info.json` file if in a git repo.
     VcsInfo(vcs::VcsInfo),
 }
 

src/cargo/ops/cargo_package/vcs.rs

@@ -1,3 +1,5 @@
+//! Helpers to gather the VCS information for `cargo package`.
+
 use std::path::Path;
 use std::path::PathBuf;
 
@@ -12,13 +14,15 @@ use crate::GlobalContext;
 
 use super::PackageOpts;
 
+/// Represents the VCS information when packaging.
 #[derive(Serialize)]
 pub struct VcsInfo {
     git: GitVcsInfo,
-    /// Path to the package within repo (empty string if root). / not \
+    /// Path to the package within repo (empty string if root).
     path_in_vcs: String,
 }
 
+/// Represents the Git VCS information when packaging.
 #[derive(Serialize)]
 pub struct GitVcsInfo {
     sha1: String,
@@ -27,11 +31,13 @@ pub struct GitVcsInfo {
     dirty: bool,
 }
 
-/// Checks if the package source is in a *git* DVCS repository. If *git*, and
-/// the source is *dirty* (e.g., has uncommitted changes), and `--allow-dirty`
-/// has not been passed, then `bail!` with an informative message. Otherwise
-/// return the sha1 hash of the current *HEAD* commit, or `None` if no repo is
-/// found.
+/// Checks if the package source is in a *git* DVCS repository.
+///
+/// If *git*, and the source is *dirty* (e.g., has uncommitted changes),
+/// and `--allow-dirty` has not been passed,
+/// then `bail!` with an informative message.
+/// Otherwise return the sha1 hash of the current *HEAD* commit,
+/// or `None` if no repo is found.
 #[tracing::instrument(skip_all)]
 pub fn check_repo_state(
     p: &Package,
@@ -104,6 +110,7 @@ pub fn check_repo_state(
     return Ok(Some(VcsInfo { git, path_in_vcs }));
 }
 
+/// The real git status check starts from here.
 fn git(
     pkg: &Package,
     gctx: &GlobalContext,

src/cargo/ops/cargo_package/verify.rs

@@ -1,3 +1,5 @@
+//! Helpers to verify a packaged `.crate` file.
+
 use std::collections::HashMap;
 use std::fs;
 use std::fs::File;
@@ -29,6 +31,7 @@ use crate::CargoResult;
 use super::PackageOpts;
 use super::TmpRegistry;
 
+/// Verifies whether a `.crate` file is able to compile.
 pub fn run_verify(
     ws: &Workspace<'_>,
     pkg: &Package,
@@ -123,6 +126,11 @@ pub fn run_verify(
     Ok(())
 }
 
+/// Hashes everything under a given directory.
+///
+/// This is for checking if any source file inside a `.crate` file has changed
+/// durint the compilation. It is usually caused by bad build scripts or proc
+/// macros trying to modify source files. Cargo disallows that.
 fn hash_all(path: &Path) -> CargoResult<HashMap<PathBuf, u64>> {
     fn wrap(path: &Path) -> CargoResult<HashMap<PathBuf, u64>> {
         let mut result = HashMap::new();
@@ -148,6 +156,7 @@ fn hash_all(path: &Path) -> CargoResult<HashMap<PathBuf, u64>> {
     Ok(result)
 }
 
+/// Reports the hash difference before and after the compilation computed by  [`hash_all`].
 fn report_hash_difference(orig: &HashMap<PathBuf, u64>, after: &HashMap<PathBuf, u64>) -> String {
     let mut changed = Vec::new();
     let mut removed = Vec::new();