📝 Add docstrings to audit/language-safety-20260907

setup.sh

@@ -76,7 +76,7 @@ detect_shell() {
     printf "%s" "$CURRENT_SHELL"
 }
 
-# ── Platform Detection ──
+# detect_platform identifies the operating system, distribution, architecture, and available package manager, storing the results in global variables.
 detect_platform() {
     OS="unknown"
     DISTRO="unknown"
@@ -127,7 +127,7 @@ detect_platform() {
     esac
 }
 
-# install_just installs the `just` task runner using the detected package manager, or reports failure when it is unavailable.
+# install_just installs the `just` task runner using the detected package manager and reports whether installation succeeded.
 install_just() {
     if command -v just >/dev/null 2>&1; then
         ok "just already installed: $(just --version 2>/dev/null | head -1)"

src/codegen/mod.rs

@@ -18,13 +18,28 @@ use std::path::Path;
 
 use crate::manifest::Manifest;
 
-/// Generate all artifacts: Halide C++ source, schedule, and CMakeLists.txt.
+/// Generates the Halide generator source, runner source, and CMake configuration files.
 ///
-/// Output directory structure:
-///   <output_dir>/
-///     <name>_generator.cpp    — Halide generator (algorithm + schedule)
-///     <name>_runner.cpp       — Runner that loads input, runs pipeline, writes output
-///     CMakeLists.txt          — Build configuration for Halide
+/// The files are written to `output_dir` using the project name from the manifest:
+/// `<name>_generator.cpp`, `<name>_runner.cpp`, and `CMakeLists.txt`.
+///
+/// # Arguments
+///
+/// * `manifest` - Project manifest containing the pipeline and generation settings.
+/// * `output_dir` - Directory in which to write the generated files.
+///
+/// # Errors
+///
+/// Returns an error if the pipeline is invalid, the output directory cannot be created,
+/// or any generated file cannot be written.
+///
+/// # Examples
+///
+/// ```no_run
+/// # let manifest: Manifest = todo!();
+/// generate_all(&manifest, "generated")?;
+/// # Ok::<(), anyhow::Error>(())
+/// ```
 pub fn generate_all(manifest: &Manifest, output_dir: &str) -> Result<()> {
     let out = Path::new(output_dir);
     fs::create_dir_all(out).context("Failed to create output directory")?;
@@ -137,6 +152,23 @@ pub fn build(manifest: &Manifest, release: bool) -> Result<()> {
 /// # }
 /// ```
 pub fn run(manifest: &Manifest, args: &[String]) -> Result<()> {
+/// Runs the generated pipeline using the debug configuration.
+///
+/// # Arguments
+///
+/// * `args` - Arguments passed to the generated runner.
+///
+/// # Returns
+///
+/// `Ok(())` if the pipeline completes successfully; otherwise, an error.
+///
+/// # Examples
+///
+/// ```no_run
+/// let manifest = Manifest::default();
+/// run(&manifest, &[])?;
+/// # Ok::<(), _>(())
+/// ```
 pub fn run(manifest: &Manifest, args: &[String]) -> Result<()> {
     run_configuration(manifest, false, args)
 }

src/main.rs

@@ -96,6 +96,10 @@ enum Commands {
 /// let command = "halideiser info --manifest halideiser.toml";
 /// assert!(command.starts_with("halideiser "));
 /// ```
+///
+/// # Errors
+///
+/// Returns an error if the selected subcommand cannot complete successfully.
 fn main() -> Result<()> {
     let cli = Cli::parse();
     match cli.command {

tests/build_process.rs

@@ -35,6 +35,18 @@ fn fixture() -> tempfile::TempDir {
 ///
 /// Panics if the process cannot be started.
 fn invoke(doc?)
+/// Runs the `halideiser` binary in the specified directory with the given arguments.
+///
+/// # Examples
+///
+/// ```no_run
+/// let output = invoke(std::path::Path::new("."), &["build"]);
+/// assert!(output.status.success());
+/// ```
+///
+/// # Panics
+///
+/// Panics if the process cannot be started.
 fn invoke(dir: &std::path::Path, args: &[&str]) -> std::process::Output {
     Command::new(env!("CARGO_BIN_EXE_halideiser"))
         .current_dir(dir)