Add full structural information to runtime interface

frame_runtime/src/environment.rs → frame_runtime/src/env.rs

@@ -1,22 +1,18 @@
-//! This module provides a generic interface to the various structs that Frame
-//! generates to realize name bindings.
-//!
-//! Some brief design rationale:
-//!
-//!  * Environments are defined as a trait rather than a simple HashMap so that
-//!    we can directly reuse the argument structs generated by Frame rather
-//!    than constructing a bunch of parallel data structures each time we query
-//!    the state of the machine.
-//!  
-//!  * It is common for a particular environment to be absent because there are
-//!    no variables of the kind held by that environment. We represent absent
-//!    environments by an empty environment rather than using an `Option` type
-//!    because it simplifies the interface and because the distinction between
-//!    `None` and `Some(EMPTY)` is not significant.
+//! This module provides a generic interface to the various structs that Frame generates to realize
+//! name bindings.
 
 use std::any::Any;
 
 /// Environments associate names (i.e. variables/parameters) with values.
+///
+/// Environments are defined as a trait rather than a simple HashMap so that we can directly reuse
+/// the various structs generated by Frame rather than constructing a bunch of parallel data
+/// structures each time we query the state of the machine.
+///  
+/// It is common for a particular environment to be absent because there are no variables of the
+/// kind held by that environment. We represent absent environments by an empty environment rather
+/// than using an `Option` type because it simplifies the interface and because the distinction
+/// between `None` and `Some(EMPTY)` is not significant.
 pub trait Environment {
     /// Is this the empty environment?
     fn is_empty(&self) -> bool {
@@ -26,8 +22,8 @@ pub trait Environment {
     fn lookup(&self, name: &str) -> Option<&dyn Any>;
 }
 
-/// The trivial empty environment. This can be used in place of an environment
-/// when that environment is absent.
+/// The trivial empty environment. This can be used in place of an environment when that
+/// environment is absent.
 pub const EMPTY: &'static dyn Environment = &EmptyEnvironment {};
 
 struct EmptyEnvironment {}