Auto merge of #12319 - ehuss:more-source-docs, r=epage

Add some more documentation for Source download functions.

This adds a little more of a description to the download functions of the `Source` trait, since the behavior wasn't clear to me (and I often forget how these work).

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