diff --git a/src/buffer/mod.rs b/src/buffer/mod.rs
index cbe072f..1e97171 100644
--- a/src/buffer/mod.rs
+++ b/src/buffer/mod.rs
@@ -1,4 +1,6 @@
 //! ### buffer
+//!
+//! ![demo gif of early buffer sync in action](https://cdn.alemi.dev/codemp/demo-vscode.gif)
 //! 
 //! a buffer is a container fo text edited by users.
 //! this module contains buffer-related operations and helpers to create Operation Sequences
diff --git a/src/cursor/mod.rs b/src/cursor/mod.rs
index 4f8623c..b362837 100644
--- a/src/cursor/mod.rs
+++ b/src/cursor/mod.rs
@@ -1,4 +1,6 @@
 //! ### cursor
+//!
+//! ![demo gif of early cursor sync in action](https://cdn.alemi.dev/codemp/demo-nvim.gif)
 //! 
 //! each user holds a cursor, which consists of multiple highlighted region 
 //! on a specific buffer
diff --git a/src/lib.rs b/src/lib.rs
index 2436518..37e5832 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -23,11 +23,11 @@
 //! To generate Operation Sequences use helper methods from the trait [buffer::OperationFactory].
 //!
 //! ## Features
-//! * `proto` : include GRCP protocol definitions under [proto] (default)
+//! * `proto` : include GRCP protocol definitions under [proto] (default enabled)
 //! * `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]
 //! 
-//! ## Example
+//! ## Examples
 //! library can be used both sync and async depending on wether the `sync` feature flag has been
 //! enabled. a global `INSTANCE` static reference can also be made available with the `global`
 //! flag.
@@ -160,6 +160,12 @@ pub trait Controller<T : Sized + Send + Sync> : Sized + Send + Sync {
 	fn send(&self, x: Self::Input) -> Result<()>;
 
 	/// get next value from stream, blocking until one is available
+	///
+	/// this is just an async trait function wrapped by `async_trait`:
+	///
+	/// ```
+	/// async fn recv(&self) -> codemp::Result<T>;
+	/// ```
 	async fn recv(&self) -> Result<T>;
 
 	/// sync variant of [Self::recv], blocking invoking thread