From 03d9c5b4e4e3c932dbf7369abac8e2b8d2e16804 Mon Sep 17 00:00:00 2001
From: Eric Huss <eric@huss.org>
Date: Thu, 29 Jun 2023 11:05:20 -0700
Subject: [PATCH] Add some more documentation for Source download functions.

---
 src/cargo/core/source/mod.rs | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/src/cargo/core/source/mod.rs b/src/cargo/core/source/mod.rs
index 6ca614d3430..2d1db1d5366 100644
--- a/src/cargo/core/source/mod.rs
+++ b/src/cargo/core/source/mod.rs
@@ -87,10 +87,25 @@ pub trait Source {
     /// If quiet, the source should not display any progress or status messages.
     fn set_quiet(&mut self, quiet: bool);
 
-    /// Fetches the full package for each name and version specified.
+    /// Starts the process to fetch a [`Package`] for the given [`PackageId`].
+    ///
+    /// If the source already has the package available on disk, then it
+    /// should return immediately with [`MaybePackage::Ready`] with the
+    /// [`Package`]. Otherwise it should return a [`MaybePackage::Download`]
+    /// to indicate the URL to download the package (this is for remote
+    /// registry sources only).
+    ///
+    /// In the case where [`MaybePackage::Download`] is returned, then the
+    /// package downloader will call [`Source::finish_download`] after the
+    /// download has finished.
     fn download(&mut self, package: PackageId) -> CargoResult<MaybePackage>;
 
-    /// Fetches the full package **immediately** for each name and version specified.
+    /// Convenience method used to **immediately** fetch a [`Package`] for the
+    /// given [`PackageId`].
+    ///
+    /// This may trigger a download if necessary. This should only be used
+    /// when a single package is needed (as in the case for `cargo install`).
+    /// Otherwise downloads should be batched together via [`PackageSet`].
     fn download_now(self: Box<Self>, package: PackageId, config: &Config) -> CargoResult<Package>
     where
         Self: std::marker::Sized,
@@ -102,7 +117,13 @@ pub trait Source {
         Ok(Package::clone(pkg))
     }
 
-    /// Finalizes the download contents of the given [`PackageId`] to a [`Package`].
+    /// Gives the source the downloaded `.crate` file.
+    ///
+    /// When a source has returned [`MaybePackage::Download`] in the
+    /// [`Source::download`] method, then this function will be called with
+    /// the results of the download of the given URL. The source is
+    /// responsible for saving to disk, and returning the appropriate
+    /// [`Package`].
     fn finish_download(&mut self, pkg_id: PackageId, contents: Vec<u8>) -> CargoResult<Package>;
 
     /// Generates a unique string which represents the fingerprint of the