Improve ZcashSerialize docs (#4693)

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};
 

zebra-chain/src/serialization/zcash_deserialize.rs

@@ -1,18 +1,16 @@
-use std::{
+//! Converting bytes into Zcash consensus-critical data structures.
-    convert::{TryFrom, TryInto},
+
-    io,
+use std::{io, net::Ipv6Addr, sync::Arc};
-    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
+/// formats, such as network messages, transactions, blocks, etc.
-/// for use only in consensus-critical contexts; in other contexts, such as
+///
-/// internal storage, it would be preferable to use Serde.
+/// 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`.
     ///

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
+/// formats, such as network messages, transactions, blocks, etc.
-/// for use only in consensus-critical contexts; in other contexts, such as
+///
-/// internal storage, it would be preferable to use Serde.
+/// 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.
     ///