Better comments & other PR feedback

Author: Marshall Pierce

src/serialization/serialization.rs

@@ -31,7 +31,9 @@
 //!
 //! V2 + DEFLATE is significantly slower to serialize (around 10x) but only a little bit slower to
 //! deserialize (less than 2x). YMMV depending on the compressibility of your histogram data, the
-//! speed of the underlying storage medium, etc.
+//! speed of the underlying storage medium, etc. Naturally, you can always compress at a later time:
+//! there's no reason why you couldn't serialize as V2 and then later re-serialize it as V2 +
+//! DEFLATE on another system (perhaps as a batch job) for better archival storage density.
 //!
 //! # API
 //!
@@ -88,11 +90,11 @@
 //!
 //! impl Serialize for V2HistogramWrapper {
 //!     fn serialize<S: Serializer>(&self, serializer: S) -> Result<(), ()> {
-//!         // not optimal to not re-use the vec and serializer, but it'll work
+//!         // Not optimal to not re-use the vec and serializer, but it'll work
 //!         let mut vec = Vec::new();
-//!         // pick the format you want to use
-//!
-//!         // map errors as appropriate for your use case
+//!         // Pick the serialization format you want to use. Here, we use plain V2, but V2 +
+//!         // DEFLATE is also available.
+//!         // Map errors as appropriate for your use case.
 //!         V2Serializer::new().serialize(&self.histogram, &mut vec)
 //!             .map_err(|_| ())?;
 //!         serializer.serialize_bytes(&vec)?;

src/serialization/v2_deflate_serializer.rs

@@ -58,6 +58,11 @@ impl V2DeflateSerializer {
             .map_err(|e| V2DeflateSerializeError::InternalSerializationError(e))?;
 
         debug_assert_eq!(self.uncompressed_buf.len(), uncompressed_len);
+        // On randomized test histograms we get about 10% compression, but of course random data
+        // doesn't compress well. Real-world data may compress better, so let's assume a more
+        // optimistic 50% compression as a baseline to reserve. If we're overly optimistic that's
+        // still only one more allocation the first time it's needed.
+        self.compressed_buf.reserve(self.uncompressed_buf.len() / 2);
 
         self.compressed_buf.write_u32::<BigEndian>(V2_COMPRESSED_COOKIE)?;
         // placeholder for length
@@ -71,7 +76,7 @@ impl V2DeflateSerializer {
             let mut compressor = DeflateEncoder::new(&mut self.compressed_buf, Compression::Default);
             compressor.write_all(&self.uncompressed_buf[0..uncompressed_len])?;
             let _ = compressor.finish()?;
-        };
+        }
 
         // fill in length placeholder. Won't underflow since length is always at least 8, and won't
         // overflow u32 as the largest array is about 6 million entries, so about 54MiB encoded (if