Update documentation.

Signed-off-by: Andrei Sandu <[email protected]>

Author: sandreim

README.md

@@ -1,9 +1,78 @@
-# versionize
+**Versionize is a framework for version tolerant serializion/deserialization of
+Rust data structures, designed for usecases that need fast deserialization 
+times and minimal size overhead. It does not aim to be a generic serialization 
+framework and only the [bincode](https://crates.io/crates/bincode) backend is 
+supported.**
 
 ## Important note
 
-This crate is currently used for cross-version serialization with the [Firecracker snapshot-restore dev preview](https://github.com/firecracker-microvm/firecracker/tree/v0.23.0), but has not been tested for other use cases. It should be considered **experimental software** outside the Firecracker context. It’s likely that this crate will see both interface and implementation changes in the future.
+This crate is currently used for cross-version serialization with the 
+[Firecracker snapshot-restore dev preview][1], but has not been tested for 
+other use cases. It should be considered **experimental software** outside the 
+Firecracker context. It’s likely that this crate will see both interface and 
+implementation changes in the future.
 
-## Description
+## Versionize in action
 
-Provides version tolerant serialization and deserialization facilities and implements a persistent storage format for state snapshots.
+```rust
+extern crate versionize;
+extern crate versionize_derive;
+
+use versionize::{VersionMap, Versionize, VersionizeResult};
+use versionize_derive::Versionize;
+
+// The test structure is at version 3.
+#[derive(Debug, PartialEq, Versionize)]
+pub struct Test {
+    a: u32,
+    #[version(start = 2, end = 3)]
+    b: u8,
+    #[version(start = 3, default_fn = "default_c")]
+    c: String,
+}
+
+impl Test {
+    // Default value for field `c`.
+    // The callback is invoked when deserializing an older version
+    // where the field did not exist.
+    fn default_c(_source_version: u16) -> String {
+        "test_string".to_owned()
+    }
+}
+
+// Memory to hold the serialization output.
+let mut mem = vec![0u8; 512];
+// Create a new version map - it will start at app version 1.
+let mut version_map = VersionMap::new();
+// Map structure versions to app version.
+version_map
+    .new_version() // App version 2.
+    .set_type_version(Test::type_id(), 2) // Struct(2) -> App(2).
+    .new_version() // App version 3.
+    .set_type_version(Test::type_id(), 3); // Struct(3) -> App(3).
+
+let test_struct = Test {
+    a: 1337,
+    b: 0xFF,
+    c: "c_value".to_owned(),
+};
+
+// Serialize to app version 2 - field c will not be serialized.
+test_struct
+    .serialize(&mut mem.as_mut_slice(), &version_map, 2)
+    .unwrap();
+
+// Deserialize from app version 2 - c should contain the default_fn() return value.
+let restored_test_struct = Test::deserialize(&mut mem.as_slice(), &version_map, 2).unwrap();
+
+assert_eq!(
+    restored_test_struct,
+    Test {
+        a: 1337,
+        b: 255,
+        c: "test_string".to_owned()
+    }
+);
+```
+
+[1]: https://github.com/firecracker-microvm/firecracker/tree/v0.24.0

src/crc.rs

@@ -1,13 +1,29 @@
 // Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-//! Implements readers and writers that compute a CRC64 checksum on the bytes
+//! Implements readers and writers that compute the CRC64 checksum of the bytes
 //! read/written.
 
 use crc64::crc64;
 use std::io::{Read, Write};
 
-/// Computes CRC64 checksums from read bytes.
+/// Computes the CRC64 checksum of the read bytes.
+///
+/// ```
+/// use std::io::Read;
+/// use versionize::crc::CRC64Reader;
+///
+/// let buf = vec![1, 2, 3, 4, 5];
+/// let mut read_buf = Vec::new();
+/// let mut slice = buf.as_slice();
+///
+/// // Create a reader from a slice.
+/// let mut crc_reader = CRC64Reader::new(&mut slice);
+///
+/// let count = crc_reader.read_to_end(&mut read_buf).unwrap();
+/// assert_eq!(crc_reader.checksum(), 0xFB04_60DE_0638_3654);
+/// assert_eq!(read_buf, buf);
+/// ```
 pub struct CRC64Reader<T> {
     reader: T,
     crc64: u64,
@@ -38,7 +54,23 @@ where
     }
 }
 
-/// Computes CRC64 checksums from written bytes.
+/// Computes the CRC64 checksum of the written bytes.
+///
+/// ```
+/// use std::io::Write;
+/// use versionize::crc::CRC64Writer;
+///
+/// let mut buf = vec![0; 16];
+/// let write_buf = vec![123; 16];
+/// let mut slice = buf.as_mut_slice();
+///
+/// // Create a new writer from slice.
+/// let mut crc_writer = CRC64Writer::new(&mut slice);
+///
+/// crc_writer.write_all(&write_buf.as_slice()).unwrap();
+/// assert_eq!(crc_writer.checksum(), 0x29D5_3572_1632_6566);
+/// assert_eq!(write_buf, buf);
+/// ```
 pub struct CRC64Writer<T> {
     writer: T,
     crc64: u64,

src/lib.rs

@@ -2,26 +2,31 @@
 // SPDX-License-Identifier: Apache-2.0
 #![deny(missing_docs)]
 
-//! Provides version tolerant serialization and deserialization facilities and
-//! implements a persistent storage format for Firecracker state snapshots.
-//! The `Versionize` trait defines a generic interface that serializable state structures
-//! need to implement.
+//! Defines a generic interface for version tolerant serialization and
+//! implements it for primitive data types using `bincode` as backend.
 //!
-//! `VersionMap` exposes an API that maps the individual structure versions to
-//! a root version. This mapping is required both when serializing or deserializing structures as
-//! it needs to know which version of structure to serialize for a given target data version.
+//! The interface has two components:
+//! - `Versionize` trait
+//! - `VersionMap` helper
 //!
-//! The Versionize proc macro supports structures and enums.
-//! Supported primitives: u8, u16, u32, u64, usize, i8, i16, i32, i64, isize, char, f32, f64,
-//! String, Vec<T>, Arrays up to 32 elements, Box<T>, Wrapping<T>, Option<T>, FamStructWrapper<T>,
-//! and (T, U).
+//! `VersionMap` maps individual structure/enum versions to a root version
+//! (app version). This mapping is required both when serializing or
+//! deserializing structures as it needs to know which version of structure
+//! to serialize for a given target app version.
+//!
+//! `Versionize` trait is implemented for the following primitives:
+//! u8, u16, u32, u64, usize, i8, i16, i32, i64, isize, char, f32, f64,
+//! String, Vec<T>, Arrays up to 32 elements, Box<T>, Wrapping<T>, Option<T>,
+//! FamStructWrapper<T>, and (T, U).
 //!
 //! Known issues and limitations:
 //! - Union serialization is not supported via the `Versionize` proc macro.
-//! - Implementing Versionize for non-repr(C) unions can result in undefined behaviour
-//! and MUST be avoided.
-//! - Versionize trait implementations for repr(C) unions must be backed by extensive testing.
-//! - Semantic serialization and deserialization is available only for structures.
+//! - Implementing `Versionize` for non-repr(C) unions can result in undefined
+//! behaviour and MUST be avoided.
+//! - Versionize trait implementations for repr(C) unions must be backed by
+//! extensive testing.
+//! - Semantic serialization and deserialization is available only for
+//! structures.
 //!
 extern crate bincode;
 extern crate crc64;
@@ -39,16 +44,16 @@ use std::io::{Read, Write};
 pub use version_map::VersionMap;
 use versionize_derive::Versionize;
 
-/// Versioned serialization error definitions.
+/// Versioned serialization/deserialization error definitions.
 #[derive(Debug, PartialEq)]
 pub enum VersionizeError {
     /// An IO error occured.
     Io(i32),
-    /// A serialization error.
+    /// Generic serialization error.
     Serialize(String),
-    /// A deserialization error.
+    /// Generic deserialization error.
     Deserialize(String),
-    /// A user generated semantic error.
+    /// Semantic translation/validation error.
     Semantic(String),
     /// String length exceeded.
     StringLength(usize),
@@ -84,18 +89,62 @@ impl std::fmt::Display for VersionizeError {
 /// Versioned serialization/deserialization result.
 pub type VersionizeResult<T> = std::result::Result<T, VersionizeError>;
 
-/// Trait that provides an interface for version aware serialization and deserialization.
+/// Trait that provides an interface for version aware serialization and
+/// deserialization.
+/// The [Versionize proc macro][1] can generate an implementation for a given
+/// type if generics are not used, otherwise a manual implementation is
+/// required.
+///
+/// Example implementation
+/// ```
+/// extern crate versionize;
+/// extern crate versionize_derive;
+/// use versionize::{VersionMap, Versionize, VersionizeResult};
+/// use versionize_derive::Versionize;
+///
+/// struct MyType<T>(T);
+///
+/// impl<T> Versionize for MyType<T>
+/// where
+/// T: Versionize,
+/// {
+///     #[inline]
+///     fn serialize<W: std::io::Write>(
+///         &self,
+///         writer: &mut W,
+///         version_map: &VersionMap,
+///         app_version: u16,
+///     ) -> VersionizeResult<()> {
+///         self.0.serialize(writer, version_map, app_version)
+///     }
+///
+///     #[inline]
+///     fn deserialize<R: std::io::Read>(
+///         reader: &mut R,
+///         version_map: &VersionMap,
+///         app_version: u16,
+///     ) -> VersionizeResult<Self> {
+///         Ok(MyType(T::deserialize(reader, version_map, app_version)?))
+///     }
+///
+///     fn version() -> u16 {
+///         1
+///     }
+/// }
+/// ```
+/// [1]: https://docs.rs/versionize_derive/latest/versionize_derive/derive.Versionize.html
 pub trait Versionize {
-    /// Serializes `self` to `target_verion` using the specficifed `writer` and `version_map`.
+    /// Serializes `self` to `target_verion` using the specficifed `writer` and
+    /// `version_map`.
     fn serialize<W: Write>(
         &self,
         writer: &mut W,
         version_map: &VersionMap,
         target_version: u16,
     ) -> VersionizeResult<()>;
 
-    /// Returns a new instance of `Self` by deserialzing from `source_version` using the
-    /// specficifed `reader` and `version_map`.
+    /// Returns a new instance of `Self` by deserializing from `source_version`
+    /// using the specficifed `reader` and `version_map`.
     fn deserialize<R: Read>(
         reader: &mut R,
         version_map: &VersionMap,
@@ -105,6 +154,8 @@ pub trait Versionize {
         Self: Sized;
 
     /// Returns the `Self` type id.
+    /// The returned ID represents a globally unique identifier for a type.
+    /// It is required by the `VersionMap` implementation.
     fn type_id() -> std::any::TypeId
     where
         Self: 'static,

src/primitives.rs

@@ -6,16 +6,15 @@
 use self::super::{VersionMap, Versionize, VersionizeError, VersionizeResult};
 use vmm_sys_util::fam::{FamStruct, FamStructWrapper};
 
-/// Maximum string len in bytes (16KB).
+/// Maximum allowed string len in bytes (16KB).
+/// Calling `serialize()` or `deserialiaze()` will fail beyond this limit.
 pub const MAX_STRING_LEN: usize = 16384;
-/// Maximum vec size in bytes (10MB).
+/// Maximum allowed vec size in bytes (10MB).
+/// Calling `serialize()` or `deserialiaze()` will fail beyond this limit.
 pub const MAX_VEC_SIZE: usize = 10_485_760;
 
-/// Implements the Versionize trait for primitive types that also implement
-/// serde's Serialize/Deserialize: use serde_bincode as a backend for
-/// serialization.
-///
-/// !TODO: Implement a backend abstraction layer so we can easily plug in different backends.
+/// A macro that implements the Versionize trait for primitive types using the
+/// serde bincode backed.
 macro_rules! impl_versionize {
     ($ty:ident) => {
         impl Versionize for $ty {