Merge pull request #15 from hexedtech/docs/tests

This commit is contained in:
cschen 2024-09-22 16:16:40 +02:00 committed by GitHub
commit 221a46dc16
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 39 additions and 21 deletions

View file

@ -4,6 +4,8 @@ on:
push: push:
branches: branches:
- dev - dev
pull_request_review:
types: [edited, dismissed]
env: env:
CARGO_TERM_COLOR: always CARGO_TERM_COLOR: always

View file

@ -16,7 +16,7 @@ exclude = ["dist/*"]
[lib] [lib]
name = "codemp" name = "codemp"
crate-type = ["cdylib"] crate-type = ["cdylib", "rlib"]
[dependencies] [dependencies]
# core # core

View file

@ -20,6 +20,15 @@
/// To delete a the fourth character we should send a. /// To delete a the fourth character we should send a.
/// `TextChange { start: 3, end: 4, content: "".into(), hash: None }` /// `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)] #[derive(Clone, Debug, Default)]
#[cfg_attr(feature = "js", napi_derive::napi(object))] #[cfg_attr(feature = "js", napi_derive::napi(object))]
#[cfg_attr(any(feature = "py", feature = "py-noabi"), pyo3::pyclass(get_all))] #[cfg_attr(any(feature = "py", feature = "py-noabi"), pyo3::pyclass(get_all))]

View file

@ -19,11 +19,12 @@
//! a supported remote server and returns a [`Client`] handle to interact with it. //! a supported remote server and returns a [`Client`] handle to interact with it.
//! //!
//! ```rust //! ```rust
//! # async fn main() { //! # async fn main_fn() {
//! let client = codemp::Client::connect( //! let client = codemp::Client::connect(
//! "https://api.code.mp", // default server, by hexed.technology //! codemp::api::Config::new(
//! "mail@example.net", // your username, on hexed.technology it's the email //! "mail@example.net",
//! "dont-use-this-password" // your password //! "dont-use-this-password"
//! )
//! ) //! )
//! .await //! .await
//! .expect("failed to connect!"); //! .expect("failed to connect!");
@ -33,26 +34,26 @@
//! A [`Client`] can acquire a [`Workspace`] handle by joining an existing one it can access with //! 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`]. //! [`Client::join_workspace`] or create a new one with [`Client::create_workspace`].
//! //!
//! ```rust,no_run //! ```rust, run
//! # async fn main() { //! # async fn main_fn() {
//! # let client = codemp::Client::connect("", "", "").await.unwrap(); //! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap();
//! client.create_workspace("my-workspace").await.expect("failed to create workspace!"); //! 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 //! 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. //! and one or more [`buffer::Controller`] to send and receive [`api::TextChange`]s.
//! //!
//! ```rust,no_run //! ```rust
//! # async fn main() { //! # async fn main_fn() {
//! # let client = codemp::Client::connect("", "", "").await.unwrap(); //! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap();
//! # client.create_workspace("").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 //! use codemp::api::Controller; // needed to access trait methods
//! let cursor = workspace.cursor(); //! let cursor = workspace.cursor();
//! let event = cursor.recv().await.expect("disconnected while waiting for event!"); //! 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 //! eventual consistency. Each [`api::TextChange`] is translated in a network counterpart that is
//! guaranteed to converge. //! guaranteed to converge.
//! //!
//! ```rust,no_run //! ```rust
//! # async fn main() { //! # async fn main_fn() {
//! # let client = codemp::Client::connect("", "", "").await.unwrap(); //! # let client = codemp::Client::connect(codemp::api::Config::new("", "")).await.unwrap();
//! # client.create_workspace("").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; //! # 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 //! buffer.content(); // force-sync
//! if let Some(change) = buffer.try_recv().await.unwrap() { //! 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 //! } // if None, no changes are currently available
//! # } //! # }
//! ``` //! ```

View file

@ -32,6 +32,12 @@ use uuid::Uuid;
#[cfg(feature = "js")] #[cfg(feature = "js")]
use napi_derive::napi; 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)] #[derive(Debug, Clone)]
#[cfg_attr(any(feature = "py", feature = "py-noabi"), pyo3::pyclass)] #[cfg_attr(any(feature = "py", feature = "py-noabi"), pyo3::pyclass)]
#[cfg_attr(feature = "js", napi)] #[cfg_attr(feature = "js", napi)]
@ -150,7 +156,7 @@ impl Workspace {
/// Detach from an active buffer. /// 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 /// There may still be some events enqueued in buffers to poll, but the [buffer::Controller] itself won't be
/// accessible anymore from [`Workspace`]. /// accessible anymore from [`Workspace`].
pub fn detach(&self, path: &str) -> DetachResult { pub fn detach(&self, path: &str) -> DetachResult {