Do a pass over all doc comments in new build modules

src/cli/build/base_exe.rs

@@ -13,15 +13,18 @@ use super::{
     target::{BuildTarget, CACHE_DIR},
 };
 
-/// Discovers the path to the base executable to use for cross-compilation, and downloads it if necessary
+/**
+    Discovers the path to the base executable to use for cross-compilation.
+
+    If the target is the same as the current system, the current executable is used.
+
+    If no binary exists at the target path, it will attempt to download it from the internet.
+*/
 pub async fn get_or_download_base_executable(target: BuildTarget) -> BuildResult<PathBuf> {
-    // If the target matches the current system, just use the current executable
     if target.is_current_system() {
         return Ok(CURRENT_EXE.to_path_buf());
     }
-
-    // If a cached target base executable doesn't exist, attempt to download it
-    if !target.cache_path().exists() {
+    if target.cache_path().exists() {
         return Ok(target.cache_path());
     }
 

src/cli/build/files.rs

@@ -3,8 +3,11 @@ use std::path::{Path, PathBuf};
 use anyhow::Result;
 use tokio::{fs, io::AsyncWriteExt};
 
-/// Removes the source file extension from the given path, if it has one
-/// A source file extension is an extension such as `.lua` or `.luau`
+/**
+    Removes the source file extension from the given path, if it has one.
+
+    A source file extension is an extension such as `.lua` or `.luau`.
+*/
 pub fn remove_source_file_ext(path: &Path) -> PathBuf {
     if path
         .extension()
@@ -16,7 +19,10 @@ pub fn remove_source_file_ext(path: &Path) -> PathBuf {
     }
 }
 
-/// Writes the given bytes to a file at the specified path, and makes sure it has permissions to be executed
+/**
+    Writes the given bytes to a file at the specified path,
+    and makes sure it has permissions to be executed.
+*/
 pub async fn write_executable_file_to(
     path: impl AsRef<Path>,
     bytes: impl AsRef<[u8]>,

src/cli/build/mod.rs

@@ -52,7 +52,9 @@ impl BuildCommand {
             bail!("output path cannot be the same as input path, please specify a different output path");
         }
 
-        // Try to read the input file
+        // Try to read the given input file
+        // FUTURE: We should try and resolve a full require file graph using the input
+        // path here instead, see the notes in the `standalone` module for more details
         let source_code = fs::read(&self.input)
             .await
             .context("failed to read input file")?;

src/cli/build/result.rs

@@ -2,7 +2,9 @@ use thiserror::Error;
 
 use super::target::BuildTarget;
 
-/// Errors that may occur when building a standalone binary
+/**
+    Errors that may occur when building a standalone binary
+*/
 #[derive(Debug, Error)]
 pub enum BuildError {
     #[error("failed to find lune target '{0}' in GitHub release")]

src/cli/build/target.rs

@@ -12,7 +12,9 @@ const HOME_DIR: Lazy<PathBuf> = Lazy::new(|| {
 
 pub const CACHE_DIR: Lazy<PathBuf> = Lazy::new(|| HOME_DIR.join(".lune").join("target"));
 
-/// A target operating system supported by Lune
+/**
+    A target operating system supported by Lune
+*/
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BuildTargetOS {
     Windows,
@@ -69,7 +71,9 @@ impl FromStr for BuildTargetOS {
     }
 }
 
-/// A target architecture supported by Lune
+/**
+    A target architecture supported by Lune
+*/
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BuildTargetArch {
     X86_64,
@@ -106,7 +110,21 @@ impl FromStr for BuildTargetArch {
     }
 }
 
-/// A full target description for cross-compilation (OS + Arch)
+/**
+    A full target description that Lune supports (OS + Arch)
+
+    This is used to determine the target to build for standalone binaries,
+    and to download the correct base executable for cross-compilation.
+
+    The target may be parsed from and displayed in the form `os-arch`.
+    Examples of valid targets are:
+
+    - `linux-aarch64`
+    - `linux-x86_64`
+    - `macos-aarch64`
+    - `macos-x86_64`
+    - `windows-x86_64`
+*/
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BuildTarget {
     pub os: BuildTargetOS,