docs: update docs and add comment

address comments

doc/src/basics.md

@@ -30,20 +30,30 @@ info: downloading self-updates
 
 ## Keeping `rustup` up to date
 
-Running `rustup update` also checks for updates to `rustup` itself and automatically
-installs the latest version. To manually update `rustup` only,
-without updating installed toolchains, type `rustup self update`:
+## Keeping rustup up to date
+
+It is possible to control Rustup's automatic self update mechanism with the `auto-self-update` configuration
+variable.  This setting supports three values: `enable` and `disable` and `check-only`.
+
+* `disable` will ensure that no automatic self updating actions are taken.
+* `enable` will mean that `rustup update` and similar commands will also check-for, and install, any update to Rustup.
+* `check-only` will cause any automatic self update to check and report on any updates, but not to automatically install them.
+
+Whether automatic self-update is enabled or not, you can request that Rustup check for, and update itself to the
+latest version of `rustup` without updating any installed toolchains by running `rustup
+self update`:
 
 ```console
 $ rustup self update
 info: checking for self-updates
 info: downloading self-updates
 ```
 
-> #### Disable automatic self-updates
-> `rustup` will automatically update itself at the end of any toolchain installation.
-> You can prevent this automatic behaviour by passing the `--no-self-update` argument
-> when running `rustup update` or `rustup toolchain install`.
+> ### Disable automatic self-updates with the parameter of the command
+> If auto-self-update is `enable`, `rustup` will automatically update itself at the end of any
+> toolchain installation as well.  You can prevent this automatic behaviour by
+> passing the `--no-self-update` argument when running `rustup update` or
+> `rustup toolchain install`.
 
 ## Help system
 

src/cli/rustup_mode.rs

@@ -932,9 +932,13 @@ fn check_updates(cfg: &Cfg) -> Result<utils::ExitCode> {
 
 fn update(cfg: &mut Cfg, m: &ArgMatches<'_>) -> Result<utils::ExitCode> {
     let self_update_mode = cfg.get_self_update_mode()?;
-    let self_update = !m.is_present("no-self-update")
-        && !self_update::NEVER_SELF_UPDATE
-        && self_update_mode == "enable";
+    // Priority: no-self-update feature > self_update_mode > no-self-update args.
+    // Update only if rustup does **not** have the no-self-update feature,
+    // and auto-self-update is configured to **enable**
+    // and has **no** no-self-update parameter.
+    let self_update = !self_update::NEVER_SELF_UPDATE
+        && self_update_mode == "enable"
+        && !m.is_present("no-self-update");
     let forced = m.is_present("force-non-host");
     if let Some(p) = m.value_of("profile") {
         let p = Profile::from_str(p)?;
@@ -1020,7 +1024,7 @@ fn update(cfg: &mut Cfg, m: &ArgMatches<'_>) -> Result<utils::ExitCode> {
         cfg.temp_cfg.clean();
     }
 
-    if !self_update && self_update_mode == "check-only" {
+    if !self_update::NEVER_SELF_UPDATE && self_update_mode == "check-only" {
         check_rustup_update()?;
     }
 
@@ -1582,6 +1586,9 @@ fn set_profile(cfg: &mut Cfg, m: &ArgMatches<'_>) -> Result<utils::ExitCode> {
 }
 
 fn set_auto_self_update(cfg: &mut Cfg, m: &ArgMatches<'_>) -> Result<utils::ExitCode> {
+    if self_update::NEVER_SELF_UPDATE {
+        warn!("Your rustup is built with the no-self-update feature, so setting auto-self-update will not have any effect.");
+    }
     cfg.set_auto_self_update(&m.value_of("auto-self-update-mode").unwrap())?;
     Ok(utils::ExitCode(0))
 }

src/config.rs

@@ -406,6 +406,7 @@ impl Cfg {
         Ok(())
     }
 
+    // FIXME(hi-rustin): It is better to use enumerations rather than strings.
     pub fn set_auto_self_update(&mut self, mode: &str) -> Result<()> {
         if !SELF_UPDATE_MODES.contains(&mode) {
             return Err(anyhow!(

src/notifications.rs

@@ -104,7 +104,7 @@ impl<'a> Display for Notification<'a> {
                 name
             ),
             SetProfile(name) => write!(f, "profile set to '{}'", name),
-            SetSelfUpdate(mode) => write!(f, "self update mode to '{}'", mode),
+            SetSelfUpdate(mode) => write!(f, "auto-self-update mode set to '{}'", mode),
             LookingForToolchain(name) => write!(f, "looking for installed toolchain '{}'", name),
             ToolchainDirectory(path, _) => write!(f, "toolchain directory: '{}'", path.display()),
             UpdatingToolchain(name) => write!(f, "updating existing install for '{}'", name),