document the individual examples

examples/buffer_proto5.rs

@@ -1,6 +1,6 @@
-//! this example positions buffers adjacently and uses an ASYMMETRIC coil winding.
+//! this "example" positions ferromagnetic buffers adjacently and uses an ASYMMETRIC coil winding
-//! v.s. the fourth prototype, it changes the couplings in an attempt to reduce unwanted
+//! to couple them. i parameterize the entire setup over a bunch of different factors in order to
-//! clock -> mem2 coupling
+//! search for the conditions which maximize energy transfer from the one core to the other.
 
 use coremem::{Driver, mat, meas, SpirvDriver};
 use coremem::geom::{region, Cube, Dilate, Memoize, Meters, Region, Spiral, SwapYZ, Torus, Translate, Wrap};

examples/em_reflection.rs

@@ -1,3 +1,12 @@
+//! this example runs a *2-dimensional* simulation.
+//! it places a dissipative material (i.e. a conductor) on the left edge of the simulation
+//! and then radiates a vertical wavefront from the center of the simulation.
+//! it's about the bare-minimum simulation which still does something interesting.
+//!
+//! note that any practical simulation should probably terminate the simulation space
+//! with something that absorbs energy. since this example doesn't, it lets you see what
+//! happens when you just use the default boundary conditions.
+
 use coremem::{mat, driver};
 use coremem::geom::{Coord as _, Cube, Index, Vec3};
 use coremem::units::Seconds;

examples/sr_latch.rs

@@ -1,3 +1,8 @@
+/// this example creates a "set/reset" latch from a non-linear ferromagnetic device.
+/// this is quite a bit like a "core memory" device.
+/// the SR latch in this example is wired to a downstream latch, mostly to show that it's
+/// possible to transfer the state (with some limitation) from one latch to another.
+
 use coremem::{Driver, mat, meas, SpirvDriver};
 use coremem::geom::{Meters, Torus};
 use coremem::sim::spirv;