Address review feedback

informalsystems · Jul 28, 2022 · 74a6bde · 74a6bde
1 parent 5d6f9b0
commit 74a6bde
Showing 1 changed file with 57 additions and 57 deletions.
diff --git a/proto/src/protobuf/mod.rs b/proto/src/protobuf/mod.rs
@@ -1,3 +1,60 @@
+//! This module provides an object safe equivalent of the `tendermint_proto::Protobuf` trait,
+//! thereby allowing for easy Google Protocol Buffers encoding and decoding of domain types with
+//! validation.
+//!
+//! Domain types implementing the `Protobuf` trait are expected to implement `TryFrom<T>` and
+//! `Into<T>` where `T` is the raw type. The equivalent object safe `erased` counterparts have
+//! blanket implementations and are derived automatically.
+//!
+//! ## Examples
+//!
+//! ```rust
+//! use core::convert::TryFrom;
+//!
+//! use prost::Message;
+//! use ibc_proto::protobuf::Protobuf;
+//!
+//! // This struct would ordinarily be automatically generated by prost.
+//! #[derive(Clone, PartialEq, Message)]
+//! pub struct MyRawType {
+//!     #[prost(uint64, tag="1")]
+//!     pub a: u64,
+//!     #[prost(string, tag="2")]
+//!     pub b: String,
+//! }
+//!
+//! #[derive(Clone)]
+//! pub struct MyDomainType {
+//!     a: u64,
+//!     b: String,
+//! }
+//!
+//! impl MyDomainType {
+//!     // Trivial constructor with basic validation logic.
+//!     pub fn new(a: u64, b: String) -> Result<Self, String> {
+//!         if a < 1 {
+//!             return Err("a must be greater than 0".to_owned());
+//!         }
+//!         Ok(Self { a, b })
+//!     }
+//! }
+//!
+//! impl TryFrom<MyRawType> for MyDomainType {
+//!     type Error = String;
+//!
+//!     fn try_from(value: MyRawType) -> Result<Self, Self::Error> {
+//!         Self::new(value.a, value.b)
+//!     }
+//! }
+//!
+//! impl From<MyDomainType> for MyRawType {
+//!     fn from(value: MyDomainType) -> Self {
+//!         Self { a: value.a, b: value.b }
+//!     }
+//! }
+//!
+//! impl Protobuf<MyRawType> for MyDomainType {}
+//! ```
 mod erased;
 mod error;
 
@@ -11,63 +68,6 @@ use prost::Message;
 pub use self::error::Error;
 
 /// Object safe equivalent of `tendermint_proto::Protobuf`.
-///
-/// Allows for easy Google Protocol Buffers encoding and decoding of domain
-/// types with validation.
-///
-/// Domain types implementing this trait are expected to implement `TryFrom<T>` and `Into<T>` where
-/// `T` is the raw type. The equivalent object safe `erased` counterparts have blanket
-/// implementations and are derived automatically.
-///
-/// ## Examples
-///
-/// ```rust
-/// use core::convert::TryFrom;
-///
-/// use prost::Message;
-/// use ibc_proto::protobuf::Protobuf;
-///
-/// // This struct would ordinarily be automatically generated by prost.
-/// #[derive(Clone, PartialEq, Message)]
-/// pub struct MyRawType {
-///     #[prost(uint64, tag="1")]
-///     pub a: u64,
-///     #[prost(string, tag="2")]
-///     pub b: String,
-/// }
-///
-/// #[derive(Clone)]
-/// pub struct MyDomainType {
-///     a: u64,
-///     b: String,
-/// }
-///
-/// impl MyDomainType {
-///     /// Trivial constructor with basic validation logic.
-///     pub fn new(a: u64, b: String) -> Result<Self, String> {
-///         if a < 1 {
-///             return Err("a must be greater than 0".to_owned());
-///         }
-///         Ok(Self { a, b })
-///     }
-/// }
-///
-/// impl TryFrom<MyRawType> for MyDomainType {
-///     type Error = String;
-///
-///     fn try_from(value: MyRawType) -> Result<Self, Self::Error> {
-///         Self::new(value.a, value.b)
-///     }
-/// }
-///
-/// impl From<MyDomainType> for MyRawType {
-///     fn from(value: MyDomainType) -> Self {
-///         Self { a: value.a, b: value.b }
-///     }
-/// }
-///
-/// impl Protobuf<MyRawType> for MyDomainType {}
-///
 pub trait Protobuf<T: Message + Default>
 where
     Self: erased::TryFrom<T> + erased::Into<T>,