Auto merge of #13698 - weihanglo:registry-doc, r=ehuss

doc: comments on `PackageRegistry`

src/cargo/core/registry.rs

@@ -1,3 +1,14 @@
+//! Types that hold source information for a group of packages.
+//!
+//! The primary type you're looking for is [`PackageRegistry`]. It is an
+//! abstraction over multiple [`Source`]s. [`PackageRegistry`] also implements
+//! the [`Registry`] trait, allowing a dependency resolver to query necessary
+//! package metadata (i.e., [Summary]) from it.
+//!
+//! Not to be confused with [`crate::sources::registry`] and [`crate::ops::registry`].
+//! The former is just one kind of source,
+//! while the latter involves operations on the registry Web API.
+
 use std::collections::{HashMap, HashSet};
 use std::task::{ready, Poll};
 
@@ -15,9 +26,15 @@ use anyhow::{bail, Context as _};
 use tracing::{debug, trace};
 use url::Url;
 
-/// Source of information about a group of packages.
+/// An abstraction provides a set of methods for querying source information
+/// about a group of packages, without leaking too much implementation details
+/// of the actual registry.
+///
+/// As of 2024-04, only [`PackageRegistry`] and `MyRegistry` in resolver-tests
+/// are found implementing this.
 ///
-/// See also `core::Source`.
+/// See also the [`Source`] trait, as many of the methods here mirror and
+/// abstract over its functionalities.
 pub trait Registry {
     /// Attempt to find the packages that match a dependency request.
     fn query(
@@ -27,6 +44,8 @@ pub trait Registry {
         f: &mut dyn FnMut(IndexSummary),
     ) -> Poll<CargoResult<()>>;
 
+    /// Gathers the result from [`Registry::query`] as a list of [`IndexSummary`] items
+    /// when they become available.
     fn query_vec(
         &mut self,
         dep: &Dependency,
@@ -36,34 +55,40 @@ pub trait Registry {
         self.query(dep, kind, &mut |s| ret.push(s)).map_ok(|()| ret)
     }
 
+    /// Gets the description of a source, to provide useful messages.
     fn describe_source(&self, source: SourceId) -> String;
+
+    /// Checks if a source is replaced with some other source.
     fn is_replaced(&self, source: SourceId) -> bool;
 
-    /// Block until all outstanding Poll::Pending requests are Poll::Ready.
+    /// Block until all outstanding [`Poll::Pending`] requests are [`Poll::Ready`].
     fn block_until_ready(&mut self) -> CargoResult<()>;
 }
 
 /// This structure represents a registry of known packages. It internally
-/// contains a number of `Box<Source>` instances which are used to load a
-/// `Package` from.
+/// contains a number of [`Source`] instances which are used to load a
+/// [`Package`] from.
 ///
 /// The resolution phase of Cargo uses this to drive knowledge about new
-/// packages as well as querying for lists of new packages. It is here that
-/// sources are updated (e.g., network operations) and overrides are
-/// handled.
+/// packages as well as querying for lists of new packages.
+/// It is here that sources are updated (e.g., network operations) and
+/// overrides/patches are handled.
 ///
 /// The general idea behind this registry is that it is centered around the
-/// `SourceMap` structure, contained within which is a mapping of a `SourceId` to
-/// a `Source`. Each `Source` in the map has been updated (using network
+/// [`SourceMap`] structure, contained within which is a mapping of a [`SourceId`]
+/// to a [`Source`]. Each [`Source`] in the map has been updated (using network
 /// operations if necessary) and is ready to be queried for packages.
+///
+/// [`Package`]: crate::core::Package
 pub struct PackageRegistry<'gctx> {
     gctx: &'gctx GlobalContext,
     sources: SourceMap<'gctx>,
 
-    // A list of sources which are considered "overrides" which take precedent
-    // when querying for packages.
+    /// A list of sources which are considered "path-overrides" which take
+    /// precedent when querying for packages.
     overrides: Vec<SourceId>,
 
+    /// Use for tracking sources that are already loaded into the registry.
     // Note that each SourceId does not take into account its `precise` field
     // when hashing or testing for equality. When adding a new `SourceId`, we
     // want to avoid duplicates in the `SourceMap` (to prevent re-updating the
@@ -81,11 +106,17 @@ pub struct PackageRegistry<'gctx> {
     // what exactly the key is.
     source_ids: HashMap<SourceId, (SourceId, Kind)>,
 
+    /// This is constructed via [`PackageRegistry::register_lock`].
+    /// See also [`LockedMap`].
     locked: LockedMap,
+    /// A group of packages tha allows to use even when yanked.
     yanked_whitelist: HashSet<PackageId>,
     source_config: SourceConfigMap<'gctx>,
 
     patches: HashMap<CanonicalUrl, Vec<Summary>>,
+    /// Whether patches are locked. That is, they are available to resolution.
+    ///
+    /// See [`PackageRegistry::lock_patches`] and [`PackageRegistry::patch`] for more.
     patches_locked: bool,
     patches_available: HashMap<CanonicalUrl, Vec<PackageId>>,
 }
@@ -110,14 +141,23 @@ type LockedMap = HashMap<
     Vec<(PackageId, Vec<PackageId>)>,
 >;
 
+/// Kinds of sources a [`PackageRegistry`] has loaded.
 #[derive(PartialEq, Eq, Clone, Copy)]
 enum Kind {
+    /// A source from a [path override].
+    ///
+    /// [path overrides]: https://doc.rust-lang.org/nightly/cargo/reference/overriding-dependencies.html#paths-overrides
     Override,
+    /// A source that is locked and not going to change.
+    ///
+    /// For example, sources of workspace members are loaded during the
+    /// workspace initialization, so not allowed to change.
     Locked,
+    /// A source that is not locked nor a path-override.
     Normal,
 }
 
-/// Argument to `PackageRegistry::patch` which is information about a `[patch]`
+/// Argument to [`PackageRegistry::patch`] which is information about a `[patch]`
 /// directive that we found in a lockfile, if present.
 pub struct LockedPatchDependency {
     /// The original `Dependency` directive, except "locked" so it's version
@@ -154,6 +194,8 @@ impl<'gctx> PackageRegistry<'gctx> {
         PackageSet::new(package_ids, self.sources, self.gctx)
     }
 
+    /// Ensures the [`Source`] of the given [`SourceId`] is loaded.
+    /// If not, this will block until the source is ready.
     fn ensure_loaded(&mut self, namespace: SourceId, kind: Kind) -> CargoResult<()> {
         match self.source_ids.get(&namespace) {
             // We've previously loaded this source, and we've already locked it,
@@ -203,21 +245,28 @@ impl<'gctx> PackageRegistry<'gctx> {
         Ok(())
     }
 
+    /// Adds a source which will be locked.
+    /// Useful for path sources such as the source of a workspace member.
     pub fn add_preloaded(&mut self, source: Box<dyn Source + 'gctx>) {
         self.add_source(source, Kind::Locked);
     }
 
+    /// Adds a source to the registry.
     fn add_source(&mut self, source: Box<dyn Source + 'gctx>, kind: Kind) {
         let id = source.source_id();
         self.sources.insert(source);
         self.source_ids.insert(id, (id, kind));
     }
 
+    /// Adds a source from a [path override].
+    ///
+    /// [path override]: https://doc.rust-lang.org/nightly/cargo/reference/overriding-dependencies.html#paths-overrides
     pub fn add_override(&mut self, source: Box<dyn Source + 'gctx>) {
         self.overrides.push(source.source_id());
         self.add_source(source, Kind::Override);
     }
 
+    /// Allows a group of package to be available to query even if they are yanked.
     pub fn add_to_yanked_whitelist(&mut self, iter: impl Iterator<Item = PackageId>) {
         let pkgs = iter.collect::<Vec<_>>();
         for (_, source) in self.sources.sources_mut() {
@@ -232,6 +281,8 @@ impl<'gctx> PackageRegistry<'gctx> {
         self.locked = HashMap::new();
     }
 
+    /// Registers one "locked package" to the registry, for guiding the
+    /// dependency resolution. See [`LockedMap`] for more.
     pub fn register_lock(&mut self, id: PackageId, deps: Vec<PackageId>) {
         trace!("register_lock: {}", id);
         for dep in deps.iter() {
@@ -262,8 +313,8 @@ impl<'gctx> PackageRegistry<'gctx> {
     /// entries in `Cargo.lock`.
     ///
     /// Note that the patch list specified here *will not* be available to
-    /// `query` until `lock_patches` is called below, which should be called
-    /// once all patches have been added.
+    /// [`Registry::query`] until [`PackageRegistry::lock_patches`] is called
+    /// below, which should be called once all patches have been added.
     ///
     /// The return value is a `Vec` of patches that should *not* be locked.
     /// This happens when the patch is locked, but the patch has been updated
@@ -434,13 +485,8 @@ impl<'gctx> PackageRegistry<'gctx> {
         Ok(unlock_patches)
     }
 
-    /// Lock all patch summaries added via `patch`, making them available to
-    /// resolution via `query`.
-    ///
-    /// This function will internally `lock` each summary added via `patch`
-    /// above now that the full set of `patch` packages are known. This'll allow
-    /// us to correctly resolve overridden dependencies between patches
-    /// hopefully!
+    /// Lock all patch summaries added via [`patch`](Self::patch),
+    /// making them available to resolution via [`Registry::query`].
     pub fn lock_patches(&mut self) {
         assert!(!self.patches_locked);
         for summaries in self.patches.values_mut() {
@@ -452,14 +498,16 @@ impl<'gctx> PackageRegistry<'gctx> {
         self.patches_locked = true;
     }
 
-    /// Gets all patches grouped by the source URLS they are going to patch.
+    /// Gets all patches grouped by the source URLs they are going to patch.
     ///
     /// These patches are mainly collected from [`patch`](Self::patch).
     /// They might not be the same as patches actually used during dependency resolving.
     pub fn patches(&self) -> &HashMap<CanonicalUrl, Vec<Summary>> {
         &self.patches
     }
 
+    /// Loads the [`Source`] for a given [`SourceId`] to this registry, making
+    /// them available to resolution.
     fn load(&mut self, source_id: SourceId, kind: Kind) -> CargoResult<()> {
         debug!("loading source {}", source_id);
         let source = self
@@ -488,6 +536,7 @@ impl<'gctx> PackageRegistry<'gctx> {
         Ok(())
     }
 
+    /// Queries path overrides from this registry.
     fn query_overrides(&mut self, dep: &Dependency) -> Poll<CargoResult<Option<IndexSummary>>> {
         for &s in self.overrides.iter() {
             let src = self.sources.get_mut(s).unwrap();
@@ -753,6 +802,7 @@ impl<'gctx> Registry for PackageRegistry<'gctx> {
     }
 }
 
+/// See [`PackageRegistry::lock`].
 fn lock(
     locked: &LockedMap,
     patches: &HashMap<CanonicalUrl, Vec<PackageId>>,