docs: updated main doc page examples

src/lib.rs

@@ -27,59 +27,77 @@
 //! * `client` : include the local [client] implementation (default enabled)
 //! 
 //! ## examples
-//! while the [client::Client] itself is the core structure implementing all methods, plugins will mostly
-//! interact with [Instance] managers.
+//! 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
 //!
 //! ### async
-//! this library is natively async and thus async usage should be preferred if possible with
-//! [instance::a_sync::Instance]
-//!
 //! ```rust,no_run
 //! use codemp::api::{Controller, TextChange};
-//! # use codemp::instance::a_sync::Instance;
+//! # use codemp::client::Client;
 //!
 //! # async fn async_example() -> codemp::Result<()> {
-//! let session = Instance::default();   // create global session
-//! session.connect("http://alemi.dev:50051").await?;   // connect to remote server
+//! // creating a client session will immediately attempt to connect
+//! let mut session = Client::new("http://alemi.dev:50053").await?;
+//!
+//! // login first, obtaining a new token granting access to 'some_workspace'
+//! session.login(
+//!   "username".to_string(),
+//!   "password".to_string(),
+//!   Some("some_workspace".to_string())
+//! ).await?;
 //! 
-//! // join a remote workspace, obtaining a cursor controller
-//! let cursor = session.join("some_workspace").await?;
-//! cursor.send(   // move cursor
-//!   codemp::proto::CursorPosition {
+//! // join a remote workspace, obtaining a workspace handle
+//! let workspace = session.join_workspace("some_workspace").await?;
+//!
+//! workspace.cursor().send(   // move cursor
+//!   codemp::proto::cursor::CursorPosition {
 //!     buffer: "test.txt".into(),
-//!     start: Some(codemp::proto::RowCol { row: 0, col: 0 }),
-//!     end: Some(codemp::proto::RowCol { row: 0, col: 1 }),
+//!     start: codemp::proto::cursor::RowCol { row: 0, col: 0 },
+//!     end: codemp::proto::cursor::RowCol { row: 0, col: 1 },
 //!   }
 //! )?;
-//! let op = cursor.recv().await?;   // listen for event
+//! let op = workspace.cursor().recv().await?; // receive event from server
 //! println!("received cursor event: {:?}", op);
 //! 
 //! // attach to a new buffer and execute operations on it
-//! session.create("test.txt", None).await?;   // create new buffer
-//! let buffer = session.attach("test.txt").await?; // attach to it
+//! workspace.create("test.txt").await?;   // create new buffer
+//! let buffer = workspace.attach("test.txt").await?; // attach to it
 //! let local_change = TextChange { span: 0..0, content: "hello!".into() };
 //! buffer.send(local_change)?; // insert some text
-//! let remote_change = buffer.recv().await?;
+//! let remote_change = buffer.recv().await?; // await remote change
 //! #
 //! # Ok(())
 //! # }
 //! ```
 //!
 //! ### sync
-//! if async is not viable, including the feature `sync` will provide a sync-only [instance::sync::Instance] variant
+//! if async is not viable, a solution might be keeping a global tokio runtime and blocking on it:
 //!
 //! ```rust,no_run
-//! # use codemp::instance::sync::Instance;
+//! # use codemp::client::Client;
 //! # use std::sync::Arc;
 //! # use codemp::api::Controller;
 //! #
 //! # fn sync_example() -> codemp::Result<()> {
-//! let session = Instance::default();   // instantiate sync variant
-//! session.connect("http://alemi.dev:50051")?;   // connect to server
+//! 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")
+//! )?;
+//!
+//! rt.block_on(session.login(
+//!   "username".to_string(),
+//!   "password".to_string(),
+//!   Some("some_workspace".to_string())
+//! ))?;
+//! 
+//! let workspace = rt.block_on(session.join_workspace("some_workspace"))?;
 //!
 //! // attach to buffer and blockingly receive events
-//! let buffer = session.attach("test.txt")?; // attach to buffer, must already exist
-//! while let Ok(op) = buffer.blocking_recv(session.rt()) {   // must pass runtime
+//! let buffer = rt.block_on(workspace.attach("test.txt"))?; // attach to buffer, must already exist
+//! while let Ok(op) = rt.block_on(buffer.recv()) {   // must pass runtime
 //!   println!("received buffer event: {:?}", op);
 //! }
 //! #
@@ -87,30 +105,6 @@
 //! # }
 //! ```
 //!
-//! ### global
-//! if instantiating the [Instance] manager is not possible, adding the feature `global` will
-//! provide a static lazyly-allocated global reference: [struct@instance::global::INSTANCE].
-//!
-//! ```rust,no_run
-//! # use codemp::instance::sync::Instance;
-//! # use std::sync::Arc;
-//! use codemp::prelude::*;   // prelude includes everything with "Codemp" in front
-//! # fn global_example() -> codemp::Result<()> {
-//! CODEMP_INSTANCE.connect("http://alemi.dev:50051")?;   // connect to server
-//! let cursor = CODEMP_INSTANCE.join("some_workspace")?;   // join workspace
-//! std::thread::spawn(move || {
-//!   loop {
-//!     match cursor.try_recv() {
-//!       Ok(Some(event)) => println!("received cursor event: {:?}", event),  // there might be more
-//!       Ok(None) => std::thread::sleep(std::time::Duration::from_millis(10)),  // wait for more
-//!       Err(e) => break,  // channel closed
-//!     }
-//!   }
-//! });
-//! #  Ok(())
-//! # }
-//! ```
-//!
 //! ## references
 //!
 //! ![another cool pic coz why not](https://alemi.dev/img/about-slice-2.png)