Add some code comments

Thanks to AI.

src/compiler/clang.rs

@@ -108,6 +108,15 @@ impl Clang {
         Ok(())
     }
 
+    /// Download and unpack the latest MSVC sysroot from GitHub Releases.
+    ///
+    /// If the sysroot is already downloaded and unpacked, it will be reused.
+    /// The sysroot will be stored in `<cache_dir>/windows-msvc-sysroot`.
+    /// A file named `DONE` will be created in the same directory with the
+    /// download URL as its content.
+    ///
+    /// The environment variable `XWIN_MSVC_SYSROOT_DOWNLOAD_URL` can be used
+    /// to override the download URL.
     fn setup_msvc_sysroot(&self, cache_dir: PathBuf) -> Result<PathBuf> {
         let msvc_sysroot_dir = cache_dir.join("windows-msvc-sysroot");
         let done_mark_file = msvc_sysroot_dir.join("DONE");
@@ -133,6 +142,12 @@ impl Clang {
         Ok(msvc_sysroot_dir)
     }
 
+    /// Retrieves the latest MSVC sysroot download URL from GitHub Releases.
+    ///
+    /// The function uses the `ureq` agent to make an HTTP GET request to the GitHub API. If a
+    /// `GITHUB_TOKEN` environment variable is present, it includes it as a Bearer token for
+    /// authentication.
+    ///
     fn get_latest_msvc_sysroot_download_url(&self, agent: ureq::Agent) -> Result<String> {
         if let Ok(url) = env::var("XWIN_MSVC_SYSROOT_DOWNLOAD_URL") {
             return Ok(url);

src/compiler/clang_cl.rs

@@ -144,6 +144,7 @@ impl<'a> ClangCl<'a> {
         Ok(())
     }
 
+    /// Downloads and extracts the specified MSVC CRT components into the specified `cache_dir`.
     fn setup_msvc_crt(&self, cache_dir: PathBuf) -> Result<()> {
         let done_mark_file = cache_dir.join("DONE");
         let xwin_arches: HashSet<_> = self
@@ -403,6 +404,14 @@ set(CMAKE_USER_MAKE_RULES_OVERRIDE "${{CMAKE_CURRENT_LIST_DIR}}/override.cmake")
     }
 }
 
+/// Creates a symlink to the `clang` binary in `cache_dir` and names it
+/// `clang-cl`. This is necessary because the `clang-cl` binary doesn't
+/// exist on macOS, but `clang` does and can be used as a drop-in
+/// replacement for `clang-cl`.
+///
+/// The `clang` binary is first searched for in `PATH` (skipping the system
+/// clang), and if no suitable clang is found, the Xcode clang is tried as
+/// a fallback. If no usable clang is found, the function does nothing.
 #[cfg(target_os = "macos")]
 pub fn setup_clang_cl_symlink(env_path: &OsStr, cache_dir: &Path) -> Result<()> {
     // Try PATH first, but skip system clang

src/compiler/common.rs

@@ -6,6 +6,11 @@ use std::path::{Path, PathBuf};
 use std::process::Command;
 use which::which_in;
 
+/// Sets up the environment path by adding necessary directories to the existing `PATH`.
+///
+/// On macOS, it checks for specific LLVM installation paths based on the architecture
+/// and adds them to the front of the environment paths if they exist.
+/// It then appends the `cache_dir` provided to the list of paths.
 pub fn setup_env_path(cache_dir: &Path) -> Result<OsString> {
     let env_path = env::var("PATH").unwrap_or_default();
     let mut env_paths: Vec<_> = env::split_paths(&env_path).collect();
@@ -29,13 +34,30 @@ pub fn setup_env_path(cache_dir: &Path) -> Result<OsString> {
     Ok(env::join_paths(env_paths)?)
 }
 
+/// Sets up symlinks for LLVM tools in the provided environment path and cache directory.
+///
+/// This function creates symlinks for the following tools:
+/// - `rust-lld` to `lld-link`
+/// - `llvm-ar` to `llvm-lib`
+/// - `llvm-ar` to `llvm-dlltool`
+///
+/// These symlinks are established if they do not already exist in the specified environment path.
 pub fn setup_llvm_tools(env_path: &OsStr, cache_dir: &Path) -> Result<()> {
     symlink_llvm_tool("rust-lld", "lld-link", env_path, cache_dir)?;
     symlink_llvm_tool("llvm-ar", "llvm-lib", env_path, cache_dir)?;
     symlink_llvm_tool("llvm-ar", "llvm-dlltool", env_path, cache_dir)?;
     Ok(())
 }
 
+/// Configures the environment variables for the target compiler and linker.
+///
+/// This function sets up environment variables for the specified target compiler and linker,
+/// allowing the build system to correctly use the desired tools for compilation and linking.
+/// It sets up the following environment variables:
+/// - `TARGET_CC` and `TARGET_CXX` with the provided compiler.
+/// - `CC_<env_target>` and `CXX_<env_target>` with the provided compiler.
+/// - `TARGET_AR` and `AR_<env_target>` with "llvm-lib".
+/// - `CARGO_TARGET_<env_target>_LINKER` with "lld-link".
 pub fn setup_target_compiler_and_linker_env(cmd: &mut Command, env_target: &str, compiler: &str) {
     cmd.env("TARGET_CC", compiler);
     cmd.env("TARGET_CXX", compiler);
@@ -49,6 +71,13 @@ pub fn setup_target_compiler_and_linker_env(cmd: &mut Command, env_target: &str,
     );
 }
 
+/// Configures the environment variables for CMake to use the Ninja generator and Windows system.
+///
+/// This function sets up the following environment variables:
+/// - `CMAKE_GENERATOR` as "Ninja".
+/// - `CMAKE_SYSTEM_NAME` as "Windows".
+/// - `CMAKE_TOOLCHAIN_FILE_<env_target>` with the provided toolchain path, where `<env_target>` is the target string
+///   converted to lowercase and hyphens replaced with underscores.
 pub fn setup_cmake_env(cmd: &mut Command, target: &str, toolchain_path: PathBuf) {
     let env_target = target.to_lowercase().replace('-', "_");
     cmd.env("CMAKE_GENERATOR", "Ninja")