Documentation update

proto-derive/src/lib.rs

@@ -1,3 +1,8 @@
+//! The DomainType derive macro implements the tendermint_proto::DomainType trait.
+//! This implementation uses the Prost library to convert between Raw types and byte streams.
+//!
+//! Read more about how to use this macro in the DomainType trait definition.
+
 use proc_macro::TokenStream;
 use quote::quote;
 use syn::spanned::Spanned;

proto/src/domaintype.rs

@@ -1,3 +1,50 @@
+//! DomainType trait
+//!
+//! The DomainType trait allows separation of the data sent on the wire (currently encoded using
+//! protobuf) from the structures used in Rust. The structures used to encode/decode from/to the wire
+//! are called "Raw" types (they mirror the definitions in the specifications) and the Rust types
+//! we use internally are called the "Domain" types. These Domain types can implement additional
+//! checks and conversions to consume the incoming data easier for a Rust developer.
+//!
+//! The benefits include decoding the wire into a struct that is inherently valid as well as hiding
+//! the encoding and decoding details from the developer. This latter is important if/when we decide
+//! to exchange the underlying Prost library with something else. (Another protobuf implementation
+//! or a completely different encoding.) Encoding is not the core product of Tendermint it's a
+//! necessary dependency.
+//!
+//!
+//! Decode: bytestream -> Raw -> Domain
+//! The `decode` function takes two steps to decode from a bytestream to a DomainType:
+//!
+//! 1. Decode the bytestream into a Raw type using the Prost library,
+//! 2. Transform that Raw type into a Domain type using the TryFrom trait of the DomainType.
+//!
+//!
+//! Encode: Domain -> Raw -> bytestream
+//! The `encode` function takes two steps to encode a DomainType into a bytestream:
+//!
+//! 1. Transform the Domain type into a Raw type using the From trait of the DomainType,
+//! 2. Encode the Raw type into a bytestream using the Prost library.
+//!
+//!
+//! Note that in the case of encode, the transformation to Raw type is infallible:
+//! Rust structs should always be ready to be encoded to the wire.
+//!
+//! Note that the Prost library and the TryFrom method have their own set of errors. These are
+//! merged into a custom Error type defined in this crate for easier handling.
+//!
+//!
+//! How to implement a DomainType struct:
+//! 1. Implement your struct based on your expectations for the developer
+//! 2. Add the derive macro `#[derive(DomainType)]` on top of it
+//! 3. Add the Raw type as a parameter of the DomainType trait (`[rawtype(MyRawType)]`)
+//! 4. Implement the `TryFrom<MyRawType> for MyDomainType` trait
+//! 5. Implement the `From<MyDomainType> for MyRawType` trait
+//!
+//! Note: the `[rawtype()]` parameter is similar to how `serde` implements serialization through a
+//! `[serde(with="")]` interim type.
+//!
+
 use crate::Error;
 use bytes::{Buf, BufMut};
 use prost::Message;