Better names and comments (#34)

execution-plan/src/api_endpoint.rs

@@ -7,14 +7,20 @@ use uuid::Uuid;
 
 use crate::{primitive::Primitive, value::Value, Address, ExecutionError, Memory, Result};
 
+/// All API endpoints that can be executed must implement this trait.
 pub trait ApiEndpoint: ModelingCmdVariant + Sized {
-    fn from_values<I>(values: &mut I, mem: &Memory) -> Result<Self>
+    /// Read the API call and its parameters from memory.
+    /// For each field in the API endpoint's body,
+    /// 1. Read that field's address from the `fields` iterator.
+    /// 2. Look up the value at that address
+    /// Then use those fields to reconstruct the entire struct.
+    fn from_memory<I>(fields: &mut I, mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>;
 }
 
 impl ApiEndpoint for StartPath {
-    fn from_values<I>(_values: &mut I, _mem: &Memory) -> Result<Self>
+    fn from_memory<I>(_fields: &mut I, _mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>,
     {
@@ -23,50 +29,50 @@ impl ApiEndpoint for StartPath {
 }
 
 impl ApiEndpoint for MovePathPen {
-    fn from_values<I>(values: &mut I, mem: &Memory) -> Result<Self>
+    fn from_memory<I>(fields: &mut I, mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>,
     {
-        let path: Uuid = read::<Primitive>(values.next(), mem)?.try_into()?;
+        let path: Uuid = read::<Primitive>(fields.next(), mem)?.try_into()?;
         let path = ModelingCmdId::from(path);
-        let to = read(values.next(), mem)?;
+        let to = read(fields.next(), mem)?;
         Ok(Self { path, to })
     }
 }
 
 impl ApiEndpoint for ExtendPath {
-    fn from_values<I>(values: &mut I, mem: &Memory) -> Result<Self>
+    fn from_memory<I>(fields: &mut I, mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>,
     {
-        let path = read::<Primitive>(values.next(), mem)
+        let path = read::<Primitive>(fields.next(), mem)
             .and_then(Uuid::try_from)
             .map(ModelingCmdId::from)?;
-        let segment = read(values.next(), mem)?;
+        let segment = read(fields.next(), mem)?;
         Ok(Self { path, segment })
     }
 }
 
 impl ApiEndpoint for Extrude {
-    fn from_values<I>(values: &mut I, mem: &Memory) -> Result<Self>
+    fn from_memory<I>(fields: &mut I, mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>,
     {
-        let target = read::<Primitive>(values.next(), mem)
+        let target = read::<Primitive>(fields.next(), mem)
             .and_then(Uuid::try_from)
             .map(ModelingCmdId)?;
-        let distance = read::<Primitive>(values.next(), mem).and_then(f64::try_from)?;
-        let cap = read::<Primitive>(values.next(), mem).and_then(bool::try_from)?;
+        let distance = read::<Primitive>(fields.next(), mem).and_then(f64::try_from)?;
+        let cap = read::<Primitive>(fields.next(), mem).and_then(bool::try_from)?;
         Ok(Self { target, distance, cap })
     }
 }
 
 impl ApiEndpoint for TakeSnapshot {
-    fn from_values<I>(values: &mut I, mem: &Memory) -> Result<Self>
+    fn from_memory<I>(fields: &mut I, mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>,
     {
-        let format_str = read::<Primitive>(values.next(), mem).and_then(String::try_from)?;
+        let format_str = read::<Primitive>(fields.next(), mem).and_then(String::try_from)?;
         let format = format_str.parse().map_err(|_| ExecutionError::InvalidEnumVariant {
             expected_type: "image format".to_owned(),
             actual: format_str,
@@ -76,11 +82,11 @@ impl ApiEndpoint for TakeSnapshot {
 }
 
 impl ApiEndpoint for ClosePath {
-    fn from_values<I>(values: &mut I, mem: &Memory) -> Result<Self>
+    fn from_memory<I>(fields: &mut I, mem: &Memory) -> Result<Self>
     where
         I: Iterator<Item = Address>,
     {
-        let path_id = read::<Primitive>(values.next(), mem).and_then(Uuid::try_from)?;
+        let path_id = read::<Primitive>(fields.next(), mem).and_then(Uuid::try_from)?;
         Ok(Self { path_id })
     }
 }

execution-plan/src/lib.rs

@@ -149,27 +149,27 @@ impl ApiRequest {
         let mut arguments = arguments.into_iter();
         let output = match endpoint {
             Endpoint::StartPath => {
-                let cmd = each_cmd::StartPath::from_values(&mut arguments, mem)?;
+                let cmd = each_cmd::StartPath::from_memory(&mut arguments, mem)?;
                 session.run_command(cmd_id, cmd).await?
             }
             Endpoint::MovePathPen => {
-                let cmd = each_cmd::MovePathPen::from_values(&mut arguments, mem)?;
+                let cmd = each_cmd::MovePathPen::from_memory(&mut arguments, mem)?;
                 session.run_command(cmd_id, cmd).await?
             }
             Endpoint::ExtendPath => {
-                let cmd = each_cmd::ExtendPath::from_values(&mut arguments, mem)?;
+                let cmd = each_cmd::ExtendPath::from_memory(&mut arguments, mem)?;
                 session.run_command(cmd_id, cmd).await?
             }
             Endpoint::ClosePath => {
-                let cmd = each_cmd::ClosePath::from_values(&mut arguments, mem)?;
+                let cmd = each_cmd::ClosePath::from_memory(&mut arguments, mem)?;
                 session.run_command(cmd_id, cmd).await?
             }
             Endpoint::Extrude => {
-                let cmd = each_cmd::Extrude::from_values(&mut arguments, mem)?;
+                let cmd = each_cmd::Extrude::from_memory(&mut arguments, mem)?;
                 session.run_command(cmd_id, cmd).await?
             }
             Endpoint::TakeSnapshot => {
-                let cmd = each_cmd::TakeSnapshot::from_values(&mut arguments, mem)?;
+                let cmd = each_cmd::TakeSnapshot::from_memory(&mut arguments, mem)?;
                 session.run_command(cmd_id, cmd).await?
             }
         };