Update docs

Signed-off-by: Michael X. Grey <[email protected]>

Author: mxgrey

src/buffer.rs

@@ -233,7 +233,7 @@ impl Default for RetentionPolicy {
 /// To obtain a `BufferKey`, use [`Chain::with_access`][1], or [`listen`][2].
 ///
 /// [1]: crate::Chain::with_access
-/// [2]: crate::Bufferable::listen
+/// [2]: crate::Accessible::listen
 pub struct BufferKey<T> {
     tag: BufferKeyTag,
     _ignore: std::marker::PhantomData<fn(T)>,

src/buffer/any_buffer.rs

@@ -41,7 +41,7 @@ use crate::{
 };
 
 /// A [`Buffer`] whose message type has been anonymized. Joining with this buffer
-/// type will yield an [`AnyMessage`].
+/// type will yield an [`AnyMessageBox`].
 #[derive(Clone, Copy)]
 pub struct AnyBuffer {
     pub(crate) location: BufferLocation,

src/buffer/buffer_map.rs

@@ -199,16 +199,17 @@ impl<T: BufferMapLayout> Buffered for T {
     }
 }
 
-/// This trait can be implemented for structs that are created by joining a
-/// collection of buffers. Usually this
+/// This trait can be implemented for structs that are created by joining together
+/// values from a collection of buffers. Usually you do not need to implement this
+/// yourself. Instead you can use `#[derive(JoinedValue)]`.
 pub trait JoinedValue: 'static + Send + Sync + Sized {
     /// This associated type must represent a buffer map layout that implements
     /// the [`Joined`] trait. The message type yielded by [`Joined`] for this
     /// associated type must match the [`JoinedValue`] type.
     type Buffers: 'static + BufferMapLayout + Joined<Item = Self> + Send + Sync;
 
-    /// Used by [`Builder::join_into`]
-    fn join_into<'w, 's, 'a, 'b>(
+    /// Used by [`Self::try_join_from`]
+    fn join_from<'w, 's, 'a, 'b>(
         buffers: Self::Buffers,
         builder: &'b mut Builder<'w, 's, 'a>,
     ) -> Chain<'w, 's, 'a, 'b, Self> {
@@ -226,17 +227,17 @@ pub trait JoinedValue: 'static + Send + Sync + Sized {
         Output::new(scope, target).chain(builder)
     }
 
-    /// Used by [`Builder::try_join_into`]
-    fn try_join_into<'w, 's, 'a, 'b>(
+    /// Used by [`Builder::try_join`]
+    fn try_join_from<'w, 's, 'a, 'b>(
         buffers: &BufferMap,
         builder: &'b mut Builder<'w, 's, 'a>,
     ) -> Result<Chain<'w, 's, 'a, 'b, Self>, IncompatibleLayout> {
         let buffers: Self::Buffers = Self::Buffers::try_from_buffer_map(buffers)?;
-        Ok(Self::join_into(buffers, builder))
+        Ok(Self::join_from(buffers, builder))
     }
 }
 
-/// Trait to describe a layout of buffer keys
+/// Trait to describe a set of buffer keys.
 pub trait BufferKeyMap: 'static + Send + Sync + Sized + Clone {
     type Buffers: 'static + BufferMapLayout + Accessed<Key = Self> + Send + Sync;
 }
@@ -321,6 +322,10 @@ mod tests {
         string: String,
     }
 
+    impl JoinedValue for TestJoinedValue {
+        type Buffers = TestJoinedValueBuffers;
+    }
+
     #[derive(Clone)]
     struct TestJoinedValueBuffers {
         integer: Buffer<i64>,
@@ -378,10 +383,6 @@ mod tests {
         }
     }
 
-    impl JoinedValue for TestJoinedValue {
-        type Buffers = TestJoinedValueBuffers;
-    }
-
     #[test]
     fn test_try_join() {
         let mut context = TestingContext::minimal_plugins();

src/buffer/bufferable.rs

@@ -61,21 +61,29 @@ impl<T: 'static + Send + Sync> Bufferable for Output<T> {
 }
 
 pub trait Joinable: Bufferable {
-    type Item;
+    type Item: 'static + Send + Sync;
 
     fn join<'w, 's, 'a, 'b>(
         self,
         builder: &'b mut Builder<'w, 's, 'a>,
     ) -> Chain<'w, 's, 'a, 'b, Self::Item>;
 }
 
+/// This trait is used to create join operations that pull exactly one value
+/// from multiple buffers or outputs simultaneously.
 impl<B> Joinable for B
 where
     B: Bufferable,
     B::BufferType: Joined,
 {
     type Item = JoinedItem<B>;
 
+    /// Join these bufferable workflow elements. Each time every buffer contains
+    /// at least one element, this will pull the oldest element from each buffer
+    /// and join them into a tuple that gets sent to the target.
+    ///
+    /// If you need a more general way to get access to one or more buffers,
+    /// use [`listen`](Accessible::listen) instead.
     fn join<'w, 's, 'a, 'b>(
         self,
         builder: &'b mut Builder<'w, 's, 'a>,
@@ -84,9 +92,17 @@ where
     }
 }
 
+/// This trait is used to create operations that access buffers or outputs.
 pub trait Accessible: Bufferable {
-    type Keys;
+    type Keys: 'static + Send + Sync;
 
+    /// Create an operation that will output buffer access keys each time any
+    /// one of the buffers is modified. This can be used to create a node in a
+    /// workflow that wakes up every time one or more buffers change, and then
+    /// operates on those buffers.
+    ///
+    /// For an operation that simply joins the contents of two or more outputs
+    /// or buffers, use [`join`](Joinable::join) instead.
     fn listen<'w, 's, 'a, 'b>(
         self,
         builder: &'b mut Builder<'w, 's, 'a>,

src/buffer/buffered.rs

@@ -57,7 +57,7 @@ pub trait Joined: Buffered {
     /// and join them into a tuple that gets sent to the target.
     ///
     /// If you need a more general way to get access to one or more buffers,
-    /// use [`listen`](Self::listen) instead.
+    /// use [`listen`](Accessed::listen) instead.
     fn join<'w, 's, 'a, 'b>(
         self,
         builder: &'b mut Builder<'w, 's, 'a>,
@@ -90,7 +90,7 @@ pub trait Accessed: Buffered {
     /// operates on those buffers.
     ///
     /// For an operation that simply joins the contents of two or more outputs
-    /// or buffers, use [`join`](Self::join) instead.
+    /// or buffers, use [`join`](Joined::join) instead.
     fn listen<'w, 's, 'a, 'b>(
         self,
         builder: &'b mut Builder<'w, 's, 'a>,

src/buffer/json_buffer.rs

@@ -1367,6 +1367,10 @@ mod tests {
         json: JsonBuffer,
     }
 
+    impl JoinedValue for TestJoinedValueJson {
+        type Buffers = TestJoinedValueJsonBuffers;
+    }
+
     impl BufferMapLayout for TestJoinedValueJsonBuffers {
         fn buffer_list(&self) -> smallvec::SmallVec<[AnyBuffer; 8]> {
             use smallvec::smallvec;
@@ -1421,10 +1425,6 @@ mod tests {
         }
     }
 
-    impl JoinedValue for TestJoinedValueJson {
-        type Buffers = TestJoinedValueJsonBuffers;
-    }
-
     #[test]
     fn test_try_join_json() {
         let mut context = TestingContext::minimal_plugins();

src/builder.rs

@@ -22,10 +22,10 @@ use std::future::Future;
 use smallvec::SmallVec;
 
 use crate::{
-    Accessed, AddOperation, AsMap, Buffer, BufferKeys, BufferLocation, BufferMap, BufferSettings,
+    Accessed, Accessible, AddOperation, AsMap, Buffer, BufferKeys, BufferLocation, BufferMap, BufferSettings,
     Bufferable, Buffered, Chain, Collect, ForkClone, ForkCloneOutput, ForkTargetStorage, Gate,
-    GateRequest, IncompatibleLayout, Injection, InputSlot, IntoAsyncMap, IntoBlockingMap, Joined,
-    JoinedItem, JoinedValue, Node, OperateBuffer, OperateBufferAccess, OperateDynamicGate,
+    GateRequest, IncompatibleLayout, Injection, InputSlot, IntoAsyncMap, IntoBlockingMap, Joinable,
+    JoinedValue, Node, OperateBuffer, OperateBufferAccess, OperateDynamicGate,
     OperateScope, OperateSplit, OperateStaticGate, Output, Provider, RequestOfMap, ResponseOfMap,
     Scope, ScopeEndpoints, ScopeSettings, ScopeSettingsStorage, Sendish, Service, SplitOutputs,
     Splittable, StreamPack, StreamTargetMap, StreamsOfMap, Trim, TrimBranch, UnusedTarget,
@@ -231,32 +231,28 @@ impl<'w, 's, 'a> Builder<'w, 's, 'a> {
         )
     }
 
-    /// Alternative way of calling [`Bufferable::join`]
-    pub fn join<'b, B: Bufferable>(&'b mut self, buffers: B) -> Chain<'w, 's, 'a, 'b, JoinedItem<B>>
-    where
-        B::BufferType: Joined,
-        JoinedItem<B>: 'static + Send + Sync,
-    {
-        buffers.into_buffer(self).join(self)
+    /// Alternative way of calling [`Joinable::join`]
+    pub fn join<'b, B: Joinable>(
+        &'b mut self,
+        buffers: B,
+    ) -> Chain<'w, 's, 'a, 'b, B::Item> {
+        buffers.join(self)
     }
 
     /// Try joining a map of buffers into a single value.
     pub fn try_join<'b, Joined: JoinedValue>(
         &'b mut self,
         buffers: &BufferMap,
     ) -> Result<Chain<'w, 's, 'a, 'b, Joined>, IncompatibleLayout> {
-        Joined::try_join_into(buffers, self)
+        Joined::try_join_from(buffers, self)
     }
 
-    /// Alternative way of calling [`Bufferable::listen`].
-    pub fn listen<'b, B: Bufferable>(
+    /// Alternative way of calling [`Accessible::listen`].
+    pub fn listen<'b, B: Accessible>(
         &'b mut self,
         buffers: B,
-    ) -> Chain<'w, 's, 'a, 'b, BufferKeys<B>>
-    where
-        B::BufferType: Accessed,
-    {
-        buffers.into_buffer(self).listen(self)
+    ) -> Chain<'w, 's, 'a, 'b, B::Keys> {
+        buffers.listen(self)
     }
 
     /// Create a node that combines its inputs with access to some buffers. You
@@ -266,11 +262,13 @@ impl<'w, 's, 'a> Builder<'w, 's, 'a> {
     ///
     /// Other [outputs](Output) can also be passed in as buffers. These outputs
     /// will be transformed into a buffer with default buffer settings.
-    pub fn create_buffer_access<T, B>(&mut self, buffers: B) -> Node<T, (T, BufferKeys<B>)>
+    pub fn create_buffer_access<T, B: Bufferable>(
+        &mut self,
+        buffers: B,
+    ) -> Node<T, (T, BufferKeys<B>)>
     where
-        T: 'static + Send + Sync,
-        B: Bufferable,
         B::BufferType: Accessed,
+        T: 'static + Send + Sync,
     {
         let buffers = buffers.into_buffer(self);
         let source = self.commands.spawn(()).id();

src/chain.rs

@@ -298,7 +298,7 @@ impl<'w, 's, 'a, 'b, T: 'static + Send + Sync> Chain<'w, 's, 'a, 'b, T> {
     /// will be transformed into a buffer with default buffer settings.
     ///
     /// To obtain a set of buffer keys each time a buffer is modified, use
-    /// [`listen`](crate::Bufferable::listen).
+    /// [`listen`](crate::Accessible::listen).
     pub fn with_access<B>(self, buffers: B) -> Chain<'w, 's, 'a, 'b, (T, BufferKeys<B>)>
     where
         B: Bufferable,
@@ -391,7 +391,7 @@ impl<'w, 's, 'a, 'b, T: 'static + Send + Sync> Chain<'w, 's, 'a, 'b, T> {
     /// The return values of the individual chain builders will be zipped into
     /// one tuple return value by this function. If all of the builders return
     /// [`Output`] then you can easily continue chaining more operations using
-    /// [`join`](crate::Bufferable::join), or destructure them into individual
+    /// [`join`](crate::Joinable::join), or destructure them into individual
     /// outputs that you can continue to build with.
     pub fn fork_clone<Build: ForkCloneBuilder<T>>(self, build: Build) -> Build::Outputs
     where

src/gate.rs

@@ -23,14 +23,14 @@ pub enum Gate {
     /// receive a wakeup immediately when a gate switches from closed to open,
     /// even if none of the data inside the buffer has changed.
     ///
-    /// [1]: crate::Bufferable::join
+    /// [1]: crate::Joinable::join
     Open,
     /// Close the buffer gate so that listeners (including [join][1] operations)
     /// will not be woken up when the data in the buffer gets modified. This
     /// effectively blocks the workflow nodes that are downstream of the buffer.
     /// Data will build up in the buffer according to its [`BufferSettings`][2].
     ///
-    /// [1]: crate::Bufferable::join
+    /// [1]: crate::Joinable::join
     /// [2]: crate::BufferSettings
     Closed,
 }