docs: Update docstrings

src/cli.rs

@@ -1,3 +1,5 @@
+//! Command line interface.
+
 use crate::targets::{parse_targets, Target};
 use clap::Parser;
 use clap_complete::Shell;

src/env/mod.rs

@@ -28,10 +28,12 @@ pub fn set_env(toolchain_dir: &Path, no_modify_env: bool) -> Result<(), Error> {
     Ok(())
 }
 
+/// Get the home directory.
 pub fn get_home_dir() -> PathBuf {
     BaseDirs::new().unwrap().home_dir().to_path_buf()
 }
 
+/// Clean the environment variables.
 pub fn clean_env(install_dir: &Path) -> Result<(), Error> {
     #[cfg(windows)]
     windows::clean_env(install_dir)?;
@@ -40,6 +42,8 @@ pub fn clean_env(install_dir: &Path) -> Result<(), Error> {
 
     Ok(())
 }
+
+/// Print to post installation message
 pub fn print_post_install_msg(toolchain_dir: &str, no_modify_env: bool) {
     if no_modify_env {
         println!(

src/env/shell.rs

@@ -75,8 +75,8 @@ impl ShellScript {
     }
 }
 
-// Cross-platform non-POSIX shells have not been assessed for integration yet
 #[cfg(unix)]
+/// Cross-platform non-POSIX shells have not been assessed for integration yet
 fn enumerate_shells() -> Vec<Shell> {
     vec![
         Box::new(Posix),
@@ -87,16 +87,17 @@ fn enumerate_shells() -> Vec<Shell> {
 }
 
 #[cfg(unix)]
+/// Returns all shells that exist on the system.
 pub(super) fn get_available_shells() -> impl Iterator<Item = Shell> {
     enumerate_shells().into_iter().filter(|sh| sh.does_exist())
 }
 
 #[cfg(windows)]
 pub trait WindowsShell {
-    // Writes the relevant env file.
+    /// Writes the relevant env file.
     fn env_script(&self, toolchain_dir: &Path) -> ShellScript;
 
-    // Gives the source string for a given shell.
+    /// Gives the source string for a given shell.
     fn source_string(&self, toolchain_dir: &str) -> Result<String, Error>;
 }
 
@@ -136,18 +137,18 @@ impl WindowsShell for Powershell {
 
 #[cfg(unix)]
 pub trait UnixShell {
-    // Detects if a shell "exists". Users have multiple shells, so an "eager"
-    // heuristic should be used, assuming shells exist if any traces do.
+    /// Detects if a shell "exists". Users have multiple shells, so an "eager"
+    /// heuristic should be used, assuming shells exist if any traces do.
     fn does_exist(&self) -> bool;
 
-    // Gives all rcfiles of a given shell that Rustup is concerned with.
-    // Used primarily in checking rcfiles for cleanup.
+    /// Gives all rcfiles of a given shell that Rustup is concerned with.
+    /// Used primarily in checking rcfiles for cleanup.
     fn rcfiles(&self) -> Vec<PathBuf>;
 
-    // Gives rcs that should be written to.
+    /// Gives rcs that should be written to.
     fn update_rcs(&self) -> Vec<PathBuf>;
 
-    // Writes the relevant env file.
+    /// Writes the relevant env file.
     fn env_script(&self, toolchain_dir: &Path) -> ShellScript {
         ShellScript {
             name: "env",
@@ -156,7 +157,7 @@ pub trait UnixShell {
         }
     }
 
-    // Gives the source string for a given shell.
+    /// Gives the source string for a given shell.
     fn source_string(&self, toolchain_dir: &str) -> Result<String, Error> {
         Ok(format!(r#". "{}/env""#, toolchain_dir))
     }
@@ -303,11 +304,13 @@ impl UnixShell for Fish {
 }
 
 #[cfg(unix)]
+/// Finds the command for a given string.
 pub(crate) fn find_cmd<'a>(cmds: &[&'a str]) -> Option<&'a str> {
     cmds.iter().cloned().find(|&s| has_cmd(s))
 }
 
 #[cfg(unix)]
+/// Checks if a command exists in the PATH.
 fn has_cmd(cmd: &str) -> bool {
     let cmd = format!("{}{}", cmd, env::consts::EXE_SUFFIX);
     let path = env::var("PATH").unwrap_or_default();
@@ -316,6 +319,7 @@ fn has_cmd(cmd: &str) -> bool {
         .any(|p| p.exists())
 }
 
+/// Writes a file to a given path.
 pub fn write_file(path: &Path, contents: &str) -> Result<(), Error> {
     let mut file = OpenOptions::new()
         .write(true)

src/env/unix.rs

@@ -1,3 +1,5 @@
+//! Unix specific environment functions.
+
 use crate::{env::get_home_dir, env::shell, error::Error};
 use miette::Result;
 use std::{
@@ -8,7 +10,7 @@ use std::{
 
 const LEGACY_EXPORT_FILE: &str = "export-esp.sh";
 
-// Clean the environment for Windows.
+/// Clean the environment for Windows.
 pub(super) fn clean_env(toolchain_dir: &Path) -> Result<(), Error> {
     for sh in shell::get_available_shells() {
         let source_bytes = format!(
@@ -50,7 +52,7 @@ pub(super) fn clean_env(toolchain_dir: &Path) -> Result<(), Error> {
     Ok(())
 }
 
-// Delete the legacy export file.
+/// Delete the legacy export file.
 fn remove_legacy_export_file() -> Result<(), Error> {
     let legacy_file = get_home_dir().join(LEGACY_EXPORT_FILE);
     if legacy_file.exists() {
@@ -60,7 +62,7 @@ fn remove_legacy_export_file() -> Result<(), Error> {
     Ok(())
 }
 
-// Update the environment for Unix.
+/// Update the environment for Unix.
 pub(crate) fn update_env(toolchain_dir: &Path) -> Result<(), Error> {
     for sh in shell::get_available_shells() {
         let source_cmd = sh.source_string(&toolchain_dir.display().to_string())?;
@@ -94,7 +96,7 @@ pub(crate) fn update_env(toolchain_dir: &Path) -> Result<(), Error> {
     Ok(())
 }
 
-// Write the environment files for Unix.
+/// Write the environment files for Unix.
 pub(super) fn write_env_files(toolchain_dir: &Path) -> Result<(), Error> {
     let mut written = vec![];
 

src/env/windows.rs

@@ -1,3 +1,5 @@
+//! Windows specific environment functions.
+
 use crate::{env::get_home_dir, env::shell, error::Error};
 use miette::Result;
 use std::{env, fs::remove_file, path::Path};
@@ -8,7 +10,7 @@ use winreg::{
 
 const LEGACY_EXPORT_FILE: &str = "export-esp.ps1";
 
-// Clean the environment for Windows.
+/// Clean the environment for Windows.
 pub(super) fn clean_env(_install_dir: &Path) -> Result<(), Error> {
     delete_env_variable("LIBCLANG_PATH")?;
     delete_env_variable("CLANG_PATH")?;
@@ -70,7 +72,7 @@ fn set_env_variable(key: &str, value: &str) -> Result<(), Error> {
     Ok(())
 }
 
-// Delete the legacy export file.
+/// Delete the legacy export file.
 fn remove_legacy_export_file() -> Result<(), Error> {
     let legacy_file = get_home_dir().join(LEGACY_EXPORT_FILE);
     if legacy_file.exists() {
@@ -123,7 +125,7 @@ pub(super) fn update_env() -> Result<(), Error> {
     Ok(())
 }
 
-// Write the environment files for Windows.
+/// Write the environment files for Windows.
 pub(super) fn write_env_files(toolchain_dir: &Path) -> Result<(), Error> {
     let windows_shells: Vec<shell::Shell> =
         vec![Box::new(shell::Batch), Box::new(shell::Powershell)];