docs(sources): doc comments for DirectorySource and ReplacedSource

Author: weihanglo

src/cargo/sources/directory.rs

@@ -13,17 +13,64 @@ use anyhow::Context as _;
 use cargo_util::{paths, Sha256};
 use serde::Deserialize;
 
+/// `DirectorySource` contains a number of crates on the file system. It was
+/// designed for representing vendored dependencies for `cargo vendor`.
+///
+/// `DirectorySource` at this moment is just a root directory containing other
+/// directories, which contain the source files of packages. Assumptions would
+/// be made to determine if a directory should be included as a package of a
+/// directory source's:
+///
+/// * Ignore directories starting with dot `.` (tend to be hidden).
+/// * Only when a `Cargo.toml` exists in a directory will it be included as
+///   a package. `DirectorySource` at this time only looks at one level of
+///   directories and never went deeper.
+/// * There must be a [`Checksum`] file `.cargo-checksum.json` file at the same
+///   level of `Cargo.toml` to ensure the integrity when a directory source was
+///   created (usually by `cargo vendor`). A failure to find or parse a single
+///   checksum results in a denial of loading any package in this source.
+/// * Otherwise, there is no other restrction of the name of directories. At
+///   this moment, it is `cargo vendor` that defines the layout and the name of
+///   each directory.
+///
+/// The file tree of a directory source may look like:
+///
+/// ```text
+/// [source root]
+/// ├── a-valid-crate/
+/// │  ├── src/
+/// │  ├── .cargo-checksum.json
+/// │  └── Cargo.toml
+/// ├── .ignored-a-dot-crate/
+/// │  ├── src/
+/// │  ├── .cargo-checksum.json
+/// │  └── Cargo.toml
+/// ├── skipped-no-manifest/
+/// │  ├── src/
+/// │  └── .cargo-checksum.json
+/// └── no-checksum-so-fails-the-entire-source-reading/
+///    └── Cargo.toml
+/// ```
 pub struct DirectorySource<'cfg> {
+    /// The unique identifier of this source.
     source_id: SourceId,
+    /// The root path of this source.
     root: PathBuf,
+    /// Packages that this sources has discovered.
     packages: HashMap<PackageId, (Package, Checksum)>,
     config: &'cfg Config,
     updated: bool,
 }
 
+/// The checksum file to ensure the integrity of a package in a directory source.
+///
+/// The file name is simply `.cargo-checksum.json`. The checksum algorithm as
+/// of now is SHA256.
 #[derive(Deserialize)]
 struct Checksum {
+    /// Checksum of the package. Normally it is computed from the `.crate` file.
     package: Option<String>,
+    /// Checksums of each source file.
     files: HashMap<String, String>,
 }
 

src/cargo/sources/mod.rs

@@ -1,3 +1,24 @@
+//! Implementations of `Source` trait.
+//!
+//! Cargo provides several built-in implementations of [`Source`] trait. Namely,
+//!
+//! * [`RegistrySource`] --- A source that provides an index for people to query
+//!   a crate's metadata, and fetch files for a certain crate. crates.io falls
+//!   into this category. So do local registry and sparse registry.
+//! * [`DirectorySource`] --- Files are downloaded ahead of time. Primarily
+//!   designed for crates generated from `cargo vendor`.
+//! * [`GitSource`] --- This gets crate information from a git repository.
+//! * [`PathSource`] --- This gets crate information from a local path on the
+//!   filesystem.
+//! * [`ReplacedSource`] --- This manages the [source replacement] feature,
+//!   redirecting operations on the original source to the replacement.
+//!
+//! This module also contains [`SourceConfigMap`], which is effectively the
+//! representation of the `[source.*]` value in Cargo configuration.
+//!
+//! [`Source`]: crate::core::Source
+//! [source replacement]: https://doc.rust-lang.org/nightly/cargo/reference/source-replacement.html
+
 pub use self::config::SourceConfigMap;
 pub use self::directory::DirectorySource;
 pub use self::git::GitSource;

src/cargo/sources/replaced.rs

@@ -5,13 +5,24 @@ use std::task::Poll;
 
 use anyhow::Context as _;
 
+/// A source that replaces one source with the other. This manages the [source
+/// replacement] feature.
+///
+/// The implementation is merely redirecting from the original to the replacement.
+///
+/// [source replacement]: https://doc.rust-lang.org/nightly/cargo/reference/source-replacement.html
 pub struct ReplacedSource<'cfg> {
+    /// The identifier of the original source.
     to_replace: SourceId,
+    /// The identifier of the new replacement source.
     replace_with: SourceId,
     inner: Box<dyn Source + 'cfg>,
 }
 
 impl<'cfg> ReplacedSource<'cfg> {
+    /// Creates a replaced source.
+    ///
+    /// The `src` argument is the new replacement source.
     pub fn new(
         to_replace: SourceId,
         replace_with: SourceId,