From 7bfbd3b96c29898de001cbda7730fa440d35bd3b Mon Sep 17 00:00:00 2001
From: Nicholas Bishop <nbishop@nbishop.net>
Date: Tue, 6 Sep 2022 09:49:04 -0400
Subject: [PATCH] Add details of each setting in the toolchain file

The format of the new section is modeled after the cargo docs, for example:
https://doc.rust-lang.org/cargo/reference/profiles.html#profile-settings

This is mostly a reorganization of the existing content to make it
easier to scan for relevant details, but a few new details have also
been added:

1. For `channel`, the format is now explained in the same format as in
   concepts/toolchains.md, but with the more limited form that
   `rust-toolchain.toml` accepts. This is based on the text that was
   here previously; I haven't verified if the code is actually this
   strict.
2. The `profile` section mentions that the default profile is not
   necessarily the profile named `default`, which is subtle detail that
   can be confusing.
3. The `components` section notes that the list is additive with the
   profile's list of components.
4. The `targets` field is now documented, previously it wasn't mentioned
   other than to say it's ignored with `path`.
---
 doc/src/overrides.md | 73 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 60 insertions(+), 13 deletions(-)

diff --git a/doc/src/overrides.md b/doc/src/overrides.md
index c586471b1c..194aa7a377 100644
--- a/doc/src/overrides.md
+++ b/doc/src/overrides.md
@@ -113,23 +113,70 @@ that uses the new TOML encoding in the `rust-toolchain` file. You need to upgrad
 The `rust-toolchain.toml`/`rust-toolchain` files are suitable to check in to
 source control.
 
-The toolchains named in these files have a more restricted form than `rustup`
-toolchains generally, and may only contain the names of the three release
-channels, 'stable', 'beta', 'nightly', Rust version numbers, like '1.0.0', and
-optionally an archive date, like 'nightly-2017-01-01'. They may not name
-custom toolchains, nor host-specific toolchains. To use a custom local
-toolchain, you can instead use a `path` toolchain:
+### Toolchain file settings
 
-``` toml
-[toolchain]
-path = "/path/to/local/toolchain"
+#### channel
+
+The `channel` setting specifies which [toolchain] to use. The value is a
+string in the following form:
+
+```
+<channel>[-<date>]
+
+<channel>       = stable|beta|nightly|<major.minor.patch>
+<date>          = YYYY-MM-DD
 ```
 
+Note that this is a more restricted form than `rustup` toolchains
+generally, and cannot be used to specify custom toolchains or
+host-specific toolchains.
+
+[toolchain]: concepts/toolchains.md
+
+#### path
+
+The `path` setting allows a custom toolchain to be used. The value is a
+path string. A relative path is resolved relative to the location of the
+`rust-toolchain.toml` file.
+
 Since a `path` directive directly names a local toolchain, other options
-like `components`, `targets`, and `profile` have no effect. `channel`
-and `path` are mutually exclusive, since a `path` already points to a
-specific toolchain. A relative `path` is resolved relative to the
-location of the `rust-toolchain.toml` file.
+like `components`, `targets`, and `profile` have no effect.
+
+`channel` and `path` are mutually exclusive, since a `path` already
+points to a specific toolchain.
+
+#### profile
+
+The `profile` setting names a group of components to be installed. The
+value is a string. The valid options are: `minimal`, `default`, and
+`complete`. See [profiles] for details of each.
+
+Note that if not specified, the `default` profile is not necessarily
+used, as a different default profile might have been set with `rustup
+set profile`.
+
+[profiles]: concepts/profiles.md
+
+#### components
+
+The `components` setting contains a list of additional components to
+install. The value is a list of strings. See [components] for a list of
+components. Note that different toolchains may have different components
+available.
+
+The components listed here are additive with the current profile.
+
+[components]: concepts/components.md
+
+#### targets
+
+The `targets` setting contains a list of platforms to install for
+[cross-compilation]. The value is a list of strings.
+
+The host platform is automatically included; the targets listed here are
+additive.
+
+[cross-compilation]: https://rust-lang.github.io/rustup/cross-compilation.html
 
 ## Default toolchain