From e622da79a5933e7f29a9727f60bfe0bfc8a30bd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?dj8yf0=CE=BCl?= Date: Sun, 29 Dec 2024 00:27:25 +0200 Subject: [PATCH] doc: move top level crate doc to an .md file; add Shortcuts header --- borsh/src/lib.rs | 70 +----------------- docs/rustdoc_include/borsh_crate_top_level.md | 74 +++++++++++++++++++ docs/rustdoc_include/borsh_deserialize.md | 2 +- docs/rustdoc_include/borsh_serialize.md | 2 +- 4 files changed, 77 insertions(+), 71 deletions(-) create mode 100644 docs/rustdoc_include/borsh_crate_top_level.md diff --git a/borsh/src/lib.rs b/borsh/src/lib.rs index a6e679bc3..0cdfebb68 100644 --- a/borsh/src/lib.rs +++ b/borsh/src/lib.rs @@ -1,74 +1,6 @@ #![cfg_attr(not(feature = "std"), no_std)] -/*! - -# Crate features - -### Ecosystem features - -* **std** - - When enabled, `borsh` uses the standard library. Disabling this feature will - result in building the crate in `no_std` environment. - - To carter such builds, Borsh offers [`io`] module which includes a items which - are used in [`BorshSerialize`] and [`BorshDeserialize`] traits. Most notably - `io::Read`, `io::Write` and `io::Result`. - - When **std** feature is enabled, those items are re-exports of corresponding - `std::io` items. Otherwise they are borsh-specific types which mimic - behaviour of corresponding standard types. - -### Default features - -* **std** - enabled by default. - -### Other features - -* **derive** - - Gates derive macros of [BorshSerialize] and - [BorshDeserialize] traits. -* **unstable__schema** - - Gates [BorshSchema] trait and its derive macro. - Gates [schema] module. - This feature requires **derive** to be enabled too. -* **rc** - - Gates implementation of [BorshSerialize] and [BorshDeserialize] - for [`Rc`](std::rc::Rc)/[`Arc`](std::sync::Arc) respectively. - In `no_std` setting `Rc`/`Arc` are pulled from `alloc` crate. - Serializing and deserializing these types - does not preserve identity and may result in multiple copies of the same data. - Be sure that this is what you want before enabling this feature. -* **hashbrown** - - Pulls in [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet) when no `std` is available. - This feature is set to be mutually exclusive with **std** feature. -* **bytes** - - Gates implementation of [BorshSerialize] and [BorshDeserialize] - for [Bytes](https://docs.rs/bytes/1.5.0/bytes/struct.Bytes.html) and [BytesMut](https://docs.rs/bytes/1.5.0/bytes/struct.BytesMut.html). -* **bson** - - Gates implementation of [BorshSerialize] and [BorshDeserialize] - for [ObjectId](https://docs.rs/bson/2.9.0/bson/oid/struct.ObjectId.html). -* **ascii** - - Gates implementation of [BorshSerialize], [BorshDeserialize], [BorshSchema] for - types from [ascii](https://docs.rs/ascii/1.1.0/ascii/) crate. -* **de_strict_order** - - Enables check that keys, parsed during deserialization of - [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet) and - [BTreeSet](std::collections::BTreeSet)/[BTreeMap](std::collections::BTreeMap) - are encountered in ascending order with respect to [PartialOrd] for hash collections, - and [Ord] for btree ones. Deserialization emits error otherwise. - - If this feature is not enabled, it is possible that two different byte slices could deserialize into the same `HashMap`/`HashSet` object. - -### Config aliases - -* **hash_collections** - - This is a feature alias, set up in `build.rs` to be equivalent to (**std** OR **hashbrown**). - Gates implementation of [BorshSerialize], [BorshDeserialize] - and [BorshSchema] - for [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet). - - -*/ +#![doc = include_str!("../../docs/rustdoc_include/borsh_crate_top_level.md")] #[cfg(not(feature = "std"))] extern crate alloc; diff --git a/docs/rustdoc_include/borsh_crate_top_level.md b/docs/rustdoc_include/borsh_crate_top_level.md new file mode 100644 index 000000000..a1cfc38cf --- /dev/null +++ b/docs/rustdoc_include/borsh_crate_top_level.md @@ -0,0 +1,74 @@ +# Crate features + +### Ecosystem features + +* **std** - + When enabled, `borsh` uses the standard library. Disabling this feature will + result in building the crate in `no_std` environment. + + To carter such builds, Borsh offers [`io`] module which includes a items which + are used in [`BorshSerialize`] and [`BorshDeserialize`] traits. Most notably + `io::Read`, `io::Write` and `io::Result`. + + When **std** feature is enabled, those items are re-exports of corresponding + `std::io` items. Otherwise they are borsh-specific types which mimic + behaviour of corresponding standard types. + +### Default features + +* **std** - enabled by default. + +### Other features + +* **derive** - + Gates derive macros of [BorshSerialize] and + [BorshDeserialize] traits. +* **unstable__schema** - + Gates [BorshSchema] trait and its derive macro. + Gates [schema] module. + This feature requires **derive** to be enabled too. +* **rc** - + Gates implementation of [BorshSerialize] and [BorshDeserialize] + for [`Rc`](std::rc::Rc)/[`Arc`](std::sync::Arc) respectively. + In `no_std` setting `Rc`/`Arc` are pulled from `alloc` crate. + Serializing and deserializing these types + does not preserve identity and may result in multiple copies of the same data. + Be sure that this is what you want before enabling this feature. +* **hashbrown** - + Pulls in [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet) when no `std` is available. + This feature is set to be mutually exclusive with **std** feature. +* **bytes** - + Gates implementation of [BorshSerialize] and [BorshDeserialize] + for [Bytes](https://docs.rs/bytes/1.5.0/bytes/struct.Bytes.html) and [BytesMut](https://docs.rs/bytes/1.5.0/bytes/struct.BytesMut.html). +* **bson** - + Gates implementation of [BorshSerialize] and [BorshDeserialize] + for [ObjectId](https://docs.rs/bson/2.9.0/bson/oid/struct.ObjectId.html). +* **ascii** - + Gates implementation of [BorshSerialize], [BorshDeserialize], [BorshSchema] for + types from [ascii](https://docs.rs/ascii/1.1.0/ascii/) crate. +* **de_strict_order** - + Enables check that keys, parsed during deserialization of + [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet) and + [BTreeSet](std::collections::BTreeSet)/[BTreeMap](std::collections::BTreeMap) + are encountered in ascending order with respect to [PartialOrd] for hash collections, + and [Ord] for btree ones. Deserialization emits error otherwise. + + If this feature is not enabled, it is possible that two different byte slices could deserialize into the same `HashMap`/`HashSet` object. + +### Config aliases + +* **hash_collections** - + This is a feature alias, set up in `build.rs` to be equivalent to (**std** OR **hashbrown**). + Gates implementation of [BorshSerialize], [BorshDeserialize] + and [BorshSchema] + for [HashMap](std::collections::HashMap)/[HashSet](std::collections::HashSet). + +# Shortcuts + +Following pages are highlighted here just to let reader a better chance at learning that +they exist. + +- [Derive Macro `BorshSerialize`](macro@crate::BorshSerialize) +- [Derive Macro `BorshDeserialize`](macro@crate::BorshDeserialize) +- [Derive Macro `BorshSchema`](macro@crate::BorshSchema) + diff --git a/docs/rustdoc_include/borsh_deserialize.md b/docs/rustdoc_include/borsh_deserialize.md index 8f147eceb..332a4954b 100644 --- a/docs/rustdoc_include/borsh_deserialize.md +++ b/docs/rustdoc_include/borsh_deserialize.md @@ -1,6 +1,6 @@ Derive macro available if borsh is built with `features = ["derive"]`. -# derive proc-macro for `borsh::de::BorshDeserialize` trait +# derive proc-macro for [`BorshDeserialize`] trait ## Bounds diff --git a/docs/rustdoc_include/borsh_serialize.md b/docs/rustdoc_include/borsh_serialize.md index 70f37e0d2..fb40158f1 100644 --- a/docs/rustdoc_include/borsh_serialize.md +++ b/docs/rustdoc_include/borsh_serialize.md @@ -1,6 +1,6 @@ Derive macro available if borsh is built with `features = ["derive"]`. -# derive proc-macro for `borsh::ser::BorshSerialize` trait +# derive proc-macro for [`BorshSerialize`] trait ## Bounds