docs: updated docs

This commit is contained in:
əlemi 2024-02-09 01:16:16 +01:00
parent a622ac773c
commit 9422f9a216
3 changed files with 18 additions and 14 deletions

View file

@ -62,6 +62,7 @@ impl TextChange {
}
#[cfg(feature = "woot")]
/// consume the [TextChange], transforming it into a Vec of [woot::crdt::Op]
pub fn transform(self, woot: &Woot) -> WootResult<Vec<Op>> {
let mut out = Vec::new();
if self.is_empty() { return Ok(out); } // no-op

View file

@ -19,8 +19,7 @@ pub(crate) trait ControllerWorker<T : Sized + Send + Sync> {
///
/// 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]) is implemented if feature `sync` is enabled.
/// api ([Controller::recv]) is provided to wait for server events.
///
/// * if possible, prefer a pure [Controller::recv] consumer, awaiting for events
/// * if async is not feasible a [Controller::poll]/[Controller::try_recv] approach is possible

View file

@ -5,8 +5,8 @@
//! > the core library of the codemp project, driving all editor plugins
//!
//! ## structure
//! The main entrypoint is the [Instance] object, that maintains a connection and can
//! be used to join workspaces or attach to buffers. It contains the underlying [client::Client] and
//! The main entrypoint is the [Client] object, that maintains a connection and can
//! be used to join workspaces or attach to buffers. It contains the underlying [Workspace] and
//! stores active controllers.
//!
//! Some actions will return structs implementing the [api::Controller] trait. These can be polled
@ -21,26 +21,21 @@
//! immediately but instead deferred until compatible.
//!
//! ## features
//! * `woot` : include the underlying CRDT library and re-exports it (default enabled)
//! * `api` : include traits for core interfaces under [api] (default enabled)
//! * `woot` : include the underlying CRDT library and re-exports it (default enabled)
//! * `proto` : include GRCP protocol definitions under [proto] (default enabled)
//! * `client` : include the local [client] implementation (default enabled)
//!
//! ## examples
//! the [client::Client] itself is the core structure implementing all methods, plugins should
//! attempt to keep a single instance at any time
//!
//! working sessions are [workspace::Workspace] and while managing multiple ones is in theory
//! possible, it's not really working right now due to how authentication is managed
//! most methods are split between the [Client] itself and the current [Workspace]
//!
//! ### async
//! ```rust,no_run
//! use codemp::api::{Controller, TextChange};
//! # use codemp::client::Client;
//!
//! # async fn async_example() -> codemp::Result<()> {
//! // creating a client session will immediately attempt to connect
//! let mut session = Client::new("http://alemi.dev:50053").await?;
//! let mut session = codemp::Client::new("http://alemi.dev:50053").await?;
//!
//! // login first, obtaining a new token granting access to 'some_workspace'
//! session.login(
@ -73,18 +68,19 @@
//! # }
//! ```
//!
//! it's always possible to get a [Workspace] reference using [Client::get_workspace]
//!
//! ### sync
//! if async is not viable, a solution might be keeping a global tokio runtime and blocking on it:
//!
//! ```rust,no_run
//! # use codemp::client::Client;
//! # use std::sync::Arc;
//! # use codemp::api::Controller;
//! #
//! # fn sync_example() -> codemp::Result<()> {
//! let rt = tokio::runtime::Runtime::new().unwrap();
//! let mut session = rt.block_on( // using block_on allows calling async code
//! Client::new("http://alemi.dev:50051")
//! codemp::Client::new("http://alemi.dev:50051")
//! )?;
//!
//! rt.block_on(session.login(
@ -214,3 +210,11 @@ pub mod proto {
pub use errors::Error;
pub use errors::Result;
#[cfg(feature = "client")]
pub use client::Client;
#[cfg(feature = "client")]
pub use workspace::Workspace;