Merge pull request #2187 from hannobraun/form

Rename implementations of `Form`; update documentation around there

crates/fj-core/src/objects/any_object.rs

@@ -9,11 +9,12 @@ use crate::{
 
 macro_rules! any_object {
     ($($ty:ident, $name:expr, $store:ident;)*) => {
-        /// An enum that can hold object
+        /// An enum that can hold any object
         ///
         /// This enum is generic over the form that the object takes. An
-        /// `AnyObject<Bare>` contains bare objects, like `Curve`. An
-        /// `AnyObject<BehindHandle>` contains handles, like `Handle<Curve>`.
+        /// `AnyObject<Bare>` contains a bare objects, for example `Curve`. An
+        /// `AnyObject<Stored>` contains a handle referencing a stored object,
+        /// for example `Handle<Curve>`.
         #[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
         pub enum AnyObject<F: Form> {
             $(
@@ -22,7 +23,7 @@ macro_rules! any_object {
             )*
         }
 
-        impl AnyObject<BehindHandle> {
+        impl AnyObject<Stored> {
             /// Access the ID of the object
             pub fn id(&self) -> ObjectId {
                 match self {
@@ -42,7 +43,10 @@ macro_rules! any_object {
             }
 
             /// Validate the object with a pre-defined validation configuration
-            pub fn validate_with_config(&self, config: &ValidationConfig, errors: &mut Vec<ValidationError>) {
+            pub fn validate_with_config(&self,
+                    config: &ValidationConfig,
+                    errors: &mut Vec<ValidationError>
+            ) {
                 match self {
                     $(
                         Self::$ty(object) => object.validate_with_config(config, errors),
@@ -51,11 +55,9 @@ macro_rules! any_object {
             }
         }
 
-        impl AnyObject<WithHandle> {
+        impl AnyObject<AboutToBeStored> {
             /// Insert the object into its respective store
-            pub fn insert(self, objects: &mut Objects) ->
-                AnyObject<BehindHandle>
-            {
+            pub fn insert(self, objects: &mut Objects) -> AnyObject<Stored> {
                 match self {
                     $(
                         Self::$ty((handle, object)) => {
@@ -69,8 +71,8 @@ macro_rules! any_object {
             }
         }
 
-        impl From<AnyObject<WithHandle>> for AnyObject<BehindHandle> {
-            fn from(object: AnyObject<WithHandle>) -> Self {
+        impl From<AnyObject<AboutToBeStored>> for AnyObject<Stored> {
+            fn from(object: AnyObject<AboutToBeStored>) -> Self {
                 match object {
                     $(
                         AnyObject::$ty((handle, _)) => Self::$ty(handle.into()),
@@ -86,13 +88,13 @@ macro_rules! any_object {
                 }
             }
 
-            impl From<Handle<$ty>> for AnyObject<BehindHandle> {
+            impl From<Handle<$ty>> for AnyObject<Stored> {
                 fn from(object: Handle<$ty>) -> Self {
                     Self::$ty(object.into())
                 }
             }
 
-            impl From<(Handle<$ty>, $ty)> for AnyObject<WithHandle> {
+            impl From<(Handle<$ty>, $ty)> for AnyObject<AboutToBeStored> {
                 fn from((handle, object): (Handle<$ty>, $ty)) -> Self {
                     Self::$ty((handle.into(), object))
                 }
@@ -116,8 +118,10 @@ any_object!(
 
 /// The form that an object can take
 ///
-/// An object can be bare ([`Bare`]), behind a [`Handle`] ([`BehindHandle`]), or
-/// can take the form of a handle *and* an object [`WithHandle`].
+/// This is used together with [`AnyObject`].
+///
+/// An object can be bare ([`Bare`]), stored ([`Stored`]), or it can be about to
+/// be - but not yet - stored ([`AboutToBeStored`]).
 pub trait Form {
     /// The form that the object takes
     type Form<T>;
@@ -131,18 +135,24 @@ impl Form for Bare {
     type Form<T> = T;
 }
 
-/// Implementation of [`Form`] for objects behind a handle
+/// Implementation of [`Form`] for stored objects
 #[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
-pub struct BehindHandle;
+pub struct Stored;
 
-impl Form for BehindHandle {
+impl Form for Stored {
     type Form<T> = HandleWrapper<T>;
 }
 
-/// Implementation of [`Form`] for objects that are paired with their handle
+/// Implementation of [`Form`] for objects that are about to be stored
+///
+/// When storing an object, a [`Handle`] instance is generated first. Then both
+/// that [`Handle`] instance and the bare object are sent to the object service,
+/// for storage.
+///
+/// This is the one use case where this form is required.
 #[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
-pub struct WithHandle;
+pub struct AboutToBeStored;
 
-impl Form for WithHandle {
+impl Form for AboutToBeStored {
     type Form<T> = (HandleWrapper<T>, T);
 }

crates/fj-core/src/objects/mod.rs

@@ -46,7 +46,7 @@ mod object_set;
 mod stores;
 
 pub use self::{
-    any_object::{AnyObject, Bare, BehindHandle, Form, WithHandle},
+    any_object::{AboutToBeStored, AnyObject, Bare, Form, Stored},
     is_object::IsObject,
     kinds::{
         curve::Curve,

crates/fj-core/src/services/mod.rs

@@ -7,7 +7,7 @@ mod service;
 mod validation;
 
 use crate::{
-    objects::{AnyObject, Objects, WithHandle},
+    objects::{AboutToBeStored, AnyObject, Objects},
     validate::{ValidationConfig, ValidationErrors},
 };
 
@@ -54,7 +54,7 @@ impl Services {
     }
 
     /// Insert an object into the stores
-    pub fn insert_object(&mut self, object: AnyObject<WithHandle>) {
+    pub fn insert_object(&mut self, object: AnyObject<AboutToBeStored>) {
         let mut object_events = Vec::new();
         self.objects
             .execute(Operation::InsertObject { object }, &mut object_events);

crates/fj-core/src/services/objects.rs

@@ -1,4 +1,4 @@
-use crate::objects::{AnyObject, Objects, WithHandle};
+use crate::objects::{AboutToBeStored, AnyObject, Objects};
 
 use super::State;
 
@@ -25,13 +25,13 @@ pub enum Operation {
     /// upon.
     InsertObject {
         /// The object to insert
-        object: AnyObject<WithHandle>,
+        object: AnyObject<AboutToBeStored>,
     },
 }
 
 /// Event produced by `Service<Objects>`
 #[derive(Clone, Debug)]
 pub struct InsertObject {
     /// The object to insert
-    pub object: AnyObject<WithHandle>,
+    pub object: AnyObject<AboutToBeStored>,
 }

crates/fj-core/src/services/validation.rs

@@ -1,7 +1,7 @@
 use std::{collections::BTreeMap, error::Error, thread};
 
 use crate::{
-    objects::{AnyObject, BehindHandle},
+    objects::{AnyObject, Stored},
     storage::ObjectId,
     validate::{ValidationConfig, ValidationError},
 };
@@ -97,7 +97,7 @@ pub enum ValidationCommand {
     /// Validate the provided object
     ValidateObject {
         /// The object to validate
-        object: AnyObject<BehindHandle>,
+        object: AnyObject<Stored>,
     },
 }
 
@@ -107,7 +107,7 @@ pub enum ValidationEvent {
     /// Validation of an object failed
     ValidationFailed {
         /// The object for which validation failed
-        object: AnyObject<BehindHandle>,
+        object: AnyObject<Stored>,
 
         /// The validation error
         err: ValidationError,