Minor doc updates (#154)

fidget/src/core/context/mod.rs

@@ -11,8 +11,8 @@
 //!   they have been constructed.
 //! - A [`Context`] is an arena for unique (deduplicated) math expressions,
 //!   which are represented as [`Node`] handles.  Each `Node` is specific to a
-//!   particular context.  Only `Node` objects can be converted into `Function`
-//!   objects for evaluation.
+//!   particular context.  Only `Node` objects can be converted into
+//!   [`Function`](crate::eval::Function) objects for evaluation.
 //!
 //! In other words, the typical workflow is `Tree → (Context, Node) → Function`.
 mod indexed;

fidget/src/core/eval/bulk.rs

@@ -9,6 +9,12 @@
 use crate::{eval::Tape, Error};
 
 /// Trait for bulk evaluation returning the given type `T`
+///
+/// Bulk evaluators should usually be constructed on a per-thread basis.
+///
+/// They contain (at minimum) output array storage, which is borrowed in the
+/// return from [`eval`](BulkEvaluator::eval).  They may also contain
+/// intermediate storage (e.g. an array of VM registers).
 pub trait BulkEvaluator: Default {
     /// Data type used during evaluation
     type Data: From<f32> + Copy + Clone;
@@ -30,6 +36,8 @@ pub trait BulkEvaluator: Default {
     /// input arguments for each of the tape's variables; use [`Tape::vars`] to
     /// map from [`Var`](crate::var::Var) to position in the list.
     ///
+    /// The returned slice is borrowed from the evaluator.
+    ///
     /// Returns an error if any of the `var` slices are of different lengths, or
     /// if all variables aren't present.
     fn eval<V: std::ops::Deref<Target = [Self::Data]>>(

fidget/src/core/eval/tracing.rs

@@ -15,6 +15,9 @@ use crate::{eval::Tape, Error};
 /// The trace can later be used to simplify the
 /// [`Function`](crate::eval::Function)
 /// using [`Function::simplify`](crate::eval::Function::simplify).
+///
+/// Tracing evaluators may contain intermediate storage (e.g. an array of VM
+/// registers), and should be constructed on a per-thread basis.
 pub trait TracingEvaluator: Default {
     /// Data type used during evaluation
     type Data: From<f32> + Copy + Clone;