Refactor components_missing_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

@@ -170,6 +170,13 @@ fn remove_component_msg(cs: &Component, manifest: &Manifest, toolchain: &str) ->
     }
 }
 
+/// 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());