docs: doc comments for local registry

Author: weihanglo

src/cargo/sources/registry/local.rs

@@ -1,3 +1,5 @@
+//! Access to a regstiry on the local filesystem. See [`LocalRegistry`] for more.
+
 use crate::core::PackageId;
 use crate::sources::registry::{LoadResponse, MaybeLock, RegistryConfig, RegistryData};
 use crate::util::errors::CargoResult;
@@ -10,18 +12,68 @@ use std::path::Path;
 use std::task::Poll;
 
 /// A local registry is a registry that lives on the filesystem as a set of
-/// `.crate` files with an `index` directory in the same format as a remote
+/// `.crate` files with an `index` directory in the [same format] as a remote
 /// registry.
+///
+/// This type is primarily accessed through the [`RegistryData`] trait.
+///
+/// When a local registry is requested for a package, it simply looks into what
+/// its index has under the `index` directory. When [`LocalRegistry::download`]
+/// is called, a local registry verifies the checksum of the requested `.crate`
+/// tarball and then unpacks it to `$CARGO_HOME/.registry/src`.
+///
+/// > Note that there is a third-party subcommand [`cargo-local-registry`],
+/// > which happened to be developed by a former Cargo team member when local
+/// > registry was introduced. The tool is to ease the burden of maintaining
+/// > local registries. However, in general the Cargo team avoids recommending
+/// > any specific third-party crate. Just FYI.
+///
+/// [same format]: super#the-format-of-the-index
+/// [`cargo-local-registry`]: https://crates.io/crates/cargo-local-registry
+///
+/// # Filesystem hierarchy
+///
+/// Here is an example layout of a local registry on a local filesystem:
+///
+/// ```text
+/// [registry root]/
+/// ├── index/                      # registry index
+/// │  ├── an/
+/// │  │  └── yh/
+/// │  │     └── anyhow
+/// │  ├── ru/
+/// │  │  └── st/
+/// │  │     ├── rustls
+/// │  │     └── rustls-ffi
+/// │  └── se/
+/// │     └── mv/
+/// │        └── semver
+/// ├── anyhow-1.0.71.crate         # pre-downloaded crate tarballs
+/// ├── rustls-0.20.8.crate
+/// ├── rustls-ffi-0.8.2.crate
+/// └── semver-1.0.17.crate
+/// ```
+///
+/// For general concepts of registries, see the [module-level documentation](crate::sources::registry).
 pub struct LocalRegistry<'cfg> {
+    /// Path to the registry index.
     index_path: Filesystem,
+    /// Root path of this local registry.
     root: Filesystem,
+    /// Path where this local registry extract `.crate` tarballs to.
     src_path: Filesystem,
     config: &'cfg Config,
+    /// Whether this source has updated all package informations it may contain.
     updated: bool,
+    /// Disables status messages.
     quiet: bool,
 }
 
 impl<'cfg> LocalRegistry<'cfg> {
+    /// Creates a local registry at `root`.
+    ///
+    /// * `name` --- Name of a path segment where `.crate` tarballs are stored.
+    ///   Expect to be unique.
     pub fn new(root: &Path, config: &'cfg Config, name: &str) -> LocalRegistry<'cfg> {
         LocalRegistry {
             src_path: config.registry_source_path().join(name),