Refactor components_*_msg and add Panics sections to docstrings

Author: rami3l

src/dist/dist.rs

@@ -42,46 +42,57 @@ static TOOLCHAIN_CHANNELS: &[&str] = &[
     r"\d{1}\.\d{1,3}(?:\.\d{1,2})?",
 ];
 
+/// Returns a error message indicating that certain [`Component`]s are missing in a toolchain distribution.
+///
+/// This message is currently used exclusively in toolchain-wide operations,
+/// otherwise [`component_unavailable_msg`](../../errors/fn.component_unavailable_msg.html) will be used.
+///
+/// # Panics
+/// This function will panic when the collection of unavailable components `cs` is empty.
 fn components_missing_msg(cs: &[Component], manifest: &ManifestV2, toolchain: &str) -> String {
-    assert!(!cs.is_empty());
     let mut buf = vec![];
     let suggestion = format!("    rustup toolchain add {toolchain} --profile minimal");
     let nightly_tips = "Sometimes not all components are available in any given nightly. ";
 
-    if cs.len() == 1 {
-        let _ = writeln!(
-            buf,
-            "component {} is unavailable for download for channel '{}'",
-            &cs[0].description(manifest),
-            toolchain,
-        );
+    match cs {
+        [] => panic!("`components_missing_msg` should not be called with an empty collection of unavailable components"),
+        [c] => {
+            _ = writeln!(
+                buf,
+                "component {} is unavailable for download for channel '{}'",
+                c.description(manifest),
+                toolchain,
+            );
+
+            if toolchain.starts_with("nightly") {
+                _ = write!(buf, "{nightly_tips}");
+            }
 
-        if toolchain.starts_with("nightly") {
-            let _ = write!(buf, "{nightly_tips}");
+            _ = write!(
+                buf,
+                "If you don't need the component, you could try a minimal installation with:\n\n{suggestion}"
+            );
         }
+        cs => {
+            let cs_str = cs
+                .iter()
+                .map(|c| c.description(manifest))
+                .collect::<Vec<_>>()
+                .join(", ");
+            _ = write!(
+                buf,
+                "some components unavailable for download for channel '{toolchain}': {cs_str}"
+            );
 
-        let _ = write!(
-            buf,
-            "If you don't need the component, you could try a minimal installation with:\n\n{suggestion}"
-        );
-    } else {
-        let cs_str = cs
-            .iter()
-            .map(|c| c.description(manifest))
-            .collect::<Vec<_>>()
-            .join(", ");
-        let _ = write!(
-            buf,
-            "some components unavailable for download for channel '{toolchain}': {cs_str}"
-        );
+            if toolchain.starts_with("nightly") {
+                let _ = write!(buf, "{nightly_tips}");
+            }
 
-        if toolchain.starts_with("nightly") {
-            let _ = write!(buf, "{nightly_tips}");
+            _ = write!(
+                buf,
+                "If you don't need the components, you could try a minimal installation with:\n\n{suggestion}"
+            );
         }
-        let _ = write!(
-            buf,
-            "If you don't need the components, you could try a minimal installation with:\n\n{suggestion}"
-        );
     }
 
     String::from_utf8(buf).unwrap()

src/errors.rs

@@ -139,53 +139,61 @@ fn suggest_message(suggestion: &Option<String>) -> String {
     }
 }
 
+/// Returns a error message indicating that certain [`Component`]s are unavailable.
+///
+/// See also [`component_missing_msg`](../dist/dist/fn.components_missing_msg.html)
+/// which generates error messages for component unavailability toolchain-wide operations.
+///
+/// # Panics
+/// This function will panic when the collection of unavailable components `cs` is empty.
 fn component_unavailable_msg(cs: &[Component], manifest: &Manifest, toolchain: &str) -> String {
-    assert!(!cs.is_empty());
-
     let mut buf = vec![];
-
-    if cs.len() == 1 {
-        let _ = writeln!(
-            buf,
-            "component {} is unavailable for download for channel '{}'",
-            &cs[0].description(manifest),
-            toolchain,
-        );
-        if toolchain.starts_with("nightly") {
-            let _ = write!(
+    match cs {
+        [] => panic!("`component_unavailable_msg` should not be called with an empty collection of unavailable components"),
+        [c] => {
+            _ = writeln!(
                 buf,
-                "Sometimes not all components are available in any given nightly. "
+                "component {} is unavailable for download for channel '{}'",
+                c.description(manifest),
+                toolchain,
             );
-        }
-    } else {
-        // More than one component
 
-        let same_target = cs
-            .iter()
-            .all(|c| c.target == cs[0].target || c.target.is_none());
-
-        let cs_str = if same_target {
-            cs.iter()
-                .map(|c| format!("'{}'", c.short_name(manifest)))
-                .collect::<Vec<_>>()
-                .join(", ")
-        } else {
-            cs.iter()
-                .map(|c| c.description(manifest))
-                .collect::<Vec<_>>()
-                .join(", ")
-        };
+            if toolchain.starts_with("nightly") {
+                _ = write!(
+                    buf,
+                    "Sometimes not all components are available in any given nightly. "
+                );
+            }
+        }
+        cs => {
+            // More than one component
+            let same_target = cs
+                .iter()
+                .all(|c| c.target == cs[0].target || c.target.is_none());
 
-        let _ = write!(
-            buf,
-            "some components unavailable for download for channel '{toolchain}': {cs_str}",
-        );
+            let cs_str = if same_target {
+                cs.iter()
+                    .map(|c| format!("'{}'", c.short_name(manifest)))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            } else {
+                cs.iter()
+                    .map(|c| c.description(manifest))
+                    .collect::<Vec<_>>()
+                    .join(", ")
+            };
 
-        if toolchain.starts_with("nightly") {
             _ = write!(
                 buf,
-                "Sometimes not all components are available in any given nightly. "
+                "some components unavailable for download for channel '{toolchain}': {cs_str}"
             );
+
+            if toolchain.starts_with("nightly") {
+                _ = write!(
+                    buf,
+                    "Sometimes not all components are available in any given nightly. "
+                );
+            }
         }
     }