From dac9ddb4c04a9bb28d95097f44a980a602595fde Mon Sep 17 00:00:00 2001 From: Dylan Bowker Date: Sun, 12 May 2024 08:39:41 -0600 Subject: [PATCH] chore: some docs clean-up --- libraries/native_model/Cargo.toml | 3 +- .../native_model/src/codec/bincode_1_3.rs | 2 +- .../native_model/src/codec/bincode_2_rc.rs | 2 +- libraries/native_model/src/codec/mod.rs | 14 +++++- .../native_model/src/codec/postcard_1_0.rs | 2 +- libraries/native_model/src/lib.rs | 46 +++++++++---------- libraries/native_model/src/wrapper.rs | 2 +- 7 files changed, 40 insertions(+), 31 deletions(-) diff --git a/libraries/native_model/Cargo.toml b/libraries/native_model/Cargo.toml index b91fa456..d20878e1 100644 --- a/libraries/native_model/Cargo.toml +++ b/libraries/native_model/Cargo.toml @@ -32,7 +32,8 @@ criterion = { version = "0.5.1" } skeptic = "0.13.7" [features] -default = ["serde", "bincode_1_3"] +# default = ["serde", "bincode_1_3"] +default = ["serde", "bincode_1_3", "bincode_2_rc", "postcard_1_0", "rmp_serde_1_3"] [[bench]] name = "overhead" diff --git a/libraries/native_model/src/codec/bincode_1_3.rs b/libraries/native_model/src/codec/bincode_1_3.rs index dc598e8f..65ba1379 100644 --- a/libraries/native_model/src/codec/bincode_1_3.rs +++ b/libraries/native_model/src/codec/bincode_1_3.rs @@ -1,4 +1,4 @@ -//! ⚠️ [`Read the docs before using`](crate::bincode_1_3::Bincode#warning). +//! ⚠️ [`Read the docs before using`](crate::bincode_1_3::Bincode#warning) - //! Annotate your type with `native_model::bincode_1_3::Bincode` to use the //! bincode 1.3 crate for serializing & deserializing. diff --git a/libraries/native_model/src/codec/bincode_2_rc.rs b/libraries/native_model/src/codec/bincode_2_rc.rs index 80597947..a49fde6e 100644 --- a/libraries/native_model/src/codec/bincode_2_rc.rs +++ b/libraries/native_model/src/codec/bincode_2_rc.rs @@ -1,4 +1,4 @@ -//! ⚠️ [`Read the docs before using`](crate::bincode_2_rc::Bincode#warning). +//! ⚠️ [`Read the docs before using`](crate::bincode_2_rc::Bincode#warning) - //! Annotate your type with `native_model::bincode_2_rc::Bincode` to use //! the bincode 2.0.0-rc.3 crate for serializing & deserializing. diff --git a/libraries/native_model/src/codec/mod.rs b/libraries/native_model/src/codec/mod.rs index 24c47f6d..4aa57086 100644 --- a/libraries/native_model/src/codec/mod.rs +++ b/libraries/native_model/src/codec/mod.rs @@ -14,7 +14,7 @@ pub mod rmp_serde_1_3; /// /// Example: /// ```rust -/// use bincode_2_rc::{error::EncodeError,serde::encode_to_vec, config::standard}; +/// use bincode_2_rc::{error::EncodeError,serde::encode_to_vec, config::standard}; /// use serde::Serialize; /// pub struct Bincode; /// @@ -27,6 +27,12 @@ pub mod rmp_serde_1_3; /// ``` pub trait Encode { type Error; + /// Encodes a `T` type into a series of bytes. + /// + /// # Errors + /// + /// The errors returned from this function depend on the trait implementor + /// (the serializer), i.e. `bincode_2_rc`. fn encode(obj: &T) -> Result, Self::Error>; } @@ -46,5 +52,11 @@ pub trait Encode { /// } pub trait Decode { type Error; + /// Decodes a series of bytes back into a `T` type. + /// + /// # Errors + /// + /// The errors returned from this function depend on the trait implementor + /// (the deserializer), i.e. `bincode_2_rc`. fn decode(data: Vec) -> Result; } diff --git a/libraries/native_model/src/codec/postcard_1_0.rs b/libraries/native_model/src/codec/postcard_1_0.rs index b37c7d0a..0cc9789d 100644 --- a/libraries/native_model/src/codec/postcard_1_0.rs +++ b/libraries/native_model/src/codec/postcard_1_0.rs @@ -1,4 +1,4 @@ -//! ⚠️ [`Read the docs before using`](crate::postcard_1_0::PostCard#warning). +//! ⚠️ [`Read the docs before using`](crate::postcard_1_0::PostCard#warning) - //! Annotate your type with `native_model::postcard_1_0::PostCard` to //! use the postcard 1.0 crate for serializing & deserializing. diff --git a/libraries/native_model/src/lib.rs b/libraries/native_model/src/lib.rs index 0079b626..a68032c7 100644 --- a/libraries/native_model/src/lib.rs +++ b/libraries/native_model/src/lib.rs @@ -17,7 +17,8 @@ //! //! You may also want to check [David Koloski](https://github.com/djkoloski)'s //! [Rust serialization benchmarks](https://github.com/djkoloski/rust_serialization_benchmark) -//! for help selecting the codec right for your project. +//! for help selecting the codec (i.e. `bincode_1_3`, `rmp_serde_1_3`, etc.) +//! that's best for your project. #![feature(doc_cfg)] @@ -26,6 +27,7 @@ feature = "bincode_1_3", feature = "bincode_2_rc", feature = "postcard_1_0", + feature = "rmp_serde_1_3", doc ))] mod codec; @@ -35,6 +37,7 @@ mod codec; feature = "bincode_1_3", feature = "bincode_2_rc", feature = "postcard_1_0", + feature = "rmp_serde_1_3", doc ))] pub use codec::*; @@ -118,6 +121,11 @@ pub struct DowngradeError { /// See examples: /// - [README.md](https://github.com/vincent-herlemont/native_model) file. /// - other [examples](https://github.com/vincent-herlemont/native_model/tree/master/tests/example) +/// +/// # Errors +/// +/// The errors returned from this function depend on the [`Encode`] trait +/// implementor (the serializer), i.e. `bincode_2_rc`. pub fn encode(model: &T) -> Result> { T::native_model_encode(model) } @@ -134,6 +142,11 @@ pub fn encode_downgrade(model: T, version: u32) -> Result(data: Vec) -> Result<(T, u32)> { T::native_model_decode(data) } @@ -145,18 +158,11 @@ pub trait Model: Sized { fn native_model_version_str() -> &'static str; // --------------- Decode --------------- - fn native_model_decode_body(data: Vec, id: u32) -> DecodeResult - where - Self: Sized; + fn native_model_decode_body(data: Vec, id: u32) -> DecodeResult; - fn native_model_decode_upgrade_body(data: Vec, id: u32, version: u32) -> Result - where - Self: Sized; + fn native_model_decode_upgrade_body(data: Vec, id: u32, version: u32) -> Result; - fn native_model_decode(data: Vec) -> Result<(Self, u32)> - where - Self: Sized, - { + fn native_model_decode(data: Vec) -> Result<(Self, u32)> { let native_model = crate::Wrapper::deserialize(&data[..]).unwrap(); let source_id = native_model.get_id(); let source_version = native_model.get_version(); @@ -170,18 +176,11 @@ pub trait Model: Sized { // --------------- Encode --------------- - fn native_model_encode_body(&self) -> EncodeResult> - where - Self: Sized; + fn native_model_encode_body(&self) -> EncodeResult>; - fn native_model_encode_downgrade_body(self, version: u32) -> Result> - where - Self: Sized; + fn native_model_encode_downgrade_body(self, version: u32) -> Result>; - fn native_model_encode(&self) -> Result> - where - Self: Sized, - { + fn native_model_encode(&self) -> Result> { let mut data = self.native_model_encode_body()?; let data = crate::native_model_encode( &mut data, @@ -191,10 +190,7 @@ pub trait Model: Sized { Ok(data) } - fn native_model_encode_downgrade(self, version: u32) -> Result> - where - Self: Sized, - { + fn native_model_encode_downgrade(self, version: u32) -> Result> { let mut data = self.native_model_encode_downgrade_body(version)?; let data = crate::native_model_encode(&mut data, Self::native_model_id(), version); Ok(data) diff --git a/libraries/native_model/src/wrapper.rs b/libraries/native_model/src/wrapper.rs index c60c036e..8d07ac68 100644 --- a/libraries/native_model/src/wrapper.rs +++ b/libraries/native_model/src/wrapper.rs @@ -17,7 +17,7 @@ impl Wrapper { Some(native_model) } - pub fn value(&self) -> &T { + pub const fn value(&self) -> &T { &self.value }