feat: docs (#6)

src/deserializer.rs

@@ -1,3 +1,11 @@
+//! ### Deserializer
+//! This module contains the deserialization logic for the library. It is used to deserialize
+//! bytes to a custom type.
+//!
+//! To use the deserializer, you need to call the [`from_bytes`] function which takes in
+//! the bytes and a type. The type must implement the `Deserialize` trait from the serde library.
+//! It returns a Result with the deserialized data or an error.
+
 use bitvec::{prelude as bv, slice::BitSlice, view::BitView};
 use serde::{
     de::{EnumAccess, IntoDeserializer, MapAccess, SeqAccess, VariantAccess},
@@ -6,17 +14,17 @@ use serde::{
 
 use super::{error::Error, serializer::Delimiter};
 
-/// Internal struct that handles the deserialization of the data.
-/// It has a few methods that allows us to peek and eat bytes from the data.
-/// It also has methods to parse some data into the required type.
+// Internal struct that handles the deserialization of the data.
+// It has a few methods that allows us to peek and eat bytes from the data.
+// It also has methods to parse some data into the required type.
 #[derive(Debug)]
 struct CustomDeserializer<'de> {
     data: &'de bv::BitSlice<u8, bv::Lsb0>,
 }
 
-/// The main function to deserialize bytes to a type. It makes assumptions
-/// on the bytes based on the specification and the type provided. In order to deserialize from bytes to
-/// a custom type, the type must implement the Deserialize trait from the serde library.
+/// The function to deserialize (serialized) bytes back into data. `T` must implement the `Deserialize` trait
+/// from the `serde` library. `bytes` is the data to be deserialized. It returns a Result with the deserialized
+/// data or an error.
 pub fn from_bytes<'de, T>(bytes: &'de [u8]) -> Result<T, Error>
 where
     T: Deserialize<'de>,

src/error.rs

@@ -1,3 +1,7 @@
+//! ### Error
+//! A module for the error type used in the library. It is a simple enum with a variant for each
+//! error that can occur in the library. It uses `thiserror` internally.
+
 use super::serializer::Delimiter;
 
 #[derive(thiserror::Error, Debug)]

src/lib.rs

@@ -1,3 +1,33 @@
+//! ### rust-fr
+//! A simple, non-self-describing data-interchange format. It exposes two modules, `serializer`
+//! and `deserializer`, for serializing and deserializing data which contain [`to_bytes`](serializer::to_bytes),
+//! [`from_bytes`](deserializer::from_bytes) functions which do exactly what their names suggest.
+//! - The data to be encoded & decoded must implement the `serde::Serialize` and `serde::Deserialize` traits.
+//!
+//! ### Example
+//! ```rust
+//! use rust_fr::{deserializer, serializer};
+//!
+//! #[derive(Debug, serde::Serialize, serde::Deserialize, PartialEq)]
+//! struct Human {
+//!    name: String,
+//!    age: u8,
+//! }
+//!
+//! let human = Human {
+//!    name: "Ayush".to_string(),
+//!    age: 19,
+//! };
+//!
+//! // serialize the data to bytes (Vec<u8>)
+//! let human_bytes = serializer::to_bytes(&human).unwrap();
+//!
+//! // deserialize the data from serialized bytes.
+//! let deserialized_human = deserializer::from_bytes::<Human>(&human_bytes).unwrap();
+//!
+//! assert_eq!(human, deserialized_human);
+//! ```
+
 pub mod deserializer;
 pub mod error;
 pub mod serializer;

src/serializer.rs

@@ -1,3 +1,9 @@
+//! ### Serializer
+//! The module that handles the serialization of the data.
+//!
+//! To use the serializer, call the [`to_bytes`] function with a reference to the data to be
+//! serialized. The data must implement the `Serialize` trait from the `serde` library.
+
 use bitvec::{prelude as bv, slice::BitSlice};
 use serde::{
     ser::{
@@ -9,23 +15,28 @@ use serde::{
 
 use super::error::Error;
 
+/// The delimiter used in the format specification. The purpose
+/// of delimiters is to separate different types of data such
+/// that they don't mangle. There are 8 different delimiters
+/// in the format specification out of which 3 (`String`, `Byte` & `Map`)
+/// are 1 byte long and 5 (the rest...) are 3 bits long.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum Delimiter {
-    /// STRING_DELIMITER: 0b10000110
+    // 0b10000110
     String = 134,
-    /// BYTE_DELIMITER: 0b10000111
+    // 0b10000111
     Byte = 135,
-    /// UNIT: 0b010
+    // 0b010
     Unit = 2,
-    /// SEQ_DELIMITER: 0b011
+    // 0b011
     Seq = 3,
-    /// SEQ_VALUE_DELIMITER: 0b100
+    // 0b100
     SeqValue = 4,
-    /// MAP_DELIMITER: 0b10001011
+    // 0b10001011
     Map = 139,
-    /// MAP_KEY_DELIMITER: 0b110
+    // 0b110
     MapKey = 6,
-    /// MAP_VALUE_DELIMITER: 0b111
+    // 0b111
     MapValue = 7,
 }
 
@@ -44,16 +55,16 @@ impl std::fmt::Display for Delimiter {
     }
 }
 
-/// Internal struct that handles the serialization of the data.
-/// It has a few methods that lets us peeking bytes in the data.
+// Internal struct that handles the serialization of the data.
+// It has a few methods that lets us peeking bytes in the data.
 #[derive(Debug)]
 struct CustomSerializer {
     data: bv::BitVec<u8, bv::Lsb0>,
 }
 
-/// The main function to serialize data of a given type to a byte vector i.e. Vec<u8>. It
-/// uses the format specification to serialize the data. In order to serialize a custom type,
-/// the type must implement the Serialize trait from the serde library.
+/// The function to serialize data of a given type to a byte vector. The
+/// `value` must implement the `Serialize` trait from the `serde` library. It returns
+/// a Result with the serialized byte vector or an error.
 pub fn to_bytes<T: Serialize>(value: &T) -> Result<Vec<u8>, Error> {
     let mut serializer = CustomSerializer {
         data: bv::BitVec::new(),