Some tweaks

crates/uv-settings/src/settings.rs

@@ -40,13 +40,9 @@ pub struct Options {
     pub top_level: ResolverInstallerOptions,
     #[option_group]
     pub pip: Option<PipOptions>,
-    #[cfg_attr(
-        feature = "schemars",
-        schemars(
-            with = "Option<Vec<String>>",
-            description = "PEP 508 style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
-        )
-    )]
+
+    // NOTE(charlie): These fields are shared with `ToolUv` in
+    // `crates/uv-workspace/src/pyproject.rs`, and the documentation lives on that struct.
     pub override_dependencies: Option<Vec<Requirement<VerbatimParsedUrl>>>,
     pub constraint_dependencies: Option<Vec<Requirement<VerbatimParsedUrl>>>,
 

crates/uv-workspace/src/pyproject.rs

@@ -137,19 +137,25 @@ pub struct ToolUv {
         "#
     )]
     pub environments: Option<SupportedEnvironments>,
-    /// The project's override dependencies.
+    /// Overrides to apply when resolving the project's dependencies.
     ///
-    /// Overrides on dependencies must be described in PEP 508-style.
+    /// Overrides are used to force a specific version of a requirement to be installed, regardless
+    /// of the version specifiers declared by any other package, and regardless of whether choosing
+    /// that specific version would typically constitute an invalid resolution.
+    ///
+    /// While constraints are _additive_, in that they're combined with the requirements of the
+    /// constituent packages, overrides are _absolute_, in that they completely replace the
+    /// requirements of the constituent packages.
     ///
     /// !!! note
-    ///     When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid.   
-    ///     Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied.   
-    ///     The settings in the pyproject.toml of workspace members and in uv.toml are ignored.   
+    ///     In `uv lock`, `uv sync`, and `uv run`, uv will only read `override-dependencies` from
+    ///     the `pyproject.toml` at the workspace root, and will ignore any declarations in other
+    ///     workspace members or `uv.toml` files.
     #[cfg_attr(
         feature = "schemars",
         schemars(
             with = "Option<Vec<String>>",
-            description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
+            description = "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`."
         )
     )]
     #[option(
@@ -160,21 +166,24 @@ pub struct ToolUv {
         "#
     )]
     pub override_dependencies: Option<Vec<pep508_rs::Requirement<VerbatimParsedUrl>>>,
+    /// Constraints to apply when resolving the project's dependencies.
+    ///
+    /// Constraints are used to restrict the versions of dependencies that are selected during
+    /// resolution. However, including a package as a constraint will _not_ trigger installation of
+    /// the package on its own; instead, the package must be requested elsewhere in the project's
+    /// first-party or transitive dependencies.
+    ///
+    /// !!! note
+    ///     In `uv lock`, `uv sync`, and `uv run`, uv will only read `constraint-dependencies` from
+    ///     the `pyproject.toml` at the workspace root, and will ignore any declarations in other
+    ///     workspace members or `uv.toml` files.
     #[cfg_attr(
         feature = "schemars",
         schemars(
             with = "Option<Vec<String>>",
-            description = "PEP 508-style requirements, e.g. `ruff==0.5.0`, or `ruff @ https://...`."
+            description = "PEP 508-style requirements, e.g., `ruff==0.5.0`, or `ruff @ https://...`."
         )
     )]
-    /// The project's constraint dependencies.
-    ///
-    /// Constraint on dependencies must be described in PEP 508-style.
-    ///
-    /// !!! note
-    ///     When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid.   
-    ///     Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied.   
-    ///     The settings in the pyproject.toml of workspace members and in uv.toml are ignored.   
     #[option(
         default = r#"[]"#,
         value_type = "list[str]",

docs/reference/settings.md

@@ -170,14 +170,17 @@ specified as `KEY=VALUE` pairs.
 
 #### [`constraint-dependencies`](#constraint-dependencies) {: #constraint-dependencies }
 
-The project's constraint dependencies.
+Constraints to apply when resolving the project's dependencies.
 
-Constraint on dependencies must be described in PEP 508-style.
+Constraints are used to restrict the versions of dependencies that are selected during
+resolution. However, including a package as a constraint will _not_ trigger installation of
+the package on its own; instead, the package must be requested elsewhere in the project's
+first-party or transitive dependencies.
 
 !!! note
-    When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid.   
-    Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied.   
-    The settings in the pyproject.toml of workspace members and in uv.toml are ignored.   
+    In `uv lock`, `uv sync`, and `uv run`, uv will only read `constraint-dependencies` from
+    the `pyproject.toml` at the workspace root, and will ignore any declarations in other
+    workspace members or `uv.toml` files.
 
 **Default value**: `[]`
 
@@ -806,14 +809,20 @@ Disable network access, relying only on locally cached data and locally availabl
 
 #### [`override-dependencies`](#override-dependencies) {: #override-dependencies }
 
-The project's override dependencies.
+Overrides to apply when resolving the project's dependencies.
 
-Overrides on dependencies must be described in PEP 508-style.
+Overrides are used to force a specific version of a requirement to be installed, regardless
+of the version specifiers declared by any other package, and regardless of whether choosing
+that specific version would typically constitute an invalid resolution.
+
+While constraints are _additive_, in that they're combined with the requirements of the
+constituent packages, overrides are _absolute_, in that they completely replace the
+requirements of the constituent packages.
 
 !!! note
-    When using project interfaces like `uv lock`, only the settings in the pyproject.toml are valid.   
-    Specifically, when using a workspace, only the settings in the pyproject.toml located at the workspace root are applied.   
-    The settings in the pyproject.toml of workspace members and in uv.toml are ignored.   
+    In `uv lock`, `uv sync`, and `uv run`, uv will only read `override-dependencies` from
+    the `pyproject.toml` at the workspace root, and will ignore any declarations in other
+    workspace members or `uv.toml` files.
 
 **Default value**: `[]`