Auto merge of #10633 - hi-rustin:rustin-patch-docs-variables, r=epage

Improve CARGO_ENCODED_RUSTFLAGS and CARGO_ENCODED_RUSTDOCFLAGS variables docs

### What does this PR try to resolve?

close #10555

It has been improved according to the three requirements in the issue.

Author: bors

src/doc/src/reference/config.md

@@ -363,18 +363,19 @@ Can be overridden with the `--target-dir` CLI option.
 ##### `build.rustflags`
 * Type: string or array of strings
 * Default: none
-* Environment: `CARGO_BUILD_RUSTFLAGS` or `RUSTFLAGS`
+* Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS`
 
 Extra command-line flags to pass to `rustc`. The value may be a array of
 strings or a space-separated string.
 
 There are three mutually exclusive sources of extra flags. They are checked in
 order, with the first one being used:
 
-1. `RUSTFLAGS` environment variable.
-2. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags`
+1. `CARGO_ENCODED_RUSTFLAGS` environment variable.
+2. `RUSTFLAGS` environment variable.
+3. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags`
    config entries joined together.
-3. `build.rustflags` config value.
+4. `build.rustflags` config value.
 
 Additional flags may also be passed with the [`cargo rustc`] command.
 
@@ -399,16 +400,17 @@ appropriate profile setting.
 ##### `build.rustdocflags`
 * Type: string or array of strings
 * Default: none
-* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `RUSTDOCFLAGS`
+* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS`
 
 Extra command-line flags to pass to `rustdoc`. The value may be a array of
 strings or a space-separated string.
 
 There are two mutually exclusive sources of extra flags. They are checked in
 order, with the first one being used:
 
-1. `RUSTDOCFLAGS` environment variable.
-2. `build.rustdocflags` config value.
+1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable.
+2. `RUSTDOCFLAGS` environment variable.
+3. `build.rustdocflags` config value.
 
 Additional flags may also be passed with the [`cargo rustdoc`] command.
 

src/doc/src/reference/environment-variables.md

@@ -36,16 +36,18 @@ system:
   invocations that Cargo performs. In contrast with [`cargo rustdoc`], this is
   useful for passing a flag to *all* `rustdoc` instances. See
   [`build.rustdocflags`] for some more ways to set flags. This string is
-  split by whitespace; for a more robust encoding of multiple arguments,
-  set `CARGO_ENCODED_RUSTDOCFLAGS` instead with arguments separated by
-  `0x1f` (ASCII Unit Separator).
+  split by whitespace; for a more robust encoding of multiple arguments, 
+  see `CARGO_ENCODED_RUSTDOCFLAGS`.
+* `CARGO_ENCODED_RUSTDOCFLAGS` -  A list of custom flags separated by `0x1f` 
+  (ASCII Unit Separator) to pass to all `rustdoc` invocations that Cargo performs.
 * `RUSTFLAGS` — A space-separated list of custom flags to pass to all compiler
   invocations that Cargo performs. In contrast with [`cargo rustc`], this is
   useful for passing a flag to *all* compiler instances. See
   [`build.rustflags`] for some more ways to set flags. This string is
-  split by whitespace; for a more robust encoding of multiple arguments,
-  set `CARGO_ENCODED_RUSTFLAGS` instead with arguments separated by
-  `0x1f` (ASCII Unit Separator).
+  split by whitespace; for a more robust encoding of multiple arguments, 
+  see `CARGO_ENCODED_RUSTFLAGS`.
+* `CARGO_ENCODED_RUSTFLAGS` - A list of custom flags separated by `0x1f` 
+  (ASCII Unit Separator) to pass to all compiler invocations that Cargo performs.
 * `CARGO_INCREMENTAL` — If this is set to 1 then Cargo will force [incremental
   compilation] to be enabled for the current compilation, and when set to 0 it
   will force disabling it. If this env var isn't present then cargo's defaults