docs: Improve docs for Flow

src/lib.rs

@@ -12,15 +12,23 @@ pub mod stream;
 mod tests;
 pub mod types;
 
-/// Simple abstraction of IMAP flows that can be used for implementing IO utilities.
+/// Common sans I/O interface used to implement I/O drivers for types that implement our protocol flows.
 ///
-/// The utility [`Stream`](stream::Stream) is using this for implementing the IO bits when
-/// dealing with TCP or TLS.
+/// Most notably, [`ClientFlow`](client::ClientFlow) and [`ServerFlow`](server::ServerFlow) both implement
+/// this trait whereas [`Stream`](stream::Stream) implements the I/O drivers.
 pub trait Flow {
+    /// Event emitted while progressing the protocol flow.
     type Event;
+
+    /// Error emitted while progressing the protocol flow.
     type Error;
 
+    /// Enqueue input bytes.
+    ///
+    /// These bytes may be used during the next [`Self::progress`] call.
     fn enqueue_input(&mut self, bytes: &[u8]);
+
+    /// Progress the protocol flow until the next event (or interrupt).
     fn progress(&mut self) -> Result<Self::Event, FlowInterrupt<Self::Error>>;
 }
 
@@ -37,8 +45,8 @@ impl<F: Flow> Flow for &mut F {
     }
 }
 
-/// The IMAP flow was interrupted by an event that needs to be handled externally.
-#[must_use = "If the IMAP flow is interrupted the interrupt must be handled. Ignoring this might result in a deadlock on IMAP level"]
+/// The protocol flow was interrupted by an event that needs to be handled externally.
+#[must_use = "If the protocol flow is interrupted the interrupt must be handled. Ignoring this might result in a deadlock on IMAP level"]
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum FlowInterrupt<E> {
     /// An IO operation is necessary. Ignoring this might result in a deadlock on IMAP level.
@@ -47,7 +55,7 @@ pub enum FlowInterrupt<E> {
     Error(E),
 }
 
-/// The user of `imap-flow` must perform an IO operation in order to progress the IMAP flow.
+/// The user of `imap-flow` must perform an IO operation in order to progress the protocol flow.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub enum FlowIo {
     /// More bytes must be read and passed to [`Flow::enqueue_input`].