Merge pull request #15 from hexedtech/docs/tests

.github/workflows/test.yml

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

Cargo.toml

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

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(any(feature = "py", feature = "py-noabi"), pyo3::pyclass(get_all))]

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
+//!   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
 //!   .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
+//! ```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!");
-//! 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
+//! ```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();
-//! # 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
+//! ```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();
-//! # 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
 //! # }
 //! ```

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(any(feature = "py", feature = "py-noabi"), pyo3::pyclass)]
 #[cfg_attr(feature = "js", napi)]
@@ -150,7 +156,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 {