From 0bb5feebfc70cd5a870f7ff2e200eaf245f601c6 Mon Sep 17 00:00:00 2001 From: bit-aloo <84662239+Shourya742@users.noreply.github.com> Date: Wed, 13 Nov 2024 15:37:18 +0530 Subject: [PATCH] Apply suggestions from code review Co-authored-by: RJ Rybarczyk --- .../no-serde-sv2/codec/src/codec/decodable.rs | 67 +++++++++---------- 1 file changed, 31 insertions(+), 36 deletions(-) diff --git a/protocols/v2/binary-sv2/no-serde-sv2/codec/src/codec/decodable.rs b/protocols/v2/binary-sv2/no-serde-sv2/codec/src/codec/decodable.rs index 24ab8f189..e43111516 100644 --- a/protocols/v2/binary-sv2/no-serde-sv2/codec/src/codec/decodable.rs +++ b/protocols/v2/binary-sv2/no-serde-sv2/codec/src/codec/decodable.rs @@ -10,25 +10,19 @@ use std::convert::TryFrom; #[cfg(not(feature = "no_std"))] use std::io::{Cursor, Read}; -/// Trait that defines how a type can be decoded from raw byte data. -/// -/// This trait describes the process of decoding a data structure from a sequence of bytes. -/// Implementations use a combination of methods to extract the structure of the data, decode its -/// fields, and then construct the type from those decoded fields. It is designed to handle both -/// simple types and nested or complex data structures. -/// -/// - `get_structure`: Describes the layout of the type's fields, allowing the decoder to break down the raw data. -/// - `from_decoded_fields`: Reconstructs the type from individual decoded fields. -/// - `from_bytes`: High-level method that manages the decoding process from raw bytes. -/// - `from_reader`: Reads and decodes data from a stream, useful when working with I/O sources like files or network sockets. + /// Custom deserialization of types from binary data. + /// + /// Defines the process of reconstructing a type from a sequence of bytes. It handles both simple + /// and nested or complex data structures. pub trait Decodable<'a>: Sized { - /// Returns the structure of the type. - /// - /// This method defines the layout of the data fields within the type. The structure - /// returned is used to split raw data into individual fields that can be decoded. + /// Defines the expected structure of a type in terms of individual fields, based on binary + /// data. + /// + /// This function returns a vector of `FieldMarker`s, each representing a component of the + /// structure. Useful for guiding the decoding process. fn get_structure(data: &[u8]) -> Result, Error>; - /// Constructs the type from decoded fields. + /// Constructs the type from a vector of decoded fields. /// /// After the data has been split into fields, this method combines those fields /// back into the original type, handling nested structures or composite fields. @@ -56,11 +50,10 @@ pub trait Decodable<'a>: Sized { Self::from_decoded_fields(fields) } - /// Decodes the type from a reader stream. - /// - /// Instead of working directly with byte slices, this method reads from an I/O source - /// like a file or a network stream. It processes all available data, decodes it, and - /// reconstructs the type. + /// Reads binary data from an input source and decodes an instance of the type. + /// + /// Reads data from any source implementing `Read`, processing all available data, decoding it, + /// and reconstructing the type. #[cfg(not(feature = "no_std"))] fn from_reader(reader: &mut impl Read) -> Result { let mut data = Vec::new(); @@ -78,10 +71,10 @@ pub trait Decodable<'a>: Sized { } } -// Enum representing primitive data markers. +// Primitive data markers. // -// These markers are used to identify primitive types such as integers, booleans, and byte arrays. -// Each variant represents a specific type and is used during decoding to interpret raw data correctly. +// Fundamental data types that can be passed to a decoder to define the structure of the type to be +// decoded in a standardized way. #[derive(Debug, Clone, Copy)] pub enum PrimitiveMarker { U8, @@ -107,23 +100,24 @@ pub enum PrimitiveMarker { /// understand the layout and type of each field in the data, guiding the decoding process. #[derive(Debug, Clone)] pub enum FieldMarker { - /// Primitive Marker + /// A primitive data type. Primitive(PrimitiveMarker), - /// Struct Marker + + /// A structured type composed of multiple fields, allowing for nested data. Struct(Vec), } -/// Trait that provides a mechanism to retrieve the marker associated with a data field. +/// Trait for retrieving the [`FieldMarker`] associated with a type. /// -/// This trait defines a method for getting the marker that represents the structure or -/// type of a given field. It is used to assist in decoding by indicating how to interpret -/// the data. +/// Provides a standardized way to retrieve a `FieldMarker` for a type, allowing the protocol to +/// identify the structure and layout of data fields during decoding. pub trait GetMarker { - /// This helps getting a marker for a type + /// Defines the structure of a type for decoding purposes, supporting both primitive and + /// structured types. It helps getting a marker for a type. fn get_marker() -> FieldMarker; } -// Represents a decoded primitive data type. +// Primitive data types decoded from binary data. // // After decoding, the raw data is transformed into one of these variants, which represent // standard primitive types like integers or binary arrays. The decoder uses these values to @@ -147,16 +141,17 @@ pub enum DecodablePrimitive<'a> { B016M(B016M<'a>), } -/// Represents a decoded field, which may be primitive or a nested structure. +/// A decoded field, which may be primitive or a nested structure. /// -/// Once the raw data is decoded, it is either classified as a primitive (e.g., integer, boolean) +/// Once the raw data is decoded, it is either classified as a primitive (e.g., integer, Boolean) /// or a structure, which may itself contain multiple decoded fields. This type encapsulates that /// distinction. #[derive(Debug)] pub enum DecodableField<'a> { - /// Represents DecodeablePrimitive + /// Primitive field. Primitive(DecodablePrimitive<'a>), - /// Represents vector of DecodableField + + /// Structured field, allowing for nested data structures. Struct(Vec>), }