Added method docs.

horned-sphere · horned-sphere · commit f5d20885ae91 · 2024-04-26T09:15:28.000+01:00
diff --git a/server/swimos_agent/src/lanes/join/map/mod.rs b/server/swimos_agent/src/lanes/join/map/mod.rs
@@ -667,6 +667,8 @@ where
     }
 }
 
+/// A [`HandlerAction`] that will produce a value by applying a closure to a reference to
+/// and entry in the lane.
 pub struct JoinMapLaneWithEntry<C, L, K, V, F, B: ?Sized> {
     projection: for<'a> fn(&'a C) -> &'a JoinMapLane<L, K, V>,
     key: K,
@@ -675,6 +677,10 @@ pub struct JoinMapLaneWithEntry<C, L, K, V, F, B: ?Sized> {
 }
 
 impl<C, L, K, V, F, B: ?Sized> JoinMapLaneWithEntry<C, L, K, V, F, B> {
+    /// #Arguments
+    /// * `projection` - Projection from the agent context to the lane.
+    /// * `key` - Key of the entry.
+    /// * `f` - The closure to apply to the entry.
     pub fn new(projection: for<'a> fn(&'a C) -> &'a JoinMapLane<L, K, V>, key: K, f: F) -> Self {
         JoinMapLaneWithEntry {
             projection,
diff --git a/server/swimos_agent/src/lanes/join/value/mod.rs b/server/swimos_agent/src/lanes/join/value/mod.rs
@@ -428,6 +428,8 @@ impl<C, K, V> JoinValueAddDownlink<C, K, V> {
     }
 }
 
+/// A [`HandlerAction`] that will produce a value by applying a closure to a reference to
+/// and entry in the lane.
 pub struct JoinValueLaneWithEntry<C, K, V, F, B: ?Sized> {
     projection: for<'a> fn(&'a C) -> &'a JoinValueLane<K, V>,
     key: K,
@@ -436,6 +438,10 @@ pub struct JoinValueLaneWithEntry<C, K, V, F, B: ?Sized> {
 }
 
 impl<C, K, V, F, B: ?Sized> JoinValueLaneWithEntry<C, K, V, F, B> {
+    /// #Arguments
+    /// * `projection` - Projection from the agent context to the lane.
+    /// * `key` - Key of the entry.
+    /// * `f` - The closure to apply to the entry.
     pub fn new(projection: for<'a> fn(&'a C) -> &'a JoinValueLane<K, V>, key: K, f: F) -> Self {
         JoinValueLaneWithEntry {
             projection,
diff --git a/server/swimos_agent/src/lanes/map/mod.rs b/server/swimos_agent/src/lanes/map/mod.rs
@@ -35,7 +35,7 @@ use crate::{
         Modification, StepResult,
     },
     item::{AgentItem, InspectableMapLikeItem, MapItem, MapLikeItem, MutableMapLikeItem},
-    map_storage::{MapStoreInner, WithEntryResult},
+    map_storage::{MapStoreInner, TransformEntryResult},
     meta::AgentMetadata,
 };
 
@@ -104,7 +104,7 @@ where
     }
 
     /// Transform the value associated with a key.
-    pub fn transform_entry<F>(&self, key: K, f: F) -> WithEntryResult
+    pub fn transform_entry<F>(&self, key: K, f: F) -> TransformEntryResult
     where
         F: FnOnce(Option<&V>) -> Option<V>,
     {
@@ -394,13 +394,19 @@ where
     }
 }
 
+/// A [`HandlerAction`] that will produce a value by applying a closure to a reference to
+/// and entry in the lane.
 pub struct MapLaneWithEntry<C, K, V, F, B: ?Sized> {
     projection: for<'a> fn(&'a C) -> &'a MapLane<K, V>,
     key_and_f: Option<(K, F)>,
     _type: PhantomData<fn(&B)>,
 }
 
 impl<C, K, V, F, B: ?Sized> MapLaneWithEntry<C, K, V, F, B> {
+    /// #Arguments
+    /// * `projection` - Projection from the agent context to the lane.
+    /// * `key` - Key of the entry.
+    /// * `f` - The closure to apply to the entry.
     pub fn new(projection: for<'a> fn(&'a C) -> &'a MapLane<K, V>, key: K, f: F) -> Self {
         MapLaneWithEntry {
             projection,
@@ -620,7 +626,7 @@ where
         } = self;
         if let Some((key, f)) = key_and_f.take() {
             let lane = projection(context);
-            if matches!(lane.transform_entry(key, f), WithEntryResult::NoChange) {
+            if matches!(lane.transform_entry(key, f), TransformEntryResult::NoChange) {
                 StepResult::done(())
             } else {
                 StepResult::Complete {
diff --git a/server/swimos_agent/src/lanes/value/mod.rs b/server/swimos_agent/src/lanes/value/mod.rs
@@ -274,13 +274,17 @@ impl<C, T> HandlerAction<C> for ValueLaneSync<C, T> {
     }
 }
 
+/// An [`HandlerAction`] that will produce a value from a reference to the contents of the lane.
 pub struct ValueLaneWithValue<C, T, F, B: ?Sized> {
     projection: for<'a> fn(&'a C) -> &'a ValueLane<T>,
     f: Option<F>,
     _type: PhantomData<fn(&B)>,
 }
 
 impl<C, T, F, B: ?Sized> ValueLaneWithValue<C, T, F, B> {
+    /// #Arguments
+    /// * `projection` - Projection from the agent context to the lane.
+    /// * `f` - Closure to apply to the value of the lane.
     pub fn new(projection: for<'a> fn(&'a C) -> &'a ValueLane<T>, f: F) -> Self {
         ValueLaneWithValue {
             projection,
diff --git a/server/swimos_agent/src/map_storage/mod.rs b/server/swimos_agent/src/map_storage/mod.rs
@@ -52,7 +52,7 @@ impl<K, V, Q: Default> MapStoreInner<K, V, Q> {
     }
 }
 
-pub enum WithEntryResult {
+pub enum TransformEntryResult {
     NoChange,
     Update,
     Remove,
@@ -78,7 +78,7 @@ where
         queue.push(MapOperation::Update { key, value: () });
     }
 
-    pub fn transform_entry<F>(&mut self, key: K, f: F) -> WithEntryResult
+    pub fn transform_entry<F>(&mut self, key: K, f: F) -> TransformEntryResult
     where
         F: FnOnce(Option<&V>) -> Option<V>,
     {
@@ -93,22 +93,22 @@ where
                     content.insert(key.clone(), v2);
                     *previous = Some(MapLaneEvent::Update(key.clone(), Some(v)));
                     queue.push(MapOperation::Update { key, value: () });
-                    WithEntryResult::Update
+                    TransformEntryResult::Update
                 }
                 _ => {
                     *previous = Some(MapLaneEvent::Remove(key.clone(), v));
                     queue.push(MapOperation::Remove { key: key.clone() });
-                    WithEntryResult::Remove
+                    TransformEntryResult::Remove
                 }
             },
             _ => match f(None) {
                 Some(v2) => {
                     content.insert(key.clone(), v2);
                     *previous = Some(MapLaneEvent::Update(key.clone(), None));
                     queue.push(MapOperation::Update { key, value: () });
-                    WithEntryResult::Update
+                    TransformEntryResult::Update
                 }
-                _ => WithEntryResult::NoChange,
+                _ => TransformEntryResult::NoChange,
             },
         }
     }
diff --git a/server/swimos_agent/src/stores/map/mod.rs b/server/swimos_agent/src/stores/map/mod.rs
@@ -27,7 +27,7 @@ use crate::agent_model::WriteResult;
 use crate::event_handler::{ActionContext, HandlerAction, Modification, StepResult};
 use crate::event_queue::EventQueue;
 use crate::item::{AgentItem, InspectableMapLikeItem, MapItem, MapLikeItem, MutableMapLikeItem};
-use crate::map_storage::{MapStoreInner, WithEntryResult};
+use crate::map_storage::{MapStoreInner, TransformEntryResult};
 use crate::meta::AgentMetadata;
 
 use super::StoreItem;
@@ -92,7 +92,7 @@ where
     }
 
     /// Transform the value associated with a key.
-    pub fn transform_entry<F>(&self, key: K, f: F) -> WithEntryResult
+    pub fn transform_entry<F>(&self, key: K, f: F) -> TransformEntryResult
     where
         F: FnOnce(Option<&V>) -> Option<V>,
     {
@@ -413,7 +413,10 @@ where
         } = self;
         if let Some((key, f)) = key_and_f.take() {
             let store = projection(context);
-            if matches!(store.transform_entry(key, f), WithEntryResult::NoChange) {
+            if matches!(
+                store.transform_entry(key, f),
+                TransformEntryResult::NoChange
+            ) {
                 StepResult::done(())
             } else {
                 StepResult::Complete {
@@ -427,13 +430,19 @@ where
     }
 }
 
+/// A [`HandlerAction`] that will produce a value by applying a closure to a reference to
+/// and entry in the store.
 pub struct MapStoreWithEntry<C, K, V, F, B: ?Sized> {
     projection: for<'a> fn(&'a C) -> &'a MapStore<K, V>,
     key_and_f: Option<(K, F)>,
     _type: PhantomData<fn(&B)>,
 }
 
 impl<C, K, V, F, B: ?Sized> MapStoreWithEntry<C, K, V, F, B> {
+    /// #Arguments
+    /// * `projection` - Projection from the agent context to the store.
+    /// * `key` - Key of the entry.
+    /// * `f` - The closure to apply to the entry.
     pub fn new(projection: for<'a> fn(&'a C) -> &'a MapStore<K, V>, key: K, f: F) -> Self {
         MapStoreWithEntry {
             projection,
diff --git a/server/swimos_agent/src/stores/value/mod.rs b/server/swimos_agent/src/stores/value/mod.rs
@@ -276,13 +276,17 @@ impl<C, T> HandlerAction<C> for ValueStoreSet<C, T> {
     }
 }
 
+/// An [`HandlerAction`] that will produce a value from a reference to the contents of the store.
 pub struct ValueStoreWithValue<C, T, F, B: ?Sized> {
     projection: for<'a> fn(&'a C) -> &'a ValueStore<T>,
     f: Option<F>,
     _type: PhantomData<fn(&B)>,
 }
 
 impl<C, T, F, B: ?Sized> ValueStoreWithValue<C, T, F, B> {
+    /// #Arguments
+    /// * `projection` - Projection from the agent context to the store.
+    /// * `f` - Closure to apply to the value of the store.
     pub fn new(projection: for<'a> fn(&'a C) -> &'a ValueStore<T>, f: F) -> Self {
         ValueStoreWithValue {
             projection,

Original file line number	Diff line number	Diff line change
`@@ -667,6 +667,8 @@ where`
`667`	`667`	`}`
`668`	`668`	`}`
`669`	`669`
	`670`	+/// A [`HandlerAction`] that will produce a value by applying a closure to a reference to
	`671`	`+/// and entry in the lane.`
`670`	`672`	`pub struct JoinMapLaneWithEntry<C, L, K, V, F, B: ?Sized> {`
`671`	`673`	`projection: for<'a> fn(&'a C) -> &'a JoinMapLane<L, K, V>,`
`672`	`674`	`key: K,`
`@@ -675,6 +677,10 @@ pub struct JoinMapLaneWithEntry<C, L, K, V, F, B: ?Sized> {`
`675`	`677`	`}`
`676`	`678`
`677`	`679`	`impl<C, L, K, V, F, B: ?Sized> JoinMapLaneWithEntry<C, L, K, V, F, B> {`
	`680`	`+ /// #Arguments`
	`681`	+ /// * `projection` - Projection from the agent context to the lane.
	`682`	+ /// * `key` - Key of the entry.
	`683`	+ /// * `f` - The closure to apply to the entry.
`678`	`684`	`pub fn new(projection: for<'a> fn(&'a C) -> &'a JoinMapLane<L, K, V>, key: K, f: F) -> Self {`
`679`	`685`	`JoinMapLaneWithEntry {`
`680`	`686`	`projection,`
Original file line number	Diff line number	Diff line change
`@@ -428,6 +428,8 @@ impl<C, K, V> JoinValueAddDownlink<C, K, V> {`
`428`	`428`	`}`
`429`	`429`	`}`
`430`	`430`
	`431`	+/// A [`HandlerAction`] that will produce a value by applying a closure to a reference to
	`432`	`+/// and entry in the lane.`
`431`	`433`	`pub struct JoinValueLaneWithEntry<C, K, V, F, B: ?Sized> {`
`432`	`434`	`projection: for<'a> fn(&'a C) -> &'a JoinValueLane<K, V>,`
`433`	`435`	`key: K,`
`@@ -436,6 +438,10 @@ pub struct JoinValueLaneWithEntry<C, K, V, F, B: ?Sized> {`
`436`	`438`	`}`
`437`	`439`
`438`	`440`	`impl<C, K, V, F, B: ?Sized> JoinValueLaneWithEntry<C, K, V, F, B> {`
	`441`	`+ /// #Arguments`
	`442`	+ /// * `projection` - Projection from the agent context to the lane.
	`443`	+ /// * `key` - Key of the entry.
	`444`	+ /// * `f` - The closure to apply to the entry.
`439`	`445`	`pub fn new(projection: for<'a> fn(&'a C) -> &'a JoinValueLane<K, V>, key: K, f: F) -> Self {`
`440`	`446`	`JoinValueLaneWithEntry {`
`441`	`447`	`projection,`
Original file line number	Diff line number	Diff line change
`@@ -274,13 +274,17 @@ impl<C, T> HandlerAction<C> for ValueLaneSync<C, T> {`
`274`	`274`	`}`
`275`	`275`	`}`
`276`	`276`
	`277`	+/// An [`HandlerAction`] that will produce a value from a reference to the contents of the lane.
`277`	`278`	`pub struct ValueLaneWithValue<C, T, F, B: ?Sized> {`
`278`	`279`	`projection: for<'a> fn(&'a C) -> &'a ValueLane<T>,`
`279`	`280`	`f: Option<F>,`
`280`	`281`	`_type: PhantomData<fn(&B)>,`
`281`	`282`	`}`
`282`	`283`
`283`	`284`	`impl<C, T, F, B: ?Sized> ValueLaneWithValue<C, T, F, B> {`
	`285`	`+ /// #Arguments`
	`286`	+ /// * `projection` - Projection from the agent context to the lane.
	`287`	+ /// * `f` - Closure to apply to the value of the lane.
`284`	`288`	`pub fn new(projection: for<'a> fn(&'a C) -> &'a ValueLane<T>, f: F) -> Self {`
`285`	`289`	`ValueLaneWithValue {`
`286`	`290`	`projection,`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ impl<K, V, Q: Default> MapStoreInner<K, V, Q> {`
`52`	`52`	`}`
`53`	`53`	`}`
`54`	`54`
`55`		`-pub enum WithEntryResult {`
	`55`	`+pub enum TransformEntryResult {`
`56`	`56`	`NoChange,`
`57`	`57`	`Update,`
`58`	`58`	`Remove,`
`@@ -78,7 +78,7 @@ where`
`78`	`78`	`queue.push(MapOperation::Update { key, value: () });`
`79`	`79`	`}`
`80`	`80`
`81`		`- pub fn transform_entry<F>(&mut self, key: K, f: F) -> WithEntryResult`
	`81`	`+ pub fn transform_entry<F>(&mut self, key: K, f: F) -> TransformEntryResult`
`82`	`82`	`where`
`83`	`83`	`F: FnOnce(Option<&V>) -> Option<V>,`
`84`	`84`	`{`
`@@ -93,22 +93,22 @@ where`
`93`	`93`	`content.insert(key.clone(), v2);`
`94`	`94`	`*previous = Some(MapLaneEvent::Update(key.clone(), Some(v)));`
`95`	`95`	`queue.push(MapOperation::Update { key, value: () });`
`96`		`- WithEntryResult::Update`
	`96`	`+ TransformEntryResult::Update`
`97`	`97`	`}`
`98`	`98`	`_ => {`
`99`	`99`	`*previous = Some(MapLaneEvent::Remove(key.clone(), v));`
`100`	`100`	`queue.push(MapOperation::Remove { key: key.clone() });`
`101`		`- WithEntryResult::Remove`
	`101`	`+ TransformEntryResult::Remove`
`102`	`102`	`}`
`103`	`103`	`},`
`104`	`104`	`_ => match f(None) {`
`105`	`105`	`Some(v2) => {`
`106`	`106`	`content.insert(key.clone(), v2);`
`107`	`107`	`*previous = Some(MapLaneEvent::Update(key.clone(), None));`
`108`	`108`	`queue.push(MapOperation::Update { key, value: () });`
`109`		`- WithEntryResult::Update`
	`109`	`+ TransformEntryResult::Update`
`110`	`110`	`}`
`111`		`- _ => WithEntryResult::NoChange,`
	`111`	`+ _ => TransformEntryResult::NoChange,`
`112`	`112`	`},`
`113`	`113`	`}`
`114`	`114`	`}`
Original file line number	Diff line number	Diff line change
`@@ -276,13 +276,17 @@ impl<C, T> HandlerAction<C> for ValueStoreSet<C, T> {`
`276`	`276`	`}`
`277`	`277`	`}`
`278`	`278`
	`279`	+/// An [`HandlerAction`] that will produce a value from a reference to the contents of the store.
`279`	`280`	`pub struct ValueStoreWithValue<C, T, F, B: ?Sized> {`
`280`	`281`	`projection: for<'a> fn(&'a C) -> &'a ValueStore<T>,`
`281`	`282`	`f: Option<F>,`
`282`	`283`	`_type: PhantomData<fn(&B)>,`
`283`	`284`	`}`
`284`	`285`
`285`	`286`	`impl<C, T, F, B: ?Sized> ValueStoreWithValue<C, T, F, B> {`
	`287`	`+ /// #Arguments`
	`288`	+ /// * `projection` - Projection from the agent context to the store.
	`289`	+ /// * `f` - Closure to apply to the value of the store.
`286`	`290`	`pub fn new(projection: for<'a> fn(&'a C) -> &'a ValueStore<T>, f: F) -> Self {`
`287`	`291`	`ValueStoreWithValue {`
`288`	`292`	`projection,`