Docs update

Author: tgross35

crates/libm-test/examples/plot_domains.rs

@@ -1,3 +1,9 @@
+//! Program to write all inputs from a generator to a file, then invoke a Julia script
+//! to plot them. Requires Julia with the `CairoMakie` dependency.
+//!
+//! Note that running in release mode by default generates a _lot_ more datapoints, which
+//! causes plotting to be extremely slow (some simplification to done in the script).
+
 use std::io::{BufWriter, Write};
 use std::path::Path;
 use std::process::Command;
@@ -6,14 +12,15 @@ use std::{env, fs};
 use libm_test::domain::{Domain, SqrtDomain, TrigDomain, Unbounded};
 use libm_test::gen::domain;
 
+const JL_PLOT: &str = "examples/plot_file.jl";
+
 fn main() {
     let out_dir = Path::new("build");
     if !out_dir.exists() {
         fs::create_dir(out_dir).unwrap();
     }
 
-    let jl_script =
-        Path::new(&env::var("CARGO_MANIFEST_DIR").unwrap()).join("examples/plot_file.jl");
+    let jl_script = Path::new(&env::var("CARGO_MANIFEST_DIR").unwrap()).join(JL_PLOT);
 
     let mut j_args = Vec::new();
 
@@ -30,10 +37,11 @@ fn main() {
 }
 
 fn plot_one<D: Domain<f32>>(out_dir: &Path, name: &str, j_args: &mut Vec<String>) {
-    let base_name = out_dir.join(format!("{name}-inputs"));
+    let base_name = out_dir.join(format!("domain-inputs-{name}"));
     let text_file = base_name.with_extension("txt");
 
     {
+        // Scope for file and writer
         let f = fs::File::create(&text_file).unwrap();
         let mut w = BufWriter::new(f);
 

crates/libm-test/examples/plot_file.jl

@@ -1,4 +1,11 @@
-# using Plots
+"A quick script to for plotting a list of floats.
+
+Takes a list of floats and a real function, plots both on a graph in both
+linear and log scale. Requires [Makie] (specifically CairoMakie) for plotting.
+
+[Makie]: https://docs.makie.org/stable/
+"
+
 using CairoMakie
 
 CairoMakie.activate!(px_per_unit=10)
@@ -24,10 +31,11 @@ function plot_one(
     f::Function;
     xlims::Union{Tuple{Any,Any},Nothing},
     xlims_log::Union{Tuple{Any,Any},Nothing},
-)
+)::Nothing
     float_file = "$base_name.txt"
     lin_out_file = "$base_name.png"
     log_out_file = "$base_name-log.png"
+
     if xlims === nothing
         xlims = (-6, 6)
     end
@@ -62,6 +70,7 @@ function plot_one(
     delete!(ax)
 end
 
+# Args alternate `name1 path1 name2 path2`
 fn_names = ARGS[1:2:end]
 base_names = ARGS[2:2:end]
 
@@ -100,8 +109,5 @@ for idx in eachindex(fn_names)
     )
 end
 
-
 base_name = ARGS[1]
 fn_name = ARGS[2]
-
-

crates/libm-test/src/f8_impl.rs

@@ -1,16 +1,19 @@
+//! A IEEE-compliant 8-bit float type for testing purposes.
+
 use std::cmp::{self, Ordering};
 use std::{fmt, ops};
 
 use crate::Float;
 
-/// Sometimes verifying float logic is easiest when all values can easily be checked exhaustively
+/// Sometimes verifying float logic is easiest when all values can quickly be checked exhaustively
 /// or by hand.
 ///
 /// IEEE-754 compliant type that includes a 1 bit sign, 4 bit exponent, and 3 bit significand.
 /// Bias is -7.
 ///
 /// Based on <https://en.wikipedia.org/wiki/Minifloat#Example_8-bit_float_(1.4.3)>.
 #[derive(Clone, Copy)]
+#[repr(transparent)]
 #[allow(non_camel_case_types)]
 pub struct f8(u8);