Auto merge of rust-lang#12687 - flodiebold:override-docs, r=flodiebold

Improve documentation for `buildScripts.overrideCommand` / `checkOnSave.overrideCommand`

Author: bors

crates/rust-analyzer/src/config.rs

@@ -69,7 +69,7 @@ config_data! {
         cargo_buildScripts_enable: bool  = "true",
         /// Override the command rust-analyzer uses to run build scripts and
         /// build procedural macros. The command is required to output json
-        /// and should therefor include `--message-format=json` or a similar
+        /// and should therefore include `--message-format=json` or a similar
         /// option.
         ///
         /// By default, a cargo invocation will be constructed for the configured
@@ -81,7 +81,7 @@ config_data! {
         /// .
         cargo_buildScripts_overrideCommand: Option<Vec<String>> = "null",
         /// Use `RUSTC_WRAPPER=rust-analyzer` when running build scripts to
-        /// avoid compiling unnecessary things.
+        /// avoid checking unnecessary things.
         cargo_buildScripts_useRustcWrapper: bool = "true",
         /// List of features to activate.
         ///
@@ -107,15 +107,18 @@ config_data! {
         /// List of features to activate. Defaults to
         /// `#rust-analyzer.cargo.features#`.
         ///
-        /// Set to `"all"` to pass `--all-features` to cargo.
+        /// Set to `"all"` to pass `--all-features` to Cargo.
         checkOnSave_features: Option<CargoFeatures>      = "null",
-        /// Whether to pass `--no-default-features` to cargo. Defaults to
+        /// Whether to pass `--no-default-features` to Cargo. Defaults to
         /// `#rust-analyzer.cargo.noDefaultFeatures#`.
         checkOnSave_noDefaultFeatures: Option<bool>      = "null",
-        /// Override the command rust-analyzer uses to  run build scripts and
-        /// build procedural macros. The command is required to output json
-        /// and should therefor include `--message-format=json` or a similar
-        /// option.
+        /// Override the command rust-analyzer uses instead of `cargo check` for
+        /// diagnostics on save. The command is required to output json and
+        /// should therefor include `--message-format=json` or a similar option.
+        ///
+        /// If you're changing this because you're using some tool wrapping
+        /// Cargo, you might also want to change
+        /// `#rust-analyzer.cargo.buildScripts.overrideCommand#`.
         ///
         /// An example command would be:
         ///

docs/user/generated_config.adoc

@@ -29,7 +29,7 @@ Run build scripts (`build.rs`) for more precise code analysis.
 --
 Override the command rust-analyzer uses to run build scripts and
 build procedural macros. The command is required to output json
-and should therefor include `--message-format=json` or a similar
+and should therefore include `--message-format=json` or a similar
 option.
 
 By default, a cargo invocation will be constructed for the configured
@@ -44,7 +44,7 @@ cargo check --quiet --workspace --message-format=json --all-targets
 +
 --
 Use `RUSTC_WRAPPER=rust-analyzer` when running build scripts to
-avoid compiling unnecessary things.
+avoid checking unnecessary things.
 --
 [[rust-analyzer.cargo.features]]rust-analyzer.cargo.features (default: `[]`)::
 +
@@ -99,21 +99,24 @@ Extra arguments for `cargo check`.
 List of features to activate. Defaults to
 `#rust-analyzer.cargo.features#`.
 
-Set to `"all"` to pass `--all-features` to cargo.
+Set to `"all"` to pass `--all-features` to Cargo.
 --
 [[rust-analyzer.checkOnSave.noDefaultFeatures]]rust-analyzer.checkOnSave.noDefaultFeatures (default: `null`)::
 +
 --
-Whether to pass `--no-default-features` to cargo. Defaults to
+Whether to pass `--no-default-features` to Cargo. Defaults to
 `#rust-analyzer.cargo.noDefaultFeatures#`.
 --
 [[rust-analyzer.checkOnSave.overrideCommand]]rust-analyzer.checkOnSave.overrideCommand (default: `null`)::
 +
 --
-Override the command rust-analyzer uses to  run build scripts and
-build procedural macros. The command is required to output json
-and should therefor include `--message-format=json` or a similar
-option.
+Override the command rust-analyzer uses instead of `cargo check` for
+diagnostics on save. The command is required to output json and
+should therefor include `--message-format=json` or a similar option.
+
+If you're changing this because you're using some tool wrapping
+Cargo, you might also want to change
+`#rust-analyzer.cargo.buildScripts.overrideCommand#`.
 
 An example command would be:
 

editors/code/package.json

@@ -375,6 +375,11 @@
                     "default": {},
                     "markdownDescription": "Optional settings passed to the debug engine. Example: `{ \"lldb\": { \"terminal\":\"external\"} }`"
                 },
+                "rust-analyzer.restartServerOnConfigChange": {
+                    "markdownDescription": "Whether to restart the server automatically when certain settings that require a restart are changed.",
+                    "default": false,
+                    "type": "boolean"
+                },
                 "$generated-start": {},
                 "rust-analyzer.assist.expressionFillDefault": {
                     "markdownDescription": "Placeholder expression to use for missing expressions in assists.",
@@ -412,7 +417,7 @@
                     "type": "boolean"
                 },
                 "rust-analyzer.cargo.buildScripts.overrideCommand": {
-                    "markdownDescription": "Override the command rust-analyzer uses to run build scripts and\nbuild procedural macros. The command is required to output json\nand should therefor include `--message-format=json` or a similar\noption.\n\nBy default, a cargo invocation will be constructed for the configured\ntargets and features, with the following base command line:\n\n```bash\ncargo check --quiet --workspace --message-format=json --all-targets\n```\n.",
+                    "markdownDescription": "Override the command rust-analyzer uses to run build scripts and\nbuild procedural macros. The command is required to output json\nand should therefore include `--message-format=json` or a similar\noption.\n\nBy default, a cargo invocation will be constructed for the configured\ntargets and features, with the following base command line:\n\n```bash\ncargo check --quiet --workspace --message-format=json --all-targets\n```\n.",
                     "default": null,
                     "type": [
                         "null",
@@ -423,7 +428,7 @@
                     }
                 },
                 "rust-analyzer.cargo.buildScripts.useRustcWrapper": {
-                    "markdownDescription": "Use `RUSTC_WRAPPER=rust-analyzer` when running build scripts to\navoid compiling unnecessary things.",
+                    "markdownDescription": "Use `RUSTC_WRAPPER=rust-analyzer` when running build scripts to\navoid checking unnecessary things.",
                     "default": true,
                     "type": "boolean"
                 },
@@ -500,7 +505,7 @@
                     }
                 },
                 "rust-analyzer.checkOnSave.features": {
-                    "markdownDescription": "List of features to activate. Defaults to\n`#rust-analyzer.cargo.features#`.\n\nSet to `\"all\"` to pass `--all-features` to cargo.",
+                    "markdownDescription": "List of features to activate. Defaults to\n`#rust-analyzer.cargo.features#`.\n\nSet to `\"all\"` to pass `--all-features` to Cargo.",
                     "default": null,
                     "anyOf": [
                         {
@@ -524,15 +529,15 @@
                     ]
                 },
                 "rust-analyzer.checkOnSave.noDefaultFeatures": {
-                    "markdownDescription": "Whether to pass `--no-default-features` to cargo. Defaults to\n`#rust-analyzer.cargo.noDefaultFeatures#`.",
+                    "markdownDescription": "Whether to pass `--no-default-features` to Cargo. Defaults to\n`#rust-analyzer.cargo.noDefaultFeatures#`.",
                     "default": null,
                     "type": [
                         "null",
                         "boolean"
                     ]
                 },
                 "rust-analyzer.checkOnSave.overrideCommand": {
-                    "markdownDescription": "Override the command rust-analyzer uses to    run build scripts and\nbuild procedural macros. The command is required to output json\nand should therefor include `--message-format=json` or a similar\noption.\n\nAn example command would be:\n\n```bash\ncargo check --workspace --message-format=json --all-targets\n```\n.",
+                    "markdownDescription": "Override the command rust-analyzer uses instead of `cargo check` for\ndiagnostics on save. The command is required to output json and\nshould therefor include `--message-format=json` or a similar option.\n\nIf you're changing this because you're using some tool wrapping\nCargo, you might also want to change\n`#rust-analyzer.cargo.buildScripts.overrideCommand#`.\n\nAn example command would be:\n\n```bash\ncargo check --workspace --message-format=json --all-targets\n```\n.",
                     "default": null,
                     "type": [
                         "null",
@@ -1116,11 +1121,6 @@
                         "Search in current workspace and dependencies."
                     ]
                 },
-                "rust-analyzer.restartServerOnConfigChange": {
-                    "markdownDescription": "Whether to restart the server automatically when certain settings that require a restart are changed.",
-                    "default": false,
-                    "type": "boolean"
-                },
                 "$generated-end": {}
             }
         },