Fix up config docs

5 files changed, 93 insertions, 51 deletions

diff --git a/crates/hir-expand/src/builtin_fn_macro.rs b/crates/hir-expand/src/builtin_fn_macro.rs
index 8d2352f06ed..aa09912f302 100644
--- a/crates/hir-expand/src/builtin_fn_macro.rs
+++ b/crates/hir-expand/src/builtin_fn_macro.rs
@@ -641,7 +641,7 @@ fn env_expand(
         // unnecessary diagnostics for eg. `CARGO_PKG_NAME`.
         if key == "OUT_DIR" {
             err = Some(ExpandError::Other(
-                r#"`OUT_DIR` not set, enable "run build scripts" to fix"#.into(),
+                r#"`OUT_DIR` not set, enable "build scripts" to fix"#.into(),
             ));
         }
 
diff --git a/crates/ide-diagnostics/src/handlers/macro_error.rs b/crates/ide-diagnostics/src/handlers/macro_error.rs
index a5bfb302d5e..53d0131e02d 100644
--- a/crates/ide-diagnostics/src/handlers/macro_error.rs
+++ b/crates/ide-diagnostics/src/handlers/macro_error.rs
@@ -111,7 +111,7 @@ macro_rules! env { () => {} }
 macro_rules! concat { () => {} }
 
   include!(concat!(env!("OUT_DIR"), "/out.rs"));
-//^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ error: `OUT_DIR` not set, enable "run build scripts" to fix
+//^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ error: `OUT_DIR` not set, enable "build scripts" to fix
 "#,
         );
     }
@@ -161,7 +161,7 @@ fn main() {
   //^^^^^^^^^^^^^ error: could not convert tokens
 
     env!("OUT_DIR");
-  //^^^^^^^^^^^^^^^ error: `OUT_DIR` not set, enable "run build scripts" to fix
+  //^^^^^^^^^^^^^^^ error: `OUT_DIR` not set, enable "build scripts" to fix
 
     compile_error!("compile_error works");
   //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ error: compile_error works
diff --git a/crates/rust-analyzer/src/config.rs b/crates/rust-analyzer/src/config.rs
index c7f939f36aa..75c1a31e934 100644
--- a/crates/rust-analyzer/src/config.rs
+++ b/crates/rust-analyzer/src/config.rs
@@ -52,7 +52,7 @@ use crate::{
 // parsing the old name.
 config_data! {
     struct ConfigData {
-        /// Placeholder for missing expressions in assists.
+        /// Placeholder expression to use for missing expressions in assists.
         assist_expressionFillDefault: ExprFillDefaultDef              = "\"todo\"",
 
         /// Automatically refresh project info via `cargo metadata` on
@@ -60,16 +60,27 @@ config_data! {
         cargo_autoreload: bool           = "true",
         /// Run build scripts (`build.rs`) for more precise code analysis.
         cargo_buildScripts_enable: bool  = "true",
-        /// Advanced option, fully override the command rust-analyzer uses to
-        /// run build scripts and build procedural macros. The command should
-        /// include `--message-format=json` or a similar option.
+        /// 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.
+        ///
+        /// By default, a cargo invocation will be constructed for the configured
+        /// targets and features, with the following base command line:
+        ///
+        /// ```bash
+        /// cargo check --quiet --workspace --message-format=json --all-targets
+        /// ```
+        /// .
         cargo_buildScripts_overrideCommand: Option<Vec<String>> = "null",
         /// Use `RUSTC_WRAPPER=rust-analyzer` when running build scripts to
         /// avoid compiling unnecessary things.
         cargo_buildScripts_useRustcWrapper: bool = "true",
-        /// List of features to activate. Set to `"all"` to pass `--all-features` to cargo.
+        /// List of features to activate.
+        ///
+        /// Set this to `"all"` to pass `--all-features` to cargo.
         cargo_features: CargoFeatures      = "[]",
-        /// Do not activate the `default` feature.
+        /// Whether to pass `--no-default-features` to cargo.
         cargo_noDefaultFeatures: bool    = "false",
         /// Internal config for debugging, disables loading of sysroot crates.
         cargo_noSysroot: bool            = "false",
@@ -87,13 +98,23 @@ config_data! {
         /// Extra arguments for `cargo check`.
         checkOnSave_extraArgs: Vec<String>               = "[]",
         /// List of features to activate. Defaults to
-        /// `#rust-analyzer.cargo.features#`. Set to `"all"` to pass `--all-features` to cargo.
+        /// `#rust-analyzer.cargo.features#`.
+        ///
+        /// Set to `"all"` to pass `--all-features` to cargo.
         checkOnSave_features: Option<CargoFeatures>      = "null",
         /// Do not activate the `default` feature.
         checkOnSave_noDefaultFeatures: Option<bool>      = "null",
-        /// Advanced option, fully override the command rust-analyzer uses for
-        /// checking. The command should include `--message-format=json` or
-        /// similar option.
+        /// 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.
+        ///
+        /// An example command would be:
+        ///
+        /// ```bash
+        /// cargo check --workspace --message-format=json --all-targets
+        /// ```
+        /// .
         checkOnSave_overrideCommand: Option<Vec<String>> = "null",
         /// Check for a specific target. Defaults to
         /// `#rust-analyzer.cargo.target#`.
@@ -183,13 +204,13 @@ config_data! {
         /// Controls file watching implementation.
         files_watcher: String = "\"client\"",
 
-        /// Enables highlighting of related references while hovering your mouse `break`, `loop`, `while`, or `for` keywords.
+        /// Enables highlighting of related references while the cursor is on `break`, `loop`, `while`, or `for` keywords.
         highlightRelated_breakPoints_enable: bool = "true",
-        /// Enables highlighting of all exit points while hovering your mouse above any `return`, `?`, or return type arrow (`->`).
+        /// Enables highlighting of all exit points while the cursor is on any `return`, `?`, `fn`, or return type arrow (`->`).
         highlightRelated_exitPoints_enable: bool = "true",
-        /// Enables highlighting of related references while hovering your mouse above any identifier.
+        /// Enables highlighting of related references while the cursor is on any identifier.
         highlightRelated_references_enable: bool = "true",
-        /// Enables highlighting of all break points for a loop or block context while hovering your mouse above any `async` or `await` keywords.
+        /// Enables highlighting of all break points for a loop or block context while the cursor is on any `async` or `await` keywords.
         highlightRelated_yieldPoints_enable: bool = "true",
 
         /// Whether to show `Debug` action. Only applies when
@@ -233,20 +254,20 @@ config_data! {
         /// Whether to show inlay type hints for elided lifetimes in function signatures.
         inlayHints_lifetimeElisionHints_enable: LifetimeElisionDef = "\"never\"",
         /// Whether to prefer using parameter names as the name for elided lifetime hints if possible.
-        inlayHints_lifetimeElisionHints_useParameterNames: bool  = "false",
+        inlayHints_lifetimeElisionHints_useParameterNames: bool    = "false",
         /// Maximum length for inlay hints. Set to null to have an unlimited length.
-        inlayHints_maxLength: Option<usize>                = "25",
+        inlayHints_maxLength: Option<usize>                        = "25",
         /// Whether to show function parameter name inlay hints at the call
         /// site.
         inlayHints_parameterHints_enable: bool                     = "true",
         /// Whether to show inlay type hints for compiler inserted reborrows.
         inlayHints_reborrowHints_enable: bool                      = "false",
         /// Whether to render trailing colons for parameter hints, and trailing colons for parameter hints.
-        inlayHints_renderColons: bool                      = "true",
+        inlayHints_renderColons: bool                              = "true",
         /// Whether to show inlay type hints for variables.
         inlayHints_typeHints_enable: bool                          = "true",
-        /// Whether to hide inlay hints for constructors.
-        inlayHints_typeHints_hideNamedConstructor: bool          = "false",
+        /// Whether to hide inlay type hints for constructors.
+        inlayHints_typeHints_hideNamedConstructor: bool            = "false",
 
         /// Join lines merges consecutive declaration and initialization of an assignment.
         joinLines_joinAssignments: bool = "true",
@@ -304,7 +325,7 @@ config_data! {
 
         /// Expand attribute macros. Requires `#rust-analyzer.procMacro.enable#` to be set.
         procMacro_attributes_enable: bool = "true",
-        /// Enable support for procedural macros, implies `#rust-analyzer.cargo.runBuildScripts#`.
+        /// Enable support for procedural macros, implies `#rust-analyzer.cargo.buildScripts.enable#`.
         procMacro_enable: bool                     = "true",
         /// These proc-macros will be ignored when trying to expand them.
         ///
diff --git a/docs/user/generated_config.adoc b/docs/user/generated_config.adoc
index 81bab6fd2d3..c3fc4096a26 100644
--- a/docs/user/generated_config.adoc
+++ b/docs/user/generated_config.adoc
@@ -1,7 +1,7 @@
 [[rust-analyzer.assist.expressionFillDefault]]rust-analyzer.assist.expressionFillDefault (default: `"todo"`)::
 +
 --
-Placeholder for missing expressions in assists.
+Placeholder expression to use for missing expressions in assists.
 --
 [[rust-analyzer.cargo.autoreload]]rust-analyzer.cargo.autoreload (default: `true`)::
 +
@@ -17,9 +17,18 @@ Run build scripts (`build.rs`) for more precise code analysis.
 [[rust-analyzer.cargo.buildScripts.overrideCommand]]rust-analyzer.cargo.buildScripts.overrideCommand (default: `null`)::
 +
 --
-Advanced option, fully override the command rust-analyzer uses to
-run build scripts and build procedural macros. The command should
-include `--message-format=json` or a similar option.
+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.
+
+By default, a cargo invocation will be constructed for the configured
+targets and features, with the following base command line:
+
+```bash
+cargo check --quiet --workspace --message-format=json --all-targets
+```
+.
 --
 [[rust-analyzer.cargo.buildScripts.useRustcWrapper]]rust-analyzer.cargo.buildScripts.useRustcWrapper (default: `true`)::
 +
@@ -30,12 +39,14 @@ avoid compiling unnecessary things.
 [[rust-analyzer.cargo.features]]rust-analyzer.cargo.features (default: `[]`)::
 +
 --
-List of features to activate. Set to `"all"` to pass `--all-features` to cargo.
+List of features to activate.
+
+Set this to `"all"` to pass `--all-features` to cargo.
 --
 [[rust-analyzer.cargo.noDefaultFeatures]]rust-analyzer.cargo.noDefaultFeatures (default: `false`)::
 +
 --
-Do not activate the `default` feature.
+Whether to pass `--no-default-features` to cargo.
 --
 [[rust-analyzer.cargo.noSysroot]]rust-analyzer.cargo.noSysroot (default: `false`)::
 +
@@ -76,7 +87,9 @@ 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.
+`#rust-analyzer.cargo.features#`.
+
+Set to `"all"` to pass `--all-features` to cargo.
 --
 [[rust-analyzer.checkOnSave.noDefaultFeatures]]rust-analyzer.checkOnSave.noDefaultFeatures (default: `null`)::
 +
@@ -86,9 +99,17 @@ Do not activate the `default` feature.
 [[rust-analyzer.checkOnSave.overrideCommand]]rust-analyzer.checkOnSave.overrideCommand (default: `null`)::
 +
 --
-Advanced option, fully override the command rust-analyzer uses for
-checking. The command should include `--message-format=json` or
-similar option.
+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.
+
+An example command would be:
+
+```bash
+cargo check --workspace --message-format=json --all-targets
+```
+.
 --
 [[rust-analyzer.checkOnSave.target]]rust-analyzer.checkOnSave.target (default: `null`)::
 +
@@ -226,22 +247,22 @@ Controls file watching implementation.
 [[rust-analyzer.highlightRelated.breakPoints.enable]]rust-analyzer.highlightRelated.breakPoints.enable (default: `true`)::
 +
 --
-Enables highlighting of related references while hovering your mouse `break`, `loop`, `while`, or `for` keywords.
+Enables highlighting of related references while the cursor is on `break`, `loop`, `while`, or `for` keywords.
 --
 [[rust-analyzer.highlightRelated.exitPoints.enable]]rust-analyzer.highlightRelated.exitPoints.enable (default: `true`)::
 +
 --
-Enables highlighting of all exit points while hovering your mouse above any `return`, `?`, or return type arrow (`->`).
+Enables highlighting of all exit points while the cursor is on any `return`, `?`, `fn`, or return type arrow (`->`).
 --
 [[rust-analyzer.highlightRelated.references.enable]]rust-analyzer.highlightRelated.references.enable (default: `true`)::
 +
 --
-Enables highlighting of related references while hovering your mouse above any identifier.
+Enables highlighting of related references while the cursor is on any identifier.
 --
 [[rust-analyzer.highlightRelated.yieldPoints.enable]]rust-analyzer.highlightRelated.yieldPoints.enable (default: `true`)::
 +
 --
-Enables highlighting of all break points for a loop or block context while hovering your mouse above any `async` or `await` keywords.
+Enables highlighting of all break points for a loop or block context while the cursor is on any `async` or `await` keywords.
 --
 [[rust-analyzer.hover.actions.debug.enable]]rust-analyzer.hover.actions.debug.enable (default: `true`)::
 +
@@ -362,7 +383,7 @@ Whether to show inlay type hints for variables.
 [[rust-analyzer.inlayHints.typeHints.hideNamedConstructor]]rust-analyzer.inlayHints.typeHints.hideNamedConstructor (default: `false`)::
 +
 --
-Whether to hide inlay hints for constructors.
+Whether to hide inlay type hints for constructors.
 --
 [[rust-analyzer.joinLines.joinAssignments]]rust-analyzer.joinLines.joinAssignments (default: `true`)::
 +
@@ -474,7 +495,7 @@ Expand attribute macros. Requires `#rust-analyzer.procMacro.enable#` to be set.
 [[rust-analyzer.procMacro.enable]]rust-analyzer.procMacro.enable (default: `true`)::
 +
 --
-Enable support for procedural macros, implies `#rust-analyzer.cargo.runBuildScripts#`.
+Enable support for procedural macros, implies `#rust-analyzer.cargo.buildScripts.enable#`.
 --
 [[rust-analyzer.procMacro.ignored]]rust-analyzer.procMacro.ignored (default: `{}`)::
 +
diff --git a/editors/code/package.json b/editors/code/package.json
index 79df7bdf3e4..4931ad96340 100644
--- a/editors/code/package.json
+++ b/editors/code/package.json
@@ -369,7 +369,7 @@
                 },
                 "$generated-start": {},
                 "rust-analyzer.assist.expressionFillDefault": {
-                    "markdownDescription": "Placeholder for missing expressions in assists.",
+                    "markdownDescription": "Placeholder expression to use for missing expressions in assists.",
                     "default": "todo",
                     "type": "string",
                     "enum": [
@@ -392,7 +392,7 @@
                     "type": "boolean"
                 },
                 "rust-analyzer.cargo.buildScripts.overrideCommand": {
-                    "markdownDescription": "Advanced option, fully override the command rust-analyzer uses to\nrun build scripts and build procedural macros. The command should\ninclude `--message-format=json` or a similar option.",
+                    "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.",
                     "default": null,
                     "type": [
                         "null",
@@ -408,7 +408,7 @@
                     "type": "boolean"
                 },
                 "rust-analyzer.cargo.features": {
-                    "markdownDescription": "List of features to activate. Set to `\"all\"` to pass `--all-features` to cargo.",
+                    "markdownDescription": "List of features to activate.\n\nSet this to `\"all\"` to pass `--all-features` to cargo.",
                     "default": [],
                     "type": [
                         "string",
@@ -425,7 +425,7 @@
                     ]
                 },
                 "rust-analyzer.cargo.noDefaultFeatures": {
-                    "markdownDescription": "Do not activate the `default` feature.",
+                    "markdownDescription": "Whether to pass `--no-default-features` to cargo.",
                     "default": false,
                     "type": "boolean"
                 },
@@ -476,7 +476,7 @@
                     }
                 },
                 "rust-analyzer.checkOnSave.features": {
-                    "markdownDescription": "List of features to activate. Defaults to\n`#rust-analyzer.cargo.features#`. Set 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,
                     "type": [
                         "string",
@@ -502,7 +502,7 @@
                     ]
                 },
                 "rust-analyzer.checkOnSave.overrideCommand": {
-                    "markdownDescription": "Advanced option, fully override the command rust-analyzer uses for\nchecking. The command should include `--message-format=json` or\nsimilar option.",
+                    "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.",
                     "default": null,
                     "type": [
                         "null",
@@ -655,22 +655,22 @@
                     "type": "string"
                 },
                 "rust-analyzer.highlightRelated.breakPoints.enable": {
-                    "markdownDescription": "Enables highlighting of related references while hovering your mouse `break`, `loop`, `while`, or `for` keywords.",
+                    "markdownDescription": "Enables highlighting of related references while the cursor is on `break`, `loop`, `while`, or `for` keywords.",
                     "default": true,
                     "type": "boolean"
                 },
                 "rust-analyzer.highlightRelated.exitPoints.enable": {
-                    "markdownDescription": "Enables highlighting of all exit points while hovering your mouse above any `return`, `?`, or return type arrow (`->`).",
+                    "markdownDescription": "Enables highlighting of all exit points while the cursor is on any `return`, `?`, `fn`, or return type arrow (`->`).",
                     "default": true,
                     "type": "boolean"
                 },
                 "rust-analyzer.highlightRelated.references.enable": {
-                    "markdownDescription": "Enables highlighting of related references while hovering your mouse above any identifier.",
+                    "markdownDescription": "Enables highlighting of related references while the cursor is on any identifier.",
                     "default": true,
                     "type": "boolean"
                 },
                 "rust-analyzer.highlightRelated.yieldPoints.enable": {
-                    "markdownDescription": "Enables highlighting of all break points for a loop or block context while hovering your mouse above any `async` or `await` keywords.",
+                    "markdownDescription": "Enables highlighting of all break points for a loop or block context while the cursor is on any `async` or `await` keywords.",
                     "default": true,
                     "type": "boolean"
                 },
@@ -824,7 +824,7 @@
                     "type": "boolean"
                 },
                 "rust-analyzer.inlayHints.typeHints.hideNamedConstructor": {
-                    "markdownDescription": "Whether to hide inlay hints for constructors.",
+                    "markdownDescription": "Whether to hide inlay type hints for constructors.",
                     "default": false,
                     "type": "boolean"
                 },
@@ -936,7 +936,7 @@
                     "type": "boolean"
                 },
                 "rust-analyzer.procMacro.enable": {
-                    "markdownDescription": "Enable support for procedural macros, implies `#rust-analyzer.cargo.runBuildScripts#`.",
+                    "markdownDescription": "Enable support for procedural macros, implies `#rust-analyzer.cargo.buildScripts.enable#`.",
                     "default": true,
                     "type": "boolean"
                 },