intrinsic-test: document common::gen_rust

Author: davidtwco

crates/intrinsic-test/src/common/gen_rust.rs

@@ -6,10 +6,13 @@ use crate::common::argument::ArgumentList;
 use crate::common::intrinsic::Intrinsic;
 use crate::common::intrinsic_helpers::TypeKind;
 
-// The number of times each intrinsic will be called.
+// The number of times each intrinsic will be called - influences the generation of the
+// test arrays to minimise repeated testing of the same test values.
 pub(crate) const PASSES: u32 = 20;
 
-// we need a reflexive equality relation, so treat NaNs as equal
+/// Rust definitions that are included verbatim in the generated source. In particular, defines
+/// a wrapper around float types that defines `NaN`s to be equal reflexively to enable
+/// comparison of results that use floats types.
 const COMMON_RUST_DEFINITIONS: &str = r#"
 macro_rules! wrap_partialeq {
     ($($wrapper:ident ($inner:ty)),*) => {$(
@@ -36,6 +39,13 @@ macro_rules! concatln {
     };
 }
 
+/// Writes a `Cargo.toml` containing a workspace with `module_count` members to `w`.
+///
+/// e.g.
+/// ```toml
+/// [workspace]
+/// members = [ "mod_0", "mod_1" ]
+/// ```
 pub fn write_bin_cargo_toml(
     w: &mut impl std::io::Write,
     module_count: usize,
@@ -47,6 +57,8 @@ pub fn write_bin_cargo_toml(
     writeln!(w, "]")
 }
 
+/// Writes a `Cargo.toml` for a crate with name `name` to `w` that will contain a single Rust source
+/// file with a subset of the testing being generated.
 pub fn write_lib_cargo_toml(w: &mut impl std::io::Write, name: &str) -> std::io::Result<()> {
     write!(
         w,
@@ -73,6 +85,8 @@ pub fn write_lib_cargo_toml(w: &mut impl std::io::Write, name: &str) -> std::io:
     )
 }
 
+/// Writes a Rust source file into `w` with common definitions, static arrays with test values,
+/// declarations of C wrapper functions for FFI and Rust test functions.
 pub fn write_lib_rs<T: IntrinsicTypeDefinition>(
     w: &mut impl std::io::Write,
     notice: &str,
@@ -121,6 +135,13 @@ pub fn write_lib_rs<T: IntrinsicTypeDefinition>(
     Ok(())
 }
 
+/// Writes the body of an intrinsic test to `w` for `intrinsic`.
+///
+/// Each specialisation of the intrinsic (i.e. specific instantiations of the immediate arguments
+/// of the intrinsic) is added to an array of specialisations. Each specialisation is tested
+/// (first loop) `PASSES` number of times (second loop). For a given iteration of a given
+/// specialisation, test values are loaded for each argument and passed to the Rust intrinsic
+/// and the C wrapper function, and the results are compared.
 fn generate_rust_test_loop<T: IntrinsicTypeDefinition>(
     w: &mut impl std::io::Write,
     intrinsic: &Intrinsic<T>,
@@ -216,6 +237,8 @@ fn generate_rust_test_loop<T: IntrinsicTypeDefinition>(
     )
 }
 
+/// Writes a test function for an given intrinsic to `w`, with a body generated by
+/// `generate_rust_test_loop`.
 fn create_rust_test<T: IntrinsicTypeDefinition>(
     w: &mut impl std::io::Write,
     intrinsic: &Intrinsic<T>,
@@ -235,6 +258,8 @@ fn create_rust_test<T: IntrinsicTypeDefinition>(
     Ok(())
 }
 
+/// Writes an `extern "C"` block with function declarations for each of the C wrapper functions into
+/// `w`.
 pub fn write_bindings_rust<T: IntrinsicTypeDefinition>(
     w: &mut impl std::io::Write,
     i: usize,
@@ -268,6 +293,8 @@ pub fn write_bindings_rust<T: IntrinsicTypeDefinition>(
     writeln!(w, "}}")
 }
 
+/// Writes a `build.rs` into `w` for each test crate that compiles the corresponding C source code
+/// with wrapper functions.
 pub fn write_build_rs(
     w: &mut impl std::io::Write,
     i: usize,