Improve Urls docs

crates/uv-resolver/src/resolver/urls.rs

@@ -18,12 +18,18 @@ use crate::{DependencyMode, Manifest, ResolveError};
 /// dependencies). They take precedence over requirements by version (except for the special case
 /// where we are in a fork that doesn't use any of the URL(s) used in other forks). Each fork may
 /// only use a single URL.
+///
+/// This type contains all URLs without checking, the validation happens in
+/// [`crate::fork_urls::ForkUrls`].
 #[derive(Debug, Default)]
 pub(crate) struct Urls {
-    /// URL requirements in the root package, from other URL requirements or from constraints.
-    regular: FxHashMap<PackageName, Vec<VerbatimParsedUrl>>,
-    /// URL requirements in overrides.
+    /// URL requirements in overrides. There can only be a single URL per package in overrides
+    /// (since it replaces all other URLs), and an override URL replaces all requirements and
+    /// constraints URLs.
     overrides: FxHashMap<PackageName, VerbatimParsedUrl>,
+    /// URLs from regular requirements or from constraints. There can be multiple URLs for the same
+    /// package as long as they are in different forks.
+    regular: FxHashMap<PackageName, Vec<VerbatimParsedUrl>>,
 }
 
 impl Urls {
@@ -36,7 +42,7 @@ impl Urls {
         let mut urls: FxHashMap<PackageName, Vec<VerbatimParsedUrl>> = FxHashMap::default();
         let mut overrides: FxHashMap<PackageName, VerbatimParsedUrl> = FxHashMap::default();
 
-        // Add all direct requirements and constraints. If there are any conflicts, return an error.
+        // Add all direct regular requirements and constraints URL.
         for requirement in manifest.requirements_no_overrides(markers, dependencies) {
             let Some(url) = requirement.source.to_verbatim_parsed_url() else {
                 // Registry requirement
@@ -68,13 +74,16 @@ impl Urls {
             }
         }
 
+        // Add all URLs from overrides. If there is an override URL, all other URLs from
+        // requirements and constraints are moot and will be removed.
         for requirement in manifest.overrides(markers, dependencies) {
             let Some(url) = requirement.source.to_verbatim_parsed_url() else {
                 // Registry requirement
                 continue;
             };
-            // With an override `anyio==0.0.0` and a requirements.txt entry `./anyio`, we still use
-            // the URL. See `allow_recursive_url_local_path_override_constraint`
+            // We only clear for non-URL overrides, since e.g. with an override `anyio==0.0.0` and
+            // a requirements.txt entry `./anyio`, we still use the URL. See
+            // `allow_recursive_url_local_path_override_constraint`.
             urls.remove(&requirement.name);
             let previous = overrides.insert(requirement.name.clone(), url.clone());
             if let Some(previous) = previous {