Improve documentation for InvocationStrategy

Author: Veykril

crates/project-model/src/build_dependencies.rs

@@ -82,17 +82,16 @@ impl WorkspaceBuildScripts {
         config: &CargoConfig,
         workspaces: &[&CargoWorkspace],
         progress: &dyn Fn(String),
-        workspace_root: &AbsPathBuf,
+        working_directory: &AbsPathBuf,
     ) -> io::Result<Vec<WorkspaceBuildScripts>> {
         assert_eq!(config.invocation_strategy, InvocationStrategy::Once);
 
-        let current_dir = workspace_root;
         let cmd = Self::build_command(
             config,
             &Default::default(),
             // This is not gonna be used anyways, so just construct a dummy here
-            &ManifestPath::try_from(workspace_root.clone()).unwrap(),
-            current_dir,
+            &ManifestPath::try_from(working_directory.clone()).unwrap(),
+            working_directory,
             &Sysroot::empty(),
         )?;
         // NB: Cargo.toml could have been modified between `cargo metadata` and

crates/project-model/src/workspace.rs

@@ -459,7 +459,7 @@ impl ProjectWorkspace {
         workspaces: &[ProjectWorkspace],
         config: &CargoConfig,
         progress: &dyn Fn(String),
-        workspace_root: &AbsPathBuf,
+        working_directory: &AbsPathBuf,
     ) -> Vec<anyhow::Result<WorkspaceBuildScripts>> {
         if matches!(config.invocation_strategy, InvocationStrategy::PerWorkspace)
             || config.run_build_script_command.is_none()
@@ -474,13 +474,16 @@ impl ProjectWorkspace {
                 _ => None,
             })
             .collect();
-        let outputs =
-            &mut match WorkspaceBuildScripts::run_once(config, &cargo_ws, progress, workspace_root)
-            {
-                Ok(it) => Ok(it.into_iter()),
-                // io::Error is not Clone?
-                Err(e) => Err(sync::Arc::new(e)),
-            };
+        let outputs = &mut match WorkspaceBuildScripts::run_once(
+            config,
+            &cargo_ws,
+            progress,
+            working_directory,
+        ) {
+            Ok(it) => Ok(it.into_iter()),
+            // io::Error is not Clone?
+            Err(e) => Err(sync::Arc::new(e)),
+        };
 
         workspaces
             .iter()

crates/rust-analyzer/src/config.rs

@@ -81,8 +81,10 @@ config_data! {
         /// Run build scripts (`build.rs`) for more precise code analysis.
         cargo_buildScripts_enable: bool  = true,
         /// Specifies the invocation strategy to use when running the build scripts command.
-        /// If `per_workspace` is set, the command will be executed for each workspace.
-        /// If `once` is set, the command will be executed once.
+        /// If `per_workspace` is set, the command will be executed for each Rust workspace with the
+        /// workspace as the working directory.
+        /// If `once` is set, the command will be executed once with the opened project as the
+        /// working directory.
         /// This config only has an effect when `#rust-analyzer.cargo.buildScripts.overrideCommand#`
         /// is set.
         cargo_buildScripts_invocationStrategy: InvocationStrategy = InvocationStrategy::PerWorkspace,
@@ -3154,8 +3156,8 @@ fn field_props(field: &str, ty: &str, doc: &[&str], default: &str) -> serde_json
             "type": "string",
             "enum": ["per_workspace", "once"],
             "enumDescriptions": [
-                "The command will be executed for each workspace.",
-                "The command will be executed once."
+                "The command will be executed for each Rust workspace with the workspace as the working directory.",
+                "The command will be executed once with the opened project as the working directory."
             ],
         },
         "Option<CheckOnSaveTargets>" => set! {

docs/user/generated_config.adoc

@@ -49,8 +49,10 @@ Run build scripts (`build.rs`) for more precise code analysis.
 +
 --
 Specifies the invocation strategy to use when running the build scripts command.
-If `per_workspace` is set, the command will be executed for each workspace.
-If `once` is set, the command will be executed once.
+If `per_workspace` is set, the command will be executed for each Rust workspace with the
+workspace as the working directory.
+If `once` is set, the command will be executed once with the opened project as the
+working directory.
 This config only has an effect when `#rust-analyzer.cargo.buildScripts.overrideCommand#`
 is set.
 --

editors/code/package.json

@@ -667,16 +667,16 @@
                 "title": "cargo",
                 "properties": {
                     "rust-analyzer.cargo.buildScripts.invocationStrategy": {
-                        "markdownDescription": "Specifies the invocation strategy to use when running the build scripts command.\nIf `per_workspace` is set, the command will be executed for each workspace.\nIf `once` is set, the command will be executed once.\nThis config only has an effect when `#rust-analyzer.cargo.buildScripts.overrideCommand#`\nis set.",
+                        "markdownDescription": "Specifies the invocation strategy to use when running the build scripts command.\nIf `per_workspace` is set, the command will be executed for each Rust workspace with the\nworkspace as the working directory.\nIf `once` is set, the command will be executed once with the opened project as the\nworking directory.\nThis config only has an effect when `#rust-analyzer.cargo.buildScripts.overrideCommand#`\nis set.",
                         "default": "per_workspace",
                         "type": "string",
                         "enum": [
                             "per_workspace",
                             "once"
                         ],
                         "enumDescriptions": [
-                            "The command will be executed for each workspace.",
-                            "The command will be executed once."
+                            "The command will be executed for each Rust workspace with the workspace as the working directory.",
+                            "The command will be executed once with the opened project as the working directory."
                         ]
                     }
                 }
@@ -959,8 +959,8 @@
                             "once"
                         ],
                         "enumDescriptions": [
-                            "The command will be executed for each workspace.",
-                            "The command will be executed once."
+                            "The command will be executed for each Rust workspace with the workspace as the working directory.",
+                            "The command will be executed once with the opened project as the working directory."
                         ]
                     }
                 }