docs: also test example docs for correctedness

This commit is contained in:
əlemi 2023-08-20 09:13:21 +02:00
parent 7148b823e6
commit 7f3cba475e

View file

@ -1,10 +1,10 @@
//! # MultiPlayer Code Editing //! # MultiPlayer Code Editinglib
//! //!
//! ![just a nice pic](https://alemi.dev/img/about-slice-1.png) //! ![just a nice pic](https://alemi.dev/img/about-slice-1.png)
//! //!
//! This is the core library of the codemp project. //! This is the core library of the codemp project.
//! //!
//! ## Structure //! ## structure
//! The main entrypoint is the [Client] object, that maintains a connection and can //! The main entrypoint is the [Client] object, that maintains a connection and can
//! be used to join workspaces or attach to buffers. //! be used to join workspaces or attach to buffers.
//! //!
@ -22,69 +22,103 @@
//! //!
//! To generate Operation Sequences use helper methods from the trait [buffer::OperationFactory]. //! To generate Operation Sequences use helper methods from the trait [buffer::OperationFactory].
//! //!
//! ## Features //! ## features
//! * `proto` : include GRCP protocol definitions under [proto] (default enabled) //! * `proto` : include GRCP protocol definitions under [proto] (default enabled)
//! * `global`: provide a lazy_static global INSTANCE in [instance::global] //! * `global`: provide a lazy_static global INSTANCE in [instance::global]
//! * `sync` : wraps the [instance::a_sync::Instance] holder into a sync variant: [instance::sync::Instance] //! * `sync` : wraps the [instance::a_sync::Instance] holder into a sync variant: [instance::sync::Instance]
//! //!
//! ## Examples //! ## examples
//! library can be used both sync and async depending on wether the `sync` feature flag has been //! while the [Client] itself is the core structure implementing all methods, plugins will mostly
//! enabled. a global `INSTANCE` static reference can also be made available with the `global` //! interact with [Instance] managers.
//! flag.
//! //!
//! ### Async //! ### async
//! ```rust,ignore //! this library is natively async and thus async usage should be preferred if possible
//! async fn async_example() -> codemp::Result<()> {
//! let session = codemp::Instance::default(); // create global session
//! session.connect("http://alemi.dev:50051").await?; // connect to remote server
//! //!
//! // join a remote workspace, obtaining a cursor controller //! ```rust,no_run
//! let cursor = session.join("some_workspace").await?; //! use codemp::Controller;
//! cursor.send( // move cursor //! use codemp::buffer::OperationFactory;
//! codemp::proto::CursorPosition {
//! buffer: "test.txt".into(),
//! start: Some(codemp::proto::RowCol { row: 0, col: 0 }),
//! end: Some(codemp::proto::RowCol { row: 0, col: 1 }),
//! }
//! )?;
//! let op = cursor.recv().await?; // listen for event
//! println!("received cursor event: {:?}", op);
//! //!
//! // attach to a new buffer and execute operations on it //! # async fn async_example() -> codemp::Result<()> {
//! session.create("test.txt", None).await?; // create new buffer //! let session = codemp::Instance::default(); // create global session
//! let buffer = session.attach("test.txt").await?; // attach to it //! session.connect("http://alemi.dev:50051").await?; // connect to remote server
//! buffer.send(buffer.insert("hello", 0))?; // insert some text //!
//! if let Some(operation) = buffer.delta(4, "o world", 5) { //! // join a remote workspace, obtaining a cursor controller
//! buffer.send(operation)?; // replace with precision, if valid //! let cursor = session.join("some_workspace").await?;
//! cursor.send( // move cursor
//! codemp::proto::CursorPosition {
//! buffer: "test.txt".into(),
//! start: Some(codemp::proto::RowCol { row: 0, col: 0 }),
//! end: Some(codemp::proto::RowCol { row: 0, col: 1 }),
//! } //! }
//! assert_eq!(buffer.content(), "hello world"); //! )?;
//! let op = cursor.recv().await?; // listen for event
//! println!("received cursor event: {:?}", op);
//! //!
//! Ok(()) //! // 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
//! buffer.send(buffer.insert("hello", 0))?; // insert some text
//! if let Some(operation) = buffer.delta(4, "o world", 5) {
//! buffer.send(operation)?; // replace with precision, if valid
//! } //! }
//! assert_eq!(buffer.content(), "hello world");
//! #
//! # Ok(())
//! # }
//! ``` //! ```
//! //!
//! ### Sync //! ### sync
//! if async is not viable, including the feature `sync` will provide a sync-only Instance variant
//! //!
//! ```rust,ignore //! ```rust,no_run
//! // activate feature "global" to access static CODEMP_INSTANCE //! # use codemp::instance::sync::Instance;
//! use codemp::instance::global::INSTANCE; //! # use std::sync::Arc;
//! # use codemp::Controller;
//! #
//! # fn sync_example() -> codemp::Result<()> {
//! let session = Instance::default(); // instantiate sync variant
//! session.connect("http://alemi.dev:50051")?; // connect to server
//! //!
//! fn sync_example() -> codemp::Result<()> { //! // join remote workspace and handle cursor events with a callback
//! INSTANCE.connect("http://alemi.dev:50051")?; // connect to server //! let cursor = session.join("some_workspace")?; // join workspace
//! let cursor = INSTANCE.join("some_workspace")?; // join workspace //! let (stop, stop_rx) = tokio::sync::mpsc::unbounded_channel(); // create stop channel
//! let (stop, stop_rx) = tokio::sync::mpsc::unbounded_channel(); // create stop channel //! Arc::new(cursor).callback( // register callback
//! Arc::new(cursor).callback( // register callback //! session.rt(), stop_rx, // pass instance runtime and stop channel receiver
//! INSTANCE.rt(), stop_rx, // pass instance runtime and stop channel receiver //! | cursor_event | {
//! | cursor_event | { //! println!("received cursor event: {:?}", cursor_event);
//! println!("received cursor event: {:?}", cursor_event); //! }
//! } //! );
//! );
//! //!
//! Ok(()) //! // 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
//! println!("received buffer event: {:?}", op);
//! } //! }
//! #
//! # Ok(())
//! # }
//! ``` //! ```
//! //!
//! ### reference //! ### global
//! if instantiating the [Instance] manager is not possible, adding the feature `global` will
//! provide a static lazyly-allocated global reference.
//!
//! ```rust,no_run
//! # use codemp::instance::sync::Instance;
//! # use std::sync::Arc;
//! use codemp::prelude::*; // prelude includes everything with "Codemp" in front
//! # async fn global_example() -> codemp::Result<()> {
//! CODEMP_INSTANCE.connect("http://alemi.dev:50051").await?; // connect to server
//! let cursor = CODEMP_INSTANCE.join("some_workspace").await?; // join workspace
//! while let Ok(event) = cursor.recv().await { // receive cursor events
//! println!("received cursor event: {:?}", event);
//! }
//! #
//! # Ok(())
//! # }
//! ```
//!
//! ## references
//! //!
//! ![another cool pic coz why not](https://alemi.dev/img/about-slice-2.png) //! ![another cool pic coz why not](https://alemi.dev/img/about-slice-2.png)
//! //!