From c0892b36cd9d70c9224145fcf9f4cdde3a70d084 Mon Sep 17 00:00:00 2001 From: alemi Date: Sun, 10 Sep 2023 03:39:44 +0200 Subject: [PATCH] docs: move descr directly into traits, not module --- src/api/controller.rs | 15 +++-- src/api/factory.rs | 135 +++++++++++++++++++++--------------------- 2 files changed, 80 insertions(+), 70 deletions(-) diff --git a/src/api/controller.rs b/src/api/controller.rs index 368be32..216407a 100644 --- a/src/api/controller.rs +++ b/src/api/controller.rs @@ -1,9 +1,7 @@ //! # Controller //! -//! 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. +//! an bidirectional stream handler to easily manage async operations across local buffers and the +//! server use crate::Result; use std::sync::Arc; @@ -20,6 +18,15 @@ pub(crate) trait ControllerWorker { } /// 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 : Sized + Send + Sync { /// type of upstream values, used in [Self::send] diff --git a/src/api/factory.rs b/src/api/factory.rs index 51950e8..a41b383 100644 --- a/src/api/factory.rs +++ b/src/api/factory.rs @@ -1,72 +1,8 @@ //! ### factory -//! -//! a helper trait to produce Operation Sequences, knowing the current -//! state of the buffer //! -//! ```rust -//! use codemp::buffer::factory::{OperationFactory, SimpleOperationFactory}; +//! a helper trait that any string container can implement, which generates opseqs //! -//! 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>(()) -//! ``` -//! -//! -//! This trait provides an implementation for String, but plugin developers +//! an OperationFactory trait implementation is provided 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 { } /// 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;