misc: add comments

crates/mun_skeptic/src/lib.rs

@@ -1,13 +1,21 @@
+//! A crate to generate and run Mun tests based on mdbook content.
+
+#![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 +286,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_")