docs: move descr directly into traits, not module

src/api/controller.rs

@@ -1,9 +1,7 @@
 //! # Controller
 //! 
-//! this generic trait is implemented by actors managing stream procedures.
+//! an bidirectional stream handler to easily manage async operations across local buffers and the
-//! events can be enqueued for dispatching without blocking ([Controller::send]), and an async blocking 
+//! server
-//! api ([Controller::recv]) is provided to wait for server events. Additional sync blocking
-//! ([Controller::blocking_recv]) and callback-based ([Controller::callback]) are implemented.
 
 use crate::Result;
 use std::sync::Arc;
@@ -20,6 +18,15 @@ pub(crate) trait ControllerWorker<T : Sized + Send + Sync> {
 }
 
 /// async and threadsafe handle to a generic bidirectional stream
+///
+/// this generic trait is implemented by actors managing stream procedures.
+/// events can be enqueued for dispatching without blocking ([Controller::send]), and an async blocking 
+/// api ([Controller::recv]) is provided to wait for server events. Additional sync blocking
+/// ([Controller::blocking_recv]) and callback-based ([Controller::callback]) are implemented.
+///
+/// * if possible, prefer a pure [Controller::recv] consumer
+/// * a second possibility in preference is using a [Controller::callback]
+/// * if neither is feasible a [Controller::poll]/[Controller::try_recv] approach is available
 #[tonic::async_trait]
 pub trait Controller<T : Sized + Send + Sync> : Sized + Send + Sync {
 	/// type of upstream values, used in [Self::send]

src/api/factory.rs

@@ -1,72 +1,8 @@
 //! ### factory
-//! 
-//! a helper trait to produce Operation Sequences, knowing the current 
-//! state of the buffer
 //!
-//! ```rust
+//! a helper trait that any string container can implement, which generates opseqs
-//! use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
 //!
-//! let mut factory = SimpleOperationFactory::from("");
+//! an OperationFactory trait implementation is provided for String, but plugin developers 
-//! let op = factory.insert("asd", 0);
-//! factory.update(op)?;
-//! assert_eq!(factory.content(), "asd");
-//! # Ok::<(), codemp::ot::OTError>(())
-//! ```
-//!
-//! use [OperationFactory::insert] to add new characters at a specific index
-//!
-//! ```rust
-//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
-//! # let mut factory = SimpleOperationFactory::from("asd");
-//! factory.update(factory.insert(" dsa", 3))?;
-//! assert_eq!(factory.content(), "asd dsa");
-//! # Ok::<(), codemp::ot::OTError>(())
-//! ```
-//!
-//! use [OperationFactory::delta] to arbitrarily change text at any position
-//!
-//! ```rust
-//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
-//! # let mut factory = SimpleOperationFactory::from("asd dsa");
-//! let op = factory.delta(2, " xxx ", 5).expect("replaced region is equal to origin");
-//! factory.update(op)?;
-//! assert_eq!(factory.content(), "as xxx sa");
-//! # Ok::<(), codemp::ot::OTError>(())
-//! ```
-//!
-//! use [OperationFactory::delete] to remove characters from given index
-//!
-//! ```rust
-//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
-//! # let mut factory = SimpleOperationFactory::from("as xxx sa");
-//! factory.update(factory.delete(2, 5))?;
-//! assert_eq!(factory.content(), "assa");
-//! # Ok::<(), codemp::ot::OTError>(())
-//! ```
-//!
-//! use [OperationFactory::replace] to completely replace buffer content
-//!
-//! ```rust
-//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
-//! # let mut factory = SimpleOperationFactory::from("assa");
-//! let op = factory.replace("from scratch").expect("replace is equal to origin");
-//! factory.update(op)?;
-//! assert_eq!(factory.content(), "from scratch");
-//! # Ok::<(), codemp::ot::OTError>(())
-//! ```
-//!
-//! use [OperationFactory::cancel] to remove characters at index, but backwards
-//!
-//! ```rust
-//! # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
-//! # let mut factory = SimpleOperationFactory::from("from scratch");
-//! factory.update(factory.cancel(12, 8))?;
-//! assert_eq!(factory.content(), "from");
-//! # Ok::<(), codemp::ot::OTError>(())
-//! ```
-//! 
-//!
-//! This trait provides an implementation for String, but plugin developers 
 //! should implement their own operation factory interfacing directly with the editor 
 //! buffer when possible.
 
@@ -97,6 +33,73 @@ pub fn op_effective_range(op: &OperationSeq) -> Range<u64> {
 }
 
 /// a helper trait that any string container can implement, which generates opseqs
+///
+/// all operations are to be considered mutating current state, obtainable with
+/// [OperationFactory::content]. generating an operation has no effect on internal state
+///
+/// ### examples
+///
+/// ```rust
+/// use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
+///
+/// let mut factory = SimpleOperationFactory::from("");
+/// let op = factory.insert("asd", 0);
+/// factory.update(op)?;
+/// assert_eq!(factory.content(), "asd");
+/// # Ok::<(), codemp::ot::OTError>(())
+/// ```
+///
+/// use [OperationFactory::insert] to add new characters at a specific index
+///
+/// ```rust
+/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
+/// # let mut factory = SimpleOperationFactory::from("asd");
+/// factory.update(factory.insert(" dsa", 3))?;
+/// assert_eq!(factory.content(), "asd dsa");
+/// # Ok::<(), codemp::ot::OTError>(())
+/// ```
+///
+/// use [OperationFactory::delta] to arbitrarily change text at any position
+///
+/// ```rust
+/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
+/// # let mut factory = SimpleOperationFactory::from("asd dsa");
+/// let op = factory.delta(2, " xxx ", 5).expect("replaced region is equal to origin");
+/// factory.update(op)?;
+/// assert_eq!(factory.content(), "as xxx sa");
+/// # Ok::<(), codemp::ot::OTError>(())
+/// ```
+///
+/// use [OperationFactory::delete] to remove characters from given index
+///
+/// ```rust
+/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
+/// # let mut factory = SimpleOperationFactory::from("as xxx sa");
+/// factory.update(factory.delete(2, 5))?;
+/// assert_eq!(factory.content(), "assa");
+/// # Ok::<(), codemp::ot::OTError>(())
+/// ```
+///
+/// use [OperationFactory::replace] to completely replace buffer content
+///
+/// ```rust
+/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
+/// # let mut factory = SimpleOperationFactory::from("assa");
+/// let op = factory.replace("from scratch").expect("replace is equal to origin");
+/// factory.update(op)?;
+/// assert_eq!(factory.content(), "from scratch");
+/// # Ok::<(), codemp::ot::OTError>(())
+/// ```
+///
+/// use [OperationFactory::cancel] to remove characters at index, but backwards
+///
+/// ```rust
+/// # use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory};
+/// # let mut factory = SimpleOperationFactory::from("from scratch");
+/// factory.update(factory.cancel(12, 8))?;
+/// assert_eq!(factory.content(), "from");
+/// # Ok::<(), codemp::ot::OTError>(())
+/// ```
 pub trait OperationFactory {
 	/// the current content of the buffer
 	fn content(&self) -> String;