better doc comments

Author: cowlicks

benches/simple.rs

@@ -1,8 +1,7 @@
 use std::time::Instant;
 
 use compact_encoding::{
-    fixed_buffer_from_encoded_size, map_decode, map_encode, sum_encoded_size, CompactEncoding,
-    EncodingError,
+    create_buffer, map_decode, map_encode, sum_encoded_size, CompactEncoding, EncodingError,
 };
 use criterion::{black_box, criterion_group, criterion_main, Criterion};
 
@@ -24,6 +23,10 @@ fn decode(buffer: &[u8]) -> Result<(), EncodingError> {
     Ok(())
 }
 
+fn create_buffer(encoded_size: usize) -> Box<[u8]> {
+    vec![0; encoded_size].into_boxed_slice()
+}
+
 fn preencode_generic_simple(c: &mut Criterion) {
     c.bench_function("preencode generic simple", |b| {
         b.iter(preencode);
@@ -36,7 +39,7 @@ fn create_buffer_generic_simple(c: &mut Criterion) {
             let encoded_size = preencode().unwrap();
             let start = Instant::now();
             for _ in 0..iters {
-                black_box(fixed_buffer_from_encoded_size(encoded_size));
+                black_box(create_buffer(encoded_size));
             }
             start.elapsed()
         });
@@ -48,7 +51,7 @@ fn encode_generic_simple(c: &mut Criterion) {
     c.bench_function("encode generic simple", |b| {
         b.iter_custom(|iters| {
             let encoded_size = preencode().unwrap();
-            let buffer = fixed_buffer_from_encoded_size(encoded_size);
+            let buffer = create_buffer(encoded_size);
             let start = Instant::now();
             for _ in 0..iters {
                 let mut buffer = buffer.clone();

src/error.rs

@@ -10,7 +10,7 @@ pub enum EncodingErrorKind {
     Overflow,
     /// Buffer contained invalid data during decoding.
     InvalidData,
-    /// Some external error occurred causing a [`CompactEncoding`] method to fail.
+    /// Some external error occurred causing a [`crate::CompactEncoding`] method to fail.
     External,
 }
 

src/fixedwidth.rs

@@ -1,20 +1,17 @@
 //! Allow encoding of unsigned ints in a fixed width way, instead of the default variable width.
 //!
-//! # Why?
-//!
-//! By default, unsigned integrers are variable width encoded with [`CompactEncoding`].
-//! However we sometimes want them fixed width encoded.
-//! The [`FixedWidthEncoding`] lets us do this. To fixed width encode an unsigned integrer simply
-//! call [`FixedWidthEncoding::as_fixed_width`] on it. Like this:
-//!
+//! Why? Because the default [`CompactEncoding`] implementation for unsigned integers uses a
+//! variable width encoding. However sometimes want them encoded with a fixed width,
+//! [`FixedWidthEncoding`] lets us do this. To fixed width encode an unsigned integrer simply call
+//! [`FixedWidthEncoding::as_fixed_width`] on it. Like this:
 //! ```
 //! # use compact_encoding::EncodingError;
 //! use compact_encoding::{to_encoded_bytes, FixedWidthEncoding};
 //! let buff = to_encoded_bytes!(42u32.as_fixed_width());
-//! assert_eq!(buff, vec![42, 0, 0, 0]);
+//! assert_eq!(buff, [42, 0, 0, 0].into());
 //! // vs variable width
 //! let buff = to_encoded_bytes!(42u32);
-//! assert_eq!(buff, vec![42]);
+//! assert_eq!(buff, [42].into());
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
 //!
@@ -138,8 +135,8 @@ mod test {
         let x = 42u32;
         let fixed_buff = to_encoded_bytes!(x.as_fixed_width());
         let var_buff = to_encoded_bytes!(x);
-        assert_eq!(fixed_buff, vec![42, 0, 0, 0]);
-        assert_eq!(var_buff, vec![42]);
+        assert_eq!(fixed_buff, [42_u8, 0, 0, 0].into());
+        assert_eq!(var_buff, [42_u8].into());
 
         let ((fixed_dec,), rest) = map_decode!(&fixed_buff, [FixedWidthU32]);
         assert!(rest.is_empty());
@@ -156,8 +153,8 @@ mod test {
         let x = 42u64;
         let fixed_buff = to_encoded_bytes!(x.as_fixed_width());
         let var_buff = to_encoded_bytes!(x);
-        assert_eq!(fixed_buff, vec![42, 0, 0, 0, 0, 0, 0, 0]);
-        assert_eq!(var_buff, vec![42]);
+        assert_eq!(fixed_buff, [42, 0, 0, 0, 0, 0, 0, 0].into());
+        assert_eq!(var_buff, [42].into());
 
         let ((fixed_dec,), rest) = map_decode!(&fixed_buff, [FixedWidthU64]);
         assert!(rest.is_empty());

src/lib.rs

@@ -4,11 +4,12 @@
 //! # Series of compact encoding schemes for building small and fast parsers and serializers
 //!
 //! Binary compatible with the
-//! [original Javascript compact-encoding library](https://github.com/compact-encoding/compact-encoding/).
+//! [original JavaScript compact-encoding library](https://github.com/compact-encoding/compact-encoding/).
 //!
 //! ## Usage
 //!
-//! ### Quick start
+//! The simplest way to encoded and decode a some data is using the [`to_encoded_bytes`] and
+//! [`map_decode`] macros:
 //! ```
 //! use compact_encoding::{map_decode, to_encoded_bytes};
 //!
@@ -23,42 +24,43 @@
 //! assert_eq!(word_dec, word);
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
-//! ### Manually implement encoding and decoding
+//! ### Manual encoding and decoding
 //!
-//! This example shows how to manually calculate the needed buffer size, create the buffer, encode
-//! data, and decode it. Using only the types which include a default [`CompactEncoding`]
-//! implementation. A more ergonomic pattern is demonstrated in other examples
+//! When more fine-grained control of encoding and decoding is needed you manually do each step of
+//! encoding and decoding like in the following example, where we want to use a fixed width
+//! encoding for `number` (instead of the default variable width encoding). It shows how to
+//! manually calculate the needed buffer size, create the buffer, encode data, and decode it.
 //! ```
-//! use compact_encoding::CompactEncoding;
+//! use compact_encoding::{CompactEncoding, FixedWidthEncoding, FixedWidthU32};
 //!
 //! let number = 41_u32;
 //! let word = "hi";
 //!
-//! // Use `encoded_size` to figure out how big a buffer should be.
-//! let size = number.encoded_size()? + word.encoded_size()?;
+//! // Use `encoded_size` to figure out how big a buffer should be
+//! let size = number.as_fixed_width().encoded_size()? + word.encoded_size()?;
 //!
 //! // Create a buffer with the calculated size
 //! let mut buffer = vec![0; size];
-//! assert_eq!(buffer.len(), 1 + 1 + 2);
+//! assert_eq!(buffer.len(), 4 + 1 + 2);
 //!
 //! // Then actually encode the values
-//! let mut remaining_buffer = number.encode(&mut buffer)?;
+//! let mut remaining_buffer = number.as_fixed_width().encode(&mut buffer)?;
 //! remaining_buffer = word.encode(remaining_buffer)?;
 //! assert!(remaining_buffer.is_empty());
-//! assert_eq!(buffer.to_vec(), vec![41_u8, 2_u8, b'h', b'i']);
+//! assert_eq!(buffer.to_vec(), vec![41_u8, 0, 0, 0, 2_u8, b'h', b'i']);
 //!
 //! // `buffer` now contains all the encoded data, and we can decode from it
-//! let (number_dec, remaining_buffer) = u32::decode(&buffer)?;
+//! let (number_dec, remaining_buffer) = FixedWidthU32::decode(&buffer)?;
 //! let (word_dec, remaining_buffer) = String::decode(remaining_buffer)?;
 //! assert!(remaining_buffer.is_empty());
 //! assert_eq!(number_dec, number);
 //! assert_eq!(word_dec, word);
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
 //!
-//! ### Implementing CompactEncoding for new types
+//! ### Implementing CompactEncoding for custom types
 //!
-//! You can implement [`CompactEncoding`]` for your own structs like below:
+//! Here we demonstrate how to implement [`CompactEncoding`] for a custom struct.
 //! ```
 //! use compact_encoding::{
 //!     map_decode, map_encode, sum_encoded_size, to_encoded_bytes, CompactEncoding, EncodingError,
@@ -346,7 +348,7 @@ macro_rules! create_buffer {
                 + $val.encoded_size()?
             )*
         );
-        vec![0; len]
+        vec![0; len].into_boxed_slice()
     }}
 }
 
@@ -360,7 +362,7 @@ macro_rules! create_buffer {
 /// let mut buff = create_buffer!(num, word);
 /// let result = map_encode!(&mut buff, num, word);
 /// assert!(result.is_empty());
-/// assert_eq!(&buff, &[42, 2, b'y', b'o']);
+/// assert_eq!(&*buff, &[42, 2, b'y', b'o']);
 /// # Ok::<(), Box<dyn std::error::Error>>(())
 /// ```
 macro_rules! map_encode {
@@ -384,7 +386,7 @@ macro_rules! map_encode {
 /// ```
 /// # use crate::compact_encoding::to_encoded_bytes;
 /// let result = to_encoded_bytes!(42u64, "yo");
-/// assert_eq!(&result, &[42, 2, 121, 111]);
+/// assert_eq!(&*result, &[42, 2, 121, 111]);
 /// # Ok::<(), Box<dyn std::error::Error>>(())
 /// ```
 macro_rules! to_encoded_bytes {