From c9afe76edc0fc331c285a8a1cd4f71188dea2793 Mon Sep 17 00:00:00 2001
From: trivernis <trivernis@protonmail.com>
Date: Mon, 10 May 2021 11:56:16 +0200
Subject: [PATCH] Update rustdoc

Signed-off-by: trivernis <trivernis@protonmail.com>
---
 src/ipc/builder.rs | 13 +++++++++++++
 src/ipc/client.rs  |  6 +++++-
 src/ipc/context.rs | 17 ++++++++++++++++-
 src/ipc/server.rs  |  7 ++++++-
 src/lib.rs         | 30 ++++++++++++++++++++++++++++++
 5 files changed, 70 insertions(+), 3 deletions(-)

diff --git a/src/ipc/builder.rs b/src/ipc/builder.rs
index df2add9c..8f3e9c17 100644
--- a/src/ipc/builder.rs
+++ b/src/ipc/builder.rs
@@ -9,6 +9,19 @@ use std::future::Future;
 use std::pin::Pin;
 
 #[derive(Clone)]
+/// A builder for the IPC server or client.
+/// ```rust
+///use rmp_ipc::IPCBuilder;
+///IPCBuilder::new()
+///     .address("127.0.0.1:2020")
+///    // register callback
+///     .on("ping", |_ctx, _event| Box::pin(async move {
+///         println!("Received ping event.");
+///         Ok(())
+///     }))
+///     // can also be build_client which would return an emitter for events
+///     .build_server().await.unwrap();
+/// ```
 pub struct IPCBuilder {
     handler: EventHandler,
     address: Option<String>,
diff --git a/src/ipc/client.rs b/src/ipc/client.rs
index a76a9f0b..2d1a3b0b 100644
--- a/src/ipc/client.rs
+++ b/src/ipc/client.rs
@@ -5,12 +5,16 @@ use crate::ipc::context::Context;
 use crate::ipc::stream_emitter::StreamEmitter;
 use tokio::net::TcpStream;
 
+/// The IPC Client to connect to an IPC Server.
+/// Use the [IPCBuilder](crate::builder::IPCBuilder) to create the client.
+/// Usually one does not need to use the IPCClient object directly.
 pub struct IPCClient {
     pub(crate) handler: EventHandler,
 }
 
 impl IPCClient {
-    /// Connects to a given address and returns an emitter for events to that address
+    /// Connects to a given address and returns an emitter for events to that address.
+    /// Invoked by [IPCBuilder::build_client](crate::builder::IPCBuilder::build_client)
     pub async fn connect(self, address: &str) -> Result<StreamEmitter> {
         let stream = TcpStream::connect(address).await?;
         let (mut read_half, write_half) = stream.into_split();
diff --git a/src/ipc/context.rs b/src/ipc/context.rs
index 4fe13de4..6395bb01 100644
--- a/src/ipc/context.rs
+++ b/src/ipc/context.rs
@@ -1,11 +1,26 @@
 use crate::ipc::stream_emitter::StreamEmitter;
 
+/// An object provided to each callback function.
+/// Currently it only holds the event emitter to emit response events in event callbacks.
+/// ```rust
+/// use rmp_ipc::context::Context;
+/// use rmp_ipc::Event;
+/// use rmp_ipc::error::Result;
+///
+/// async fn my_callback(ctx: &Context, _event: Event) -> Result<()> {
+///     // use the emitter on the context object to emit events
+///     // inside callbacks
+///     ctx.emitter.emit("ping", ()).await?;
+///     Ok(())
+/// }
+/// ```
 pub struct Context {
+    /// The event emitter
     pub emitter: StreamEmitter,
 }
 
 impl Context {
-    pub fn new(emitter: StreamEmitter) -> Self {
+    pub(crate) fn new(emitter: StreamEmitter) -> Self {
         Self { emitter }
     }
 }
diff --git a/src/ipc/server.rs b/src/ipc/server.rs
index ace08f0c..6da64816 100644
--- a/src/ipc/server.rs
+++ b/src/ipc/server.rs
@@ -6,11 +6,16 @@ use crate::ipc::stream_emitter::StreamEmitter;
 use std::sync::Arc;
 use tokio::net::{TcpListener, TcpStream};
 
+/// The IPC Server listening for connections.
+/// Use the [IPCBuilder](crate::builder::IPCBuilder) to create a server.
+/// Usually one does not need to use the IPCServer object directly.
 pub struct IPCServer {
     pub(crate) handler: EventHandler,
 }
 
 impl IPCServer {
+    /// Starts the IPC Server.
+    /// Invoked by [IPCBuilder::build_server](crate::builder::IPCBuilder::build_server)
     pub async fn start(self, address: &str) -> Result<()> {
         let listener = TcpListener::bind(address).await?;
         let handler = Arc::new(self.handler);
@@ -27,7 +32,7 @@ impl IPCServer {
     }
 
     /// Handles a single tcp connection
-    pub async fn handle_connection(handler: Arc<EventHandler>, stream: TcpStream) {
+    async fn handle_connection(handler: Arc<EventHandler>, stream: TcpStream) {
         let (mut read_half, write_half) = stream.into_split();
         let emitter = StreamEmitter::new(write_half);
         let ctx = Context::new(StreamEmitter::clone(&emitter));
diff --git a/src/lib.rs b/src/lib.rs
index cf377e31..e5575d1f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,35 @@
 //! This project provides an ipc server and client implementation using
 //! messagepack. All calls are asynchronous and event based.
+//! Client Example:
+//! ```rust
+//! use rmp_ipc::IPCBuilder;
+//! // create the client
+//! let emitter = IPCBuilder::new()
+//!     .address("127.0.0.1:2020")
+//!     // register callback
+//!     .on("ping", |_ctx, _event| Box::pin(async move {
+//!         println!("Received ping event.");
+//!         Ok(())
+//!     }))
+//!     .build_client().await.unwrap();
+//!
+//! // emit an initial event
+//! emitter.emit("ping", ()).await?;
+//! ```
+//!
+//! Server Example:
+//! ```rust
+//! use rmp_ipc::IPCBuilder;
+//! // create the server
+//! IPCBuilder::new()
+//!     .address("127.0.0.1:2020")
+//!     // register callback
+//!     .on("ping", |_ctx, _event| Box::pin(async move {
+//!         println!("Received ping event.");
+//!         Ok(())
+//!     }))
+//!     .build_server().await.unwrap();
+//! ```
 
 #[cfg(test)]
 mod tests;