diff --git a/libraries/native_model/src/codec/bincode_1_3.rs b/libraries/native_model/src/codec/bincode_1_3.rs index 65ba1379..b3d748a8 100644 --- a/libraries/native_model/src/codec/bincode_1_3.rs +++ b/libraries/native_model/src/codec/bincode_1_3.rs @@ -1,6 +1,6 @@ //! ⚠️ [`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. +//! Annotate your type with `native_model::bincode_1_3::Bincode` to have +//! `native_db` use the bincode 1.3 crate for serializing & deserializing. /// Used to specify the [bincode](https://crates.io/crates/bincode/1.3.3) `1.3` /// crate for serialization & deserialization. @@ -11,21 +11,24 @@ /// all [serde](https://crates.io/crates/serde) features. Errors may be /// encountered when using this with some types. /// +/// If you are encountering errors when using this codec on your types, try +/// using the `rmp_serde_1_3` codec instead. +/// /// # Basic usage /// /// Use the [`with`](crate::native_model) attribute on your type to instruct /// `native_model` to use `Bincode` for serialization & deserialization. /// -/// Example: +/// Example usage: /// /// ```rust +/// #[derive(Clone, Default, serde::Deserialize, serde::Serialize)] /// #[native_model(id = 1, version = 1, with = native_model::bincode_1_3::Bincode)] /// struct MyStruct { /// my_string: String /// } /// ``` -#[doc(cfg(all(feature = "serde", feature = "bincode_1_3")))] #[derive(Default)] pub struct Bincode; diff --git a/libraries/native_model/src/codec/bincode_2_rc.rs b/libraries/native_model/src/codec/bincode_2_rc.rs index a49fde6e..5ad31a83 100644 --- a/libraries/native_model/src/codec/bincode_2_rc.rs +++ b/libraries/native_model/src/codec/bincode_2_rc.rs @@ -1,6 +1,7 @@ //! ⚠️ [`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. +//! Enable the `bincode_2_rc` feature and annotate your type with +//! `native_model::bincode_2_rc::Bincode` to have `native_db` use the bincode +//! 2.0.0-rc.3 crate for serializing & deserializing. /// Used to specify the [bincode](https://crates.io/crates/bincode/2.0.0-rc.3) /// `2.0.0-rc.3` crate for serialization & deserialization. @@ -11,21 +12,25 @@ /// all [serde](https://crates.io/crates/serde) features. Errors may be /// encountered when using this with some types. /// +/// If you are encountering errors when using this codec on your types, try +/// using the `rmp_serde_1_3` codec instead. +/// /// # Basic usage /// -/// Use the [`with`](crate::native_model) attribute on your type to instruct +/// After enabling the `bincode_2_rc` feature in your `Cargo.toml`, use the +/// [`with`](crate::native_model) attribute on your type to instruct /// `native_model` to use `Bincode` for serialization & deserialization. /// -/// Example: +/// Example usage: /// /// ```rust +/// #[derive(Clone, Default, serde::Deserialize, serde::Serialize)] /// #[native_model(id = 1, version = 1, with = native_model::bincode_2_rc::Bincode)] /// struct MyStruct { /// my_string: String /// } /// ``` -#[doc(cfg(all(feature = "serde", feature = "bincode_2_rc")))] pub struct Bincode; #[cfg(all(feature = "serde", feature = "bincode_2_rc"))] diff --git a/libraries/native_model/src/codec/postcard_1_0.rs b/libraries/native_model/src/codec/postcard_1_0.rs index 0cc9789d..0b3c7f35 100644 --- a/libraries/native_model/src/codec/postcard_1_0.rs +++ b/libraries/native_model/src/codec/postcard_1_0.rs @@ -1,6 +1,7 @@ //! ⚠️ [`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. +//! Enable the `postcard_1_0` feature and annotate your type with +//! `native_model::postcard_1_0::PostCard` to have `native_db` use the postcard +//! 1.0 crate for serializing & deserializing. /// Used to specify the [postcard](https://crates.io/crates/postcard/1.0.8) /// `1.0` crate for serialization & deserialization. @@ -10,21 +11,25 @@ /// `postcard` does not implement all [serde](https://crates.io/crates/serde) /// features. Errors may be encountered when using this with some types. /// +/// If you are encountering errors when using this codec on your types, try +/// using the `rmp_serde_1_3` codec instead. +/// /// # Basic usage /// -/// Use the [`with`](crate::native_model) attribute on your type to instruct +/// After enabling the `postcard_1_0` feature in your `Cargo.toml`, use the +/// [`with`](crate::native_model) attribute on your type to instruct /// `native_model` to use `PostCard` for serialization & deserialization. /// -/// Example: +/// Example usage: /// /// ```rust +/// #[derive(Clone, Default, serde::Deserialize, serde::Serialize)] /// #[native_model(id = 1, version = 1, with = native_model::postcard_1_0::PostCard)] /// struct MyStruct { /// my_string: String /// } /// ``` -#[doc(cfg(all(feature = "serde", feature = "postcard_1_0")))] pub struct PostCard; #[cfg(all(feature = "serde", feature = "postcard_1_0"))] diff --git a/libraries/native_model/src/codec/rmp_serde_1_3.rs b/libraries/native_model/src/codec/rmp_serde_1_3.rs index ec5cee77..da3a2bea 100644 --- a/libraries/native_model/src/codec/rmp_serde_1_3.rs +++ b/libraries/native_model/src/codec/rmp_serde_1_3.rs @@ -1,25 +1,27 @@ -//! [`Annotate your type`](crate::native_model) with -//! `native_model::rmp_serde_1_3::RmpSerde` to use the rmp-serde 1.3 crate for -//! serializing & deserializing. +//! Enable the `rmp_serde_1_3` feature and +//! [`annotate your type`](crate::native_model) with +//! `native_model::rmp_serde_1_3::RmpSerde` to have `native_db` use the +//! rmp-serde 1.3 crate for serializing & deserializing. /// Used to specify the [rmp-serde](https://crates.io/crates/rmp-serde/1.3.0) /// `1.3` crate for serialization & deserialization. /// /// # Basic usage /// -/// Use the [`with`](crate::native_model) attribute on your type to instruct +/// After enabling the `rmp_serde_1_3` feature in your `Cargo.toml`, use the +/// [`with`](crate::native_model) attribute on your type to instruct /// `native_model` to use `RmpSerde` for serialization & deserialization. /// -/// Example: +/// Example usage: /// /// ```rust +/// #[derive(Clone, Default, serde::Deserialize, serde::Serialize)] /// #[native_model(id = 1, version = 1, with = native_model::rmp_serde_1_3::RmpSerde)] /// struct MyStruct { /// my_string: String /// } /// ``` -#[doc(cfg(all(feature = "serde", feature = "rmp_serde_1_3")))] pub struct RmpSerde; #[cfg(all(feature = "serde", feature = "rmp_serde_1_3"))] diff --git a/libraries/native_model/src/lib.rs b/libraries/native_model/src/lib.rs index a68032c7..30f7d950 100644 --- a/libraries/native_model/src/lib.rs +++ b/libraries/native_model/src/lib.rs @@ -15,13 +15,65 @@ //! //! See examples in the [README.md](https://github.com/vincent-herlemont/native_model) file. //! -//! You may also want to check [David Koloski](https://github.com/djkoloski)'s +//! # Codecs +//! +//! `native_model` comes with several optional built-in serializer features +//! available: +//! +//! - [bincode](https://crates.io/crates/bincode/1.3.3) `1.3` · +//! [`Annotate your type`](crate::native_model) with +//! `native_model::bincode_1_3::Bincode` to have `native_db` use this default +//! codec for serializing & deserializing. **Warning: This codec may not work +//! with all serde-derived types.** +//! +//! - [bincode](https://crates.io/crates/bincode/2.0.0-rc.3) `2.0.0-rc.3` · +//! Enable the `bincode_2_rc` feature and use the +//! `native_model::bincode_2_rc::Bincode` attribute to have `native_db` use this +//! crate. **Warning: This codec may not work with all serde-derived types.** +//! +//! - [postcard](https://crates.io/crates/postcard/1.0.8) `1.0` · +//! Enable the `postcard_1_0` feature and use the +//! `native_model::postcard_1_0::PostCard` attribute. **Warning: This codec may +//! not work with all serde-derived types.** +//! +//! - [rmp-serde](https://crates.io/crates/rmp-serde/1.3.0) `1.3` · +//! Enable the `rmp_serde_1_3` feature and use the +//! `native_model::rmp_serde_1_3::RmpSerde` attribute. +//! +//! ###### Codec example: +//! +//! As example, to use `rmp-serde`: +//! +//! 1. In your project's `Cargo.toml` file, enable the `rmp_serde_1_3` feature +//! for the `native_model` dependency. Check +//! [crates.io](https://crates.io/crates/native_model) for the most recent +//! version number. +//! +//! ```toml +//! [dependencies] +//! serde = { version = "1.0", features = [ "derive" ] } +//! native_model = { version = "0.4", features = [ "rmp_serde_1_3" ] } +//! ``` +//! +//! 2. Assign the `rmp_serde_1_3` codec to your type using the `with` attribute: +//! +//! ```rust +//! #[derive(Clone, Default, serde::Deserialize, serde::Serialize)] +//! #[native_model(id = 1, version = 1, with = native_model::rmp_serde_1_3::RmpSerde)] +//! struct MyStruct { +//! my_string: String, +//! // etc. +//! } +//! ``` +//! +//! ###### Additional reading +//! +//! You may also want to check out +//! [David Koloski](https://github.com/djkoloski)'s //! [Rust serialization benchmarks](https://github.com/djkoloski/rust_serialization_benchmark) //! for help selecting the codec (i.e. `bincode_1_3`, `rmp_serde_1_3`, etc.) //! that's best for your project. -#![feature(doc_cfg)] - #[cfg(any( feature = "serde", feature = "bincode_1_3",