docs(ffi): comparison examples (#47)

docs: added ffi comparison examples

src/ext.rs

@@ -6,7 +6,7 @@ use tokio::sync::mpsc;
 
 /// Poll all given buffer controllers and wait, returning the first one ready.
 ///
-/// It will spawn tasks blocked on [`Controller::poll`] for each buffer controller.
+/// It will spawn tasks blocked on [`AsyncReceiver::poll`] for each buffer controller.
 /// As soon as one finishes, its controller is returned and all other tasks are canceled.
 ///
 /// If a timeout is provided, the result may be `None` if it expires before any task is

src/ffi/mod.rs

@@ -2,12 +2,73 @@
 //! `codemp` aims to be available as a library from as many programming languages as possible.
 //! To achieve this, we rely on Foreign Function Interface.
 //!
+//! ```no_run
+//! # async {
+//! use codemp::api::controller::{AsyncReceiver, AsyncSender}; // needed for send/recv trait methods
+//! 
+//! // connect first, api.code.mp is managed by hexed.technology
+//! let client = codemp::Client::connect(codemp::api::Config::new(
+//!   "mail@example.net", "dont-use-this-password"
+//! )).await?;
+//! 
+//! // create and join a workspace
+//! client.create_workspace("some-workspace").await?;
+//! let workspace = client.join_workspace("some-workspace").await?;
+//! 
+//! // create a new buffer in this workspace and attach to it
+//! workspace.create("/my/file.txt").await?;
+//! let buffer = workspace.attach("/my/file.txt").await?;
+//! 
+//! // write `hello!` at the beginning of this buffer
+//! buffer.send(codemp::api::TextChange {
+//!   start: 0, end: 0,
+//!   content: "hello!".to_string(),
+//! })?;
+//! 
+//! // wait for cursor movements
+//! loop {
+//!   let event = workspace.cursor().recv().await?;
+//!   println!("user {} moved on buffer {}", event.user, event.sel.buffer);
+//! }
+//! # Ok::<(),Box<dyn std::error::Error>>(())
+//! # };
+//! ```
+//!
 //! ## JavaScript
 //! Our JavaScript glue is built with [`napi`](https://napi.rs).
 //!
 //! All async operations are handled on a separate tokio runtime, automatically managed by `napi`.
 //! Callbacks are safely scheduled to be called on the main loop thread.
 //!
+//! ```js
+//! import * as codemp from 'codemp';
+//! 
+//! // connect first, api.code.mp is managed by hexed.technology
+//! let client = await codemp.connect({
+//!   username: "mail@example.net", password: "dont-use-this-password"
+//! });
+//! 
+//! // create and join a workspace
+//! await client.create_workspace("some-workspace");
+//! let workspace = await client.join_workspace("some-workspace");
+//! 
+//! // create a new buffer in this workspace and attach to it
+//! await workspace.create("/my/file.txt");
+//! let buffer = await workspace.attach("/my/file.txt");
+//! 
+//! // write `hello!` at the beginning of this buffer
+//! await buffer.send({
+//!   start: 0, end: 0,
+//!   content: "hello!",
+//! });
+//! 
+//! // wait for cursor movements
+//! while (true) {
+//!   let event = await workspace.cursor().recv();
+//!   console.log(`user ${event.user} moved on buffer ${event.buffer}`);
+//! }
+//! ```
+//!
 //! ## Python
 //! Our Python glue is built with [`PyO3`](https://pyo3.rs).
 //!
@@ -15,6 +76,34 @@
 //! value. The `Future` itself is run on a `tokio` runtime in a dedicated thread, which must be
 //! stared with `codemp.init()` before doing any async operations.
 //!
+//! ```py
+//! import codemp
+//! 
+//! # connect first, api.code.mp is managed by hexed.technology
+//! config = codemp.get_default_config()
+//! config.username = "mail@example.net"
+//! config.password = "dont-use-this-password"
+//! client = codemp.connect(config).wait()
+//! 
+//! # create and join a workspace
+//! client.create_workspace("some-workspace").wait()
+//! workspace = client.join_workspace("some-workspace").wait()
+//! 
+//! # create a new buffer in this workspace and attach to it
+//! workspace.create("/my/file.txt").wait()
+//! buffer = workspace.attach("/my/file.txt").wait()
+//! 
+//! # write `hello!` at the beginning of this buffer
+//! buffer.send(
+//!   0, 0, "hello!"
+//! ).wait()
+//! 
+//! # wait for cursor movements
+//! while true:
+//!   event = workspace.cursor().recv().wait()
+//!   print(f"user {event.user} moved on buffer {event.buffer}")
+//! ```
+//!
 //! ## Lua
 //! Our Lua glue is built with [`mlua`](https://github.com/mlua-rs/mlua).
 //!
@@ -33,6 +122,35 @@
 //! We provide pre-built binaries at [codemp.dev/releases/lua](https://codemp.dev/releases/lua/).
 //! **Please do not rely on this link, as our built binaries will likely move somewhere else soon!**.
 //!
+//! ```lua
+//! CODEMP = require('codemp')
+//! 
+//! -- connect first, api.code.mp is managed by hexed.technology
+//! local client = CODEMP.connect({
+//!   username = "mail@example.net", password = "dont-use-this-password"
+//! }):await()
+//! 
+//! -- create and join a workspace
+//! client:create_workspace("my-workspace"):await()
+//! local workspace = client:join_workspace("my-workspace"):await()
+//! 
+//! -- create a new buffer in this workspace and attach to it
+//! workspace:create_buffer("/my/file.txt"):await()
+//! local buffer = workspace:attach_buffer("/my/file.txt"):await()
+//! 
+//! -- write `hello!` at the beginning of this buffer
+//! buffer:send({
+//!   start = 0, finish = 0, 
+//!   content = "hello!"
+//! }):await()
+//! 
+//! -- wait for cursor movements
+//! while true do
+//!   local event = workspace.cursor:recv():await()
+//!   print("user " .. event.user .. " moved on buffer " .. event.buffer)
+//! end
+//! ```
+//!
 //! ## Java
 //! Our Java glue is built with [`jni`](https://github.com/jni-rs/jni-rs).
 //!
@@ -42,6 +160,34 @@
 //! Exceptions coming from the native side have generally been made checked to imitate Rust's philosophy with `Result`.
 //! `JNIException`s are however unchecked: there is nothing you can do to recover from them, as they usually represent a severe error in the glue code. If they arise, it's probably a bug.
 //!
+//! ```java
+//! import mp.code.*;
+//! 
+//! // connect first, api.code.mp is managed by hexed.technology
+//! Client client = Client.connect(
+//!   new data.Config("mail@example.net", "dont-use-this-password")
+//! );
+//! 
+//! // create and join a workspace
+//! client.createWorkspace("some-workspace");
+//! Workspace workspace = client.joinWorkspace("some-workspace");
+//! 
+//! // create a new buffer in this workspace and attach to it
+//! workspace.createBuffer("/my/file.txt");
+//! BufferController buffer = workspace.attachToBuffer("/my/file.txt");
+//! 
+//! // write `hello!` at the beginning of this buffer
+//! buffer.send(new data.TextChange(
+//!   0, 0, "hello!",
+//!   java.util.OptionalLong.empty() // optional, used for error detection
+//! ));
+//! 
+//! // wait for cursor movements
+//! while (true) {
+//!   data.Cursor event = workspace.getCursor().recv();
+//!   System.out.printf("user %s moved on buffer %s\n", event.user, event.buffer);
+//! }
+//! ```
 
 #![allow(clippy::unit_arg)]
 

src/lib.rs

@@ -88,8 +88,10 @@
 //! * `python`
 //!
 //! For some of these, ready-to-use packages are available in various registries:
-//! * [PyPI (python)](https://pypi.org/project/codemp)
 //! * [npm (javascript)](https://www.npmjs.com/package/codemp)
+//! * [PyPI (python)](https://pypi.org/project/codemp)
+//! * [Maven Central (java)](https://central.sonatype.com/artifact/mp.code/codemp)
+//! * [LuaRocks (lua)](https://luarocks.org/modules/alemi/codemp)
 //!
 #![doc(html_logo_url = "https://code.mp/static/logo-round.png")]
 #![doc(html_favicon_url = "https://code.mp/static/favicon.ico")]