misc: add comments

crates/mun/src/ops/build.rs

@@ -8,6 +8,7 @@ use mun_project::MANIFEST_FILENAME;
 
 use crate::ExitStatus;
 
+/// Options for building Mun code
 struct BuildOptions {
     manifest_path: Option<String>,
     display_colors: DisplayColor,
@@ -19,7 +20,7 @@ struct BuildOptions {
 pub fn build(matches: &ArgMatches) -> Result<ExitStatus, anyhow::Error> {
     log::trace!("starting build");
 
-    let options = compiler_options(matches)?;
+    let options = extract_build_options(matches)?;
 
     // Locate the manifest
     let manifest_path = match options.manifest_path {
@@ -69,7 +70,8 @@ fn find_manifest(directory: &Path) -> Option<PathBuf> {
     None
 }
 
-fn compiler_options(matches: &ArgMatches) -> Result<BuildOptions, anyhow::Error> {
+/// Extract build options from the command line
+fn extract_build_options(matches: &ArgMatches) -> Result<BuildOptions, anyhow::Error> {
     let optimization_lvl = match matches.value_of("opt-level") {
         Some("0") => mun_compiler::OptimizationLevel::None,
         Some("1") => mun_compiler::OptimizationLevel::Less,

crates/mun_compiler/src/driver.rs

@@ -12,8 +12,6 @@ use hir::{
 use mun_codegen::{AssemblyIR, CodeGenDatabase, ModuleGroup, TargetAssembly};
 use paths::RelativePathBuf;
 
-use std::{path::PathBuf, sync::Arc};
-
 mod config;
 mod display_color;
 
@@ -22,8 +20,10 @@ pub use self::display_color::DisplayColor;
 
 use crate::diagnostics_snippets::{emit_hir_diagnostic, emit_syntax_error};
 use mun_project::{Package, LOCKFILE_NAME};
-use std::io::Cursor;
-use std::{collections::HashMap, convert::TryInto, path::Path, time::Duration};
+use std::{
+    collections::HashMap, convert::TryInto, io::Cursor, path::Path, path::PathBuf, sync::Arc,
+    time::Duration,
+};
 use walkdir::WalkDir;
 
 pub const WORKSPACE: SourceRootId = SourceRootId(0);
@@ -358,7 +358,9 @@ impl Driver {
             match lockfile::Lockfile::create(self.out_dir.join(LOCKFILE_NAME)) {
                 Ok(lockfile) => break lockfile,
                 Err(_) => {
-                    // TODO: Implement a better way to emit warnings/errors from the driver
+                    // TODO: Implement/abstract a better way to emit warnings/errors from the
+                    //  driver. Directly writing to stdout accesses global state. The driver is not
+                    //  aware of how to output logging information.
                     // if self.display_color.should_enable() {
                     //     eprintln!(
                     //         "{} on acquiring lock on output directory",

crates/mun_skeptic/src/lib.rs

@@ -1,13 +1,23 @@
+//! A crate to generate and run Mun tests based on mdbook content. It is based on
+//! [mdbook-test](https://github.com/Michael-F-Bryan/mdbook-test) and
+//! [rust-skeptic](https://github.com/budziq/rust-skeptic).
+
+#![warn(missing_docs)]
+
 pub mod runtime;
 
 use itertools::Itertools;
 use mdbook::renderer::RenderContext;
 use pulldown_cmark::{CodeBlockKind, Event, Parser, Tag};
-use std::cell::RefCell;
-use std::fs::File;
-use std::io::{Read, Write};
-use std::path::{Path, PathBuf};
-use std::{env, io, mem};
+use std::{
+    cell::RefCell,
+    env,
+    fs::File,
+    io,
+    io::{Read, Write},
+    mem,
+    path::{Path, PathBuf},
+};
 
 #[derive(Default)]
 struct BookStore {
@@ -278,6 +288,8 @@ fn emit_test_runner(test: &Test) -> io::Result<String> {
     Ok(String::from_utf8(s).unwrap())
 }
 
+/// Write the contents of the specified path but only if the contents is different. This ensures
+/// that a filesystem write event is only emitted when the content actually changes.
 fn write_if_contents_changed(name: &Path, contents: &str) -> io::Result<()> {
     // Can't open in write mode now as that would modify the last changed timestamp of the file
     match File::open(name) {

crates/mun_skeptic/src/runtime.rs

@@ -1,23 +1,34 @@
+//! Code to perform tests on Mun code.
+
 use mun_compiler::{Config, DisplayColor, PathOrInline, RelativePathBuf};
 use mun_runtime::{invoke_fn, RuntimeBuilder};
 
+/// The type of test to create
 #[derive(Copy, Clone)]
 pub enum TestMode {
+    /// Compile the code to ensure it compiles and run the `main` function which should not panic
     CompileAndRun,
+
+    /// Only compile the code to ensure its valid Mun code
     Compile,
+
+    /// Compile the code but it should fail to compile
     ShouldNotCompile,
 }
 
 impl TestMode {
+    /// Returns true if the Mun code of the test should be compiled
     fn should_compile(self) -> bool {
         matches!(self, TestMode::CompileAndRun | TestMode::Compile)
     }
 
+    /// Returns true if the Mun code should be invoked
     fn should_run(self) -> bool {
         matches!(self, TestMode::CompileAndRun)
     }
 }
 
+/// Run a Mun test with the specified `code`.
 pub fn run_test(code: &str, mode: TestMode) {
     // Construct a temporary path to store the output files
     let out_dir = tempdir::TempDir::new("mun_test_")