Merge pull request #4 from mitinarseny/feat/docs

feat: Rust docs

Cargo.toml

@@ -11,11 +11,11 @@ categories = ["encoding"]
 license-file = "LICENSE.txt"
 
 [workspace.dependencies]
-tlb = { path = "./crates/tlb", version = "0.2.20" }
-tlbits = { path = "./crates/bits", version = "0.2.20" }
-tlb-ton = { path = "./crates/tlb-ton", version = "0.2.20" }
-ton-contracts = { path = "./crates/contracts", version = "0.2.20" }
-toner = { path = "./crates/toner", version = "0.2.20" }
+tlb = { path = "./crates/tlb", version = "0.2.21" }
+tlbits = { path = "./crates/bits", version = "0.2.21" }
+tlb-ton = { path = "./crates/tlb-ton", version = "0.2.21" }
+ton-contracts = { path = "./crates/contracts", version = "0.2.21" }
+toner = { path = "./crates/toner", version = "0.2.21" }
 
 anyhow = "1"
 base64 = "0.21"

crates/bits/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tlbits"
-version = "0.2.20"
+version = "0.2.21"
 edition.workspace = true
 repository.workspace = true
 license-file.workspace = true

crates/bits/README.md

@@ -0,0 +1,3 @@
+# Binary [TL-B](https://docs.ton.org/develop/data-formats/tl-b-language) **de**/**ser**ialization
+[![docs.rs](https://img.shields.io/docsrs/tlbits)](https://docs.rs/tlbits/latest/tlbits)
+[![crates.io](https://img.shields.io/crates/v/tlbits)](https://crates.io/crates/tlbits)

crates/bits/src/adapters.rs

@@ -1,11 +1,14 @@
+//! Adapters for [`BitReader`](crate::de::BitReader) / [`BitWriter`](crate::ser::BitWriter)
 use impl_tools::autoimpl;
 
+/// Adapter that maps an error using given closure
 #[autoimpl(Deref using self.inner)]
 pub struct MapErr<T, F> {
     pub(crate) inner: T,
     pub(crate) f: F,
 }
 
+/// `tee`-like adapter for mirroring data read/written
 #[autoimpl(Deref using self.inner)]
 pub struct Tee<T, W> {
     pub(crate) inner: T,
@@ -24,6 +27,7 @@ impl<T, W> Tee<T, W> {
     }
 }
 
+/// Adapter for counting the number of bits read/written.
 #[autoimpl(Deref using self.inner)]
 pub struct BitCounter<T> {
     pub(crate) inner: T,
@@ -36,6 +40,7 @@ impl<T> BitCounter<T> {
         Self { inner, counter: 0 }
     }
 
+    /// Return total number of recorded bits
     #[inline]
     pub const fn bit_count(&self) -> usize {
         self.counter

crates/bits/src/as/args.rs

@@ -7,6 +7,8 @@ use crate::{
 
 use super::Same;
 
+/// Adapter to implement **de**/**ser**ialize with dynamic args for types
+/// that do not require args for seralization.
 pub struct NoArgs<Args, As: ?Sized = Same>(PhantomData<(Args, As)>);
 
 impl<T, As, Args> BitPackAsWithArgs<T> for NoArgs<Args, As>
@@ -39,6 +41,7 @@ where
     }
 }
 
+/// Adapter to implement **de**/**ser**ialize with [`Default`] args.
 pub struct DefaultArgs<As: ?Sized = Same>(PhantomData<As>);
 
 impl<T, As> BitPackAs<T> for DefaultArgs<As>

crates/bits/src/as/bits.rs

@@ -5,6 +5,7 @@ use crate::{
     ser::{r#as::BitPackAs, BitPack, BitWriter, BitWriterExt},
 };
 
+/// **Ser**ialize value by taking a reference to [`BitSlice`] on it.
 pub struct AsBitSlice;
 
 impl<T> BitPackAs<T> for AsBitSlice
@@ -20,6 +21,7 @@ where
     }
 }
 
+/// **Ser**ialize value by taking a reference to `[u8]` on it.
 pub struct AsBytes;
 
 impl<T> BitPackAs<T> for AsBytes
@@ -35,8 +37,10 @@ where
     }
 }
 
+/// **De**/**ser**ialize value from/into exactly `N` bits.
 pub struct NBits<const BITS: usize>;
 
+/// **De**/**ser**ialize bytes by prefixing its length with `N`-bit integer.
 pub struct VarBytes<const BITS_FOR_BYTES_LEN: usize>;
 
 impl<const BITS_FOR_BYTES_LEN: usize, T> BitPackAs<T> for VarBytes<BITS_FOR_BYTES_LEN>

crates/bits/src/as/default.rs

@@ -1,11 +1,32 @@
 use core::marker::PhantomData;
 
-use crate::de::{r#as::BitUnpackAs, BitReader, BitReaderExt};
+use crate::{
+    de::{r#as::BitUnpackAs, BitReader, BitReaderExt},
+    ser::{r#as::BitPackAs, BitWriter, BitWriterExt},
+};
 
 use super::Same;
 
+/// **De**/**ser**ialize [`Default`] on `None` values
 pub struct DefaultOnNone<As: ?Sized = Same>(PhantomData<As>);
 
+impl<T, As> BitPackAs<Option<T>> for DefaultOnNone<As>
+where
+    T: Default,
+    As: BitPackAs<T>,
+{
+    fn pack_as<W>(source: &Option<T>, mut writer: W) -> Result<(), W::Error>
+    where
+        W: BitWriter,
+    {
+        match source {
+            Some(v) => writer.pack_as::<_, &As>(v)?,
+            None => writer.pack_as::<_, As>(T::default())?,
+        };
+        Ok(())
+    }
+}
+
 impl<T, As> BitUnpackAs<T> for DefaultOnNone<As>
 where
     T: Default,

crates/bits/src/as/from_into.rs

@@ -14,6 +14,11 @@ use crate::{
     Error,
 };
 
+/// Serialize value by converting it to/from a proxy type
+/// with serialization support.
+///
+/// See [`TryFromInto`] for more generalized version of this adapter
+/// which uses [`TryFrom`] trait instead
 pub struct FromInto<T>(PhantomData<T>);
 
 impl<T, As> BitPackAs<T> for FromInto<As>
@@ -74,6 +79,11 @@ where
     }
 }
 
+/// Serialize a reference value by converting it to/from a proxy type
+/// with serialization support.
+///
+/// See [`TryFromIntoRef`] for more generalized version of this adapter
+/// which uses [`TryFrom`] trait instead
 pub struct FromIntoRef<T>(PhantomData<T>);
 
 impl<T, As> BitPackAs<T> for FromIntoRef<As>
@@ -134,6 +144,11 @@ where
     }
 }
 
+/// Serialize value by converting it to/from a proxy type
+/// with serialization support.
+///
+/// **Note:** [`FromInto`] is more specialized version of this adapter
+/// which the infailable [`Into`] trait instead.
 pub struct TryFromInto<T>(PhantomData<T>);
 
 impl<T, As> BitPackAs<T> for TryFromInto<As>
@@ -207,3 +222,77 @@ where
             .map_err(Error::custom)
     }
 }
+
+/// Serialize a reference value by converting it to/from a proxy type
+/// with serialization support.
+///
+/// **Note:** [`FromIntoRef`] is more specialized version of this adapter
+/// which the infailable [`Into`] trait instead.
+pub struct TryFromIntoRef<T>(PhantomData<T>);
+
+impl<T, As> BitPackAs<T> for TryFromIntoRef<As>
+where
+    for<'a> &'a T: TryInto<As>,
+    for<'a> <&'a T as TryInto<As>>::Error: Display,
+    As: BitPack,
+{
+    #[inline]
+    fn pack_as<W>(source: &T, writer: W) -> Result<(), W::Error>
+    where
+        W: BitWriter,
+    {
+        source.try_into().map_err(Error::custom)?.pack(writer)
+    }
+}
+
+impl<T, As> BitPackAsWithArgs<T> for TryFromIntoRef<As>
+where
+    for<'a> &'a T: TryInto<As>,
+    for<'a> <&'a T as TryInto<As>>::Error: Display,
+    As: BitPackWithArgs,
+{
+    type Args = As::Args;
+
+    #[inline]
+    fn pack_as_with<W>(source: &T, writer: W, args: Self::Args) -> Result<(), W::Error>
+    where
+        W: BitWriter,
+    {
+        source
+            .try_into()
+            .map_err(Error::custom)?
+            .pack_with(writer, args)
+    }
+}
+
+impl<T, As> BitUnpackAs<T> for TryFromIntoRef<As>
+where
+    As: TryInto<T> + BitUnpack,
+    <As as TryInto<T>>::Error: Display,
+{
+    #[inline]
+    fn unpack_as<R>(reader: R) -> Result<T, R::Error>
+    where
+        R: BitReader,
+    {
+        As::unpack(reader)?.try_into().map_err(Error::custom)
+    }
+}
+
+impl<T, As> BitUnpackAsWithArgs<T> for TryFromIntoRef<As>
+where
+    As: TryInto<T> + BitUnpackWithArgs,
+    <As as TryInto<T>>::Error: Display,
+{
+    type Args = As::Args;
+
+    #[inline]
+    fn unpack_as_with<R>(reader: R, args: Self::Args) -> Result<T, R::Error>
+    where
+        R: BitReader,
+    {
+        As::unpack_with(reader, args)?
+            .try_into()
+            .map_err(Error::custom)
+    }
+}

crates/bits/src/as/integer.rs

@@ -33,7 +33,7 @@ impl<const BITS: usize> BitPackAs<BigUint> for NBits<BITS> {
         let bytes = source.to_bytes_be();
         let mut bits = bytes.as_bits::<Msb0>();
         bits = &bits[bits.len() - used_bits..];
-        writer.with_bits(bits)?;
+        writer.pack(bits)?;
         Ok(())
     }
 }
@@ -70,7 +70,7 @@ impl<const BITS: usize> BitPackAs<BigInt> for NBits<BITS> {
         let bytes = source.to_signed_bytes_be();
         let mut bits = bytes.as_bits::<Msb0>();
         bits = &bits[bits.len() - used_bits..];
-        writer.with_bits(bits)?;
+        writer.pack(bits)?;
         Ok(())
     }
 }
@@ -89,6 +89,14 @@ impl<const BITS: usize> BitUnpackAs<BigInt> for NBits<BITS> {
     }
 }
 
+/// Adapter for [`Var[U]Integer n`](https://docs.ton.org/develop/data-formats/msg-tlb#varuinteger-n)
+/// where `n` is *constant*.
+///
+/// ```tlb
+/// var_uint$_ {n:#} len:(#< n) value:(uint (len * 8)) = VarUInteger n;
+/// var_int$_ {n:#} len:(#< n) value:(int (len * 8)) = VarInteger n;
+/// ```
+/// See [`VarNBits`] for *dynamic* version.
 pub struct VarInt<const BITS_FOR_BYTES_LEN: usize>;
 
 impl<const BITS_FOR_BYTES_LEN: usize> BitPackAs<BigUint> for VarInt<BITS_FOR_BYTES_LEN> {
@@ -153,6 +161,12 @@ impl<const BITS_FOR_BYTES_LEN: usize> BitUnpackAs<BigInt> for VarInt<BITS_FOR_BY
     }
 }
 
+/// Adapter for [`Var[U]Integer (n * 8)`](https://docs.ton.org/develop/data-formats/msg-tlb#varuinteger-n) where `n` is *dynamic*.
+/// ```tlb
+/// var_uint$_ {n:#} len:(#< n) value:(uint (len * 8)) = VarUInteger n;
+/// var_int$_ {n:#} len:(#< n) value:(int (len * 8)) = VarInteger n;
+/// ```
+/// See [`VarInt`] for *constant* version.
 pub struct VarNBits;
 
 impl<T> BitPackAsWithArgs<T> for VarNBits
@@ -207,6 +221,12 @@ where
     }
 }
 
+/// Adapter for [`Var[U]Integer n`](https://docs.ton.org/develop/data-formats/msg-tlb#varuinteger-n) where `n` is *dynamic*.
+/// ```tlb
+/// var_uint$_ {n:#} len:(#< n) value:(uint (len * 8)) = VarUInteger n;
+/// var_int$_ {n:#} len:(#< n) value:(int (len * 8)) = VarInteger n;
+/// ```
+/// See [`VarInt`] for *constant* version.
 pub struct VarNBytes;
 
 impl<T> BitPackAsWithArgs<T> for VarNBytes