explain protobuf choice and bump version to 0.1.0

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

diff --git a/src/lib.rs b/src/lib.rs
index 85500272bcff76f5c719b6facc65ce334089f120..4f1fe18ac1a8b8506465600a1c1c77b65065aa95 100644 (file)
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,5 @@
-//! This crate provides a reliable, fault-tolerant, and brokerless message-queue abstraction over
-//! asynchronous network streams.
+//! This crate provides a simple brokerless message-queue abstraction over asynchronous network
+//! streams.
 //!
 //! # Why?
 //! When building networked applications, developers shouldn't have to focus on repeatedly solving
@@ -7,6 +7,10 @@
 //! queue abstraction, crate users can focus on core application logic and leave the low-level
 //! networking and message-queue guarantees to the abstraction.
 //!
+//! # Examples
+//! Please use the [examples](https://github.com/sachanganesh/connect-rs/tree/main/examples)
+//! provided to help understand crate usage.
+//!
 //! # 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
@@ -14,9 +18,11 @@
 //! 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.
+//! Protobuf was chosen when the library hit a roadblock with Rust's `TypeId` potentially not being
+//! consistent between Rust compiler versions. The crate requires a consistent way to determine what
+//! type of message is received, so it can appropriately deserialize the message from network bytes.
+//! Until the Rust ecosystem around reflection improves, the crate will use Protobuf to fill the
+//! void.
 
 mod reader;
 pub(crate) mod schema;