From 69171e73b308e88434e739cd4ff4481dcdd0aede Mon Sep 17 00:00:00 2001 From: alemi Date: Sat, 21 Sep 2024 11:52:46 +0200 Subject: [PATCH] docs: re-enable and fix doc tests --- Cargo.toml | 2 +- src/api/change.rs | 9 +++++++++ src/lib.rs | 39 ++++++++++++++++++++------------------- src/workspace.rs | 8 +++++++- 4 files changed, 37 insertions(+), 21 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 2698072..fbc42de 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,7 +16,7 @@ exclude = ["dist/*"] [lib] name = "codemp" -crate-type = ["cdylib"] +crate-type = ["cdylib", "rlib"] [dependencies] # core diff --git a/src/api/change.rs b/src/api/change.rs index 9c04aad..1dde0a9 100644 --- a/src/api/change.rs +++ b/src/api/change.rs @@ -20,6 +20,15 @@ /// To delete a the fourth character we should send a. /// `TextChange { start: 3, end: 4, content: "".into(), hash: None }` /// +/// ```rust +/// let change = codemp::api::TextChange { +/// start: 6, end: 11, +/// content: "mom".to_string(), hash: None +/// }; +/// let before = "hello world!"; +/// let after = change.apply(before); +/// assert_eq!(after, "hello mom!"); +/// ``` #[derive(Clone, Debug, Default)] #[cfg_attr(feature = "js", napi_derive::napi(object))] #[cfg_attr(feature = "py", pyo3::pyclass(get_all))] diff --git a/src/lib.rs b/src/lib.rs index bbad891..e84eb6d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,11 +19,12 @@ //! a supported remote server and returns a [`Client`] handle to interact with it. //! //! ```rust -//! # async fn main() { +//! # async fn main_fn() { //! let client = codemp::Client::connect( -//! "https://api.code.mp", // default server, by hexed.technology -//! "mail@example.net", // your username, on hexed.technology it's the email -//! "dont-use-this-password" // your password +//! codemp::api::Config::new( +//! "mail@example.net", +//! "dont-use-this-password" +//! ) //! ) //! .await //! .expect("failed to connect!"); @@ -33,26 +34,26 @@ //! A [`Client`] can acquire a [`Workspace`] handle by joining an existing one it can access with //! [`Client::join_workspace`] or create a new one with [`Client::create_workspace`]. //! -//! ```rust,no_run -//! # async fn main() { -//! # let client = codemp::Client::connect("", "", "").await.unwrap(); +//! ```rust, run +//! # async fn main_fn() { +//! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap(); //! client.create_workspace("my-workspace").await.expect("failed to create workspace!"); -//! let workspace = client.attach_workspace("my-workspace").await.expect("failed to attach!"); +//! let workspace = client.join_workspace("my-workspace").await.expect("failed to attach!"); //! # } //! ``` //! //! A [`Workspace`] handle can be used to acquire a [`cursor::Controller`] to track remote [`api::Cursor`]s //! and one or more [`buffer::Controller`] to send and receive [`api::TextChange`]s. //! -//! ```rust,no_run -//! # async fn main() { -//! # let client = codemp::Client::connect("", "", "").await.unwrap(); +//! ```rust +//! # async fn main_fn() { +//! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap(); //! # client.create_workspace("").await.unwrap(); -//! # let workspace = client.attach_workspace("").await.unwrap(); +//! # let workspace = client.join_workspace("").await.unwrap(); //! use codemp::api::Controller; // needed to access trait methods //! let cursor = workspace.cursor(); //! let event = cursor.recv().await.expect("disconnected while waiting for event!"); -//! println!("user {event.user} moved on buffer {event.buffer}"); +//! println!("user {} moved on buffer {}", event.user.unwrap_or_default(), event.buffer); //! # } //! ``` //! @@ -60,16 +61,16 @@ //! eventual consistency. Each [`api::TextChange`] is translated in a network counterpart that is //! guaranteed to converge. //! -//! ```rust,no_run -//! # async fn main() { -//! # let client = codemp::Client::connect("", "", "").await.unwrap(); +//! ```rust +//! # async fn main_fn() { +//! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap(); //! # client.create_workspace("").await.unwrap(); -//! # let workspace = client.attach_workspace("").await.unwrap(); +//! # let workspace = client.join_workspace("").await.unwrap(); //! # use codemp::api::Controller; -//! let buffer = workspace.attach_buffer("/some/file.txt").await.expect("failed to attach"); +//! let buffer = workspace.attach("/some/file.txt").await.expect("failed to attach"); //! buffer.content(); // force-sync //! if let Some(change) = buffer.try_recv().await.unwrap() { -//! println!("content: {change.content}, span: {change.span.start}-{change.span.end}"); +//! println!("content: {}, span: {}-{}", change.content, change.start, change.end); //! } // if None, no changes are currently available //! # } //! ``` diff --git a/src/workspace.rs b/src/workspace.rs index b474121..7a2e475 100644 --- a/src/workspace.rs +++ b/src/workspace.rs @@ -32,6 +32,12 @@ use uuid::Uuid; #[cfg(feature = "js")] use napi_derive::napi; +/// A currently active shared development environment +/// +/// Workspaces encapsulate a working environment: cursor positions, filetree, user list +/// and more. Each holds a [cursor::Controller] and a map of [buffer::Controller]s. +/// Using a workspace handle, it's possible to receive events (user join/leave, filetree updates) +/// and create/delete/attach to new buffers. #[derive(Debug, Clone)] #[cfg_attr(feature = "py", pyo3::pyclass)] #[cfg_attr(feature = "js", napi)] @@ -149,7 +155,7 @@ impl Workspace { /// Detach from an active buffer. /// - /// This option will be carried in background. `BufferWorker` will be stopped and dropped. + /// This option will be carried in background. BufferWorker will be stopped and dropped. /// There may still be some events enqueued in buffers to poll, but the [buffer::Controller] itself won't be /// accessible anymore from [`Workspace`]. pub fn detach(&self, path: &str) -> DetachResult {