renamed server to listener and add thorough documentation

[connect-rs.git] / src / lib.rs

diff --git a/src/lib.rs b/src/lib.rs
index 8a71a3760c734782b8d4e2244229a06d3e75fd33..85500272bcff76f5c719b6facc65ce334089f120 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,23 @@
+//! This crate provides a reliable, fault-tolerant, and brokerless message-queue abstraction over
+//! asynchronous network streams.
+//!
+//! # Why?
+//! When building networked applications, developers shouldn't have to focus on repeatedly solving
+//! the problem of reliable, fault-tolerant message delivery over byte-streams. By using a message
+//! queue abstraction, crate users can focus on core application logic and leave the low-level
+//! networking and message-queue guarantees to the abstraction.
+//!
+//! # Protobuf
+//! This crate relies on the use of [Protocol Buffers](https://developers.google.com/protocol-buffers)
+//! due to it being widely adopted and industry-proven. All messages are Protobuf messages that
+//! are packed into a Protobuf `Any` type and then sent over the wire. Message recipients must
+//! decide what Protobuf message type it is, and correspondingly unpack the `Any` into a particular
+//! message type.
+//!
+//! # Examples
+//! Please use the [examples](https://github.com/sachanganesh/connect-rs/tree/main/examples)
+//! provided to help understand crate usage.
+
 mod reader;
 pub(crate) mod schema;
 pub mod tcp;
@@ -10,6 +30,8 @@ use async_std::{net::SocketAddr, pin::Pin};
 use futures::{AsyncRead, AsyncWrite};
 pub use futures::{SinkExt, StreamExt};
 
+/// Wrapper around a [`ConnectionReader`] and [`ConnectionWriter`] to read and write on a network
+/// connection
 pub struct Connection {
     local_addr: SocketAddr,
     peer_addr: SocketAddr,
@@ -33,18 +55,25 @@ impl Connection {
         }
     }
 
+    /// Get the local IP address and port
     pub fn local_addr(&self) -> SocketAddr {
         self.local_addr.clone()
     }
 
+    /// Get the peer IP address and port
     pub fn peer_addr(&self) -> SocketAddr {
         self.peer_addr.clone()
     }
 
+    /// Consume the [`Connection`] to split into separate [`ConnectionReader`] and
+    /// [`ConnectionWriter`] halves
+    ///
+    /// [`Connection`]s are split when reading and writing must be concurrent operations.
     pub fn split(self) -> (ConnectionReader, ConnectionWriter) {
         (self.reader, self.writer)
     }
 
+    /// Re-wrap the [`ConnectionReader`] and [`ConnectionWriter`] halves into a [`Connection`]
     pub fn join(reader: ConnectionReader, writer: ConnectionWriter) -> Self {
         Self {
             local_addr: reader.local_addr(),
@@ -54,14 +83,17 @@ impl Connection {
         }
     }
 
+    /// Get mutable access to the underlying [`ConnectionReader`]
     pub fn reader(&mut self) -> &mut ConnectionReader {
         &mut self.reader
     }
 
+    /// Get mutable access to the underlying [`ConnectionWriter`]
     pub fn writer(&mut self) -> &mut ConnectionWriter {
         &mut self.writer
     }
 
+    /// Close the connection by closing both the reading and writing halves
     pub async fn close(self) -> SocketAddr {
         let peer_addr = self.peer_addr();
         let (reader, writer) = self.split();