From 54efbe9d2d0003142e0e3a08772722e24eb34127 Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Tue, 28 Jun 2022 14:02:07 +1000
Subject: [PATCH] Improve ZcashSerialize docs (#4693)

---
 zebra-chain/src/serialization/error.rs         |  2 +-
 .../src/serialization/zcash_deserialize.rs     | 18 ++++++++----------
 .../src/serialization/zcash_serialize.rs       | 11 +++++++----
 3 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/zebra-chain/src/serialization/error.rs b/zebra-chain/src/serialization/error.rs
index 4b11b56a0..03002348c 100644
--- a/zebra-chain/src/serialization/error.rs
+++ b/zebra-chain/src/serialization/error.rs
@@ -1,4 +1,4 @@
-//! Errors for transaction serialization.
+//! Errors for Zcash consensus-critical serialization.
 
 use std::{array::TryFromSliceError, io, num::TryFromIntError, str::Utf8Error};
 
diff --git a/zebra-chain/src/serialization/zcash_deserialize.rs b/zebra-chain/src/serialization/zcash_deserialize.rs
index 833e7bcd6..45b4df061 100644
--- a/zebra-chain/src/serialization/zcash_deserialize.rs
+++ b/zebra-chain/src/serialization/zcash_deserialize.rs
@@ -1,18 +1,16 @@
-use std::{
-    convert::{TryFrom, TryInto},
-    io,
-    net::Ipv6Addr,
-    sync::Arc,
-};
+//! Converting bytes into Zcash consensus-critical data structures.
+
+use std::{io, net::Ipv6Addr, sync::Arc};
 
 use super::{AtLeastOne, CompactSizeMessage, SerializationError, MAX_PROTOCOL_MESSAGE_LEN};
 
-/// Consensus-critical serialization for Zcash.
+/// Consensus-critical deserialization for Zcash.
 ///
 /// This trait provides a generic deserialization for consensus-critical
-/// formats, such as network messages, transactions, blocks, etc. It is intended
-/// for use only in consensus-critical contexts; in other contexts, such as
-/// internal storage, it would be preferable to use Serde.
+/// formats, such as network messages, transactions, blocks, etc.
+///
+/// It is intended for use only for consensus-critical formats.
+/// Internal deserialization can freely use `serde`, or any other format.
 pub trait ZcashDeserialize: Sized {
     /// Try to read `self` from the given `reader`.
     ///
diff --git a/zebra-chain/src/serialization/zcash_serialize.rs b/zebra-chain/src/serialization/zcash_serialize.rs
index 301fe0fbe..d281b8ab1 100644
--- a/zebra-chain/src/serialization/zcash_serialize.rs
+++ b/zebra-chain/src/serialization/zcash_serialize.rs
@@ -1,4 +1,6 @@
-use std::{convert::TryInto, io, net::Ipv6Addr};
+//! Converting Zcash consensus-critical data structures into bytes.
+
+use std::{io, net::Ipv6Addr};
 
 use super::{AtLeastOne, CompactSizeMessage};
 
@@ -10,9 +12,10 @@ pub const MAX_PROTOCOL_MESSAGE_LEN: usize = 2 * 1024 * 1024;
 /// Consensus-critical serialization for Zcash.
 ///
 /// This trait provides a generic serialization for consensus-critical
-/// formats, such as network messages, transactions, blocks, etc. It is intended
-/// for use only in consensus-critical contexts; in other contexts, such as
-/// internal storage, it would be preferable to use Serde.
+/// formats, such as network messages, transactions, blocks, etc.
+///
+/// It is intended for use only for consensus-critical formats.
+/// Internal serialization can freely use `serde`, or any other format.
 pub trait ZcashSerialize: Sized {
     /// Write `self` to the given `writer` using the canonical format.
     ///