Merge pull request #75 from propeller-heads/encoder/hr/ENG-4245-strategy-swap-encoder-docs

docs: add docs for TychoEncoder, StrategyEncoder and SwapEncoder traits

src/encoding/strategy_encoder.rs

@@ -2,14 +2,36 @@ use tycho_core::Bytes;
 
 use crate::encoding::{errors::EncodingError, models::Solution, swap_encoder::SwapEncoder};
 
-/// Encodes a solution using a specific strategy.
+/// A trait that defines how to encode a `Solution` for execution.
 pub trait StrategyEncoder {
+    /// `encode_strategy` takes a `Solution`, which contains all the necessary information about
+    /// the swaps to be performed, and encodes it into a format that can be executed by the router
+    /// or executor contracts.
+    ///
+    /// # Arguments
+    /// * `solution` - The `Solution` to encode, containing swap details, amounts, and execution
+    ///   path
+    ///
+    /// # Returns
+    /// * `Result<(Vec<u8>, Bytes, Option<String>), EncodingError>` - A tuple containing:
+    ///   - The encoded data as bytes
+    ///   - The address of the contract to call (router or executor)
+    ///   - Optionally, the function selector to use when calling the contract
     fn encode_strategy(
         &self,
-        to_encode: Solution,
+        solution: Solution,
     ) -> Result<(Vec<u8>, Bytes, Option<String>), EncodingError>;
 
+    /// Retrieves the swap encoder for a specific protocol system.
+    ///
+    /// # Arguments
+    /// * `protocol_system` - The identifier of the protocol system (e.g., "uniswap_v2")
+    ///
+    /// # Returns
+    /// * `Option<&Box<dyn SwapEncoder>>` - The swap encoder for the protocol if available
     #[allow(clippy::borrowed_box)]
     fn get_swap_encoder(&self, protocol_system: &str) -> Option<&Box<dyn SwapEncoder>>;
+
+    /// Creates a cloned instance of the strategy encoder.
     fn clone_box(&self) -> Box<dyn StrategyEncoder>;
 }

src/encoding/swap_encoder.rs

@@ -3,26 +3,40 @@ use crate::encoding::{
     models::{EncodingContext, Swap},
 };
 
-/// This trait must be implemented in order to encode a single swap for a specific protocol.
+/// A trait for protocol-specific swap encoding, where each implementation should handle the
+/// encoding logic for swaps on a specific protocol.
 pub trait SwapEncoder: Sync + Send {
+    /// Creates a new swap encoder for a specific protocol.
+    ///
+    /// # Arguments
+    /// * `executor_address` - The address of the contract that will execute the swap
     fn new(executor_address: String) -> Self
     where
         Self: Sized;
 
-    /// Encodes a swap and its relevant context information into call data for a specific protocol.
+    /// Encodes a swap for execution on the protocol.
+    ///
+    /// # Arguments
+    /// * `swap` - The swap details including the protocol component, token in, token out, and split
+    /// * `encoding_context` - Additional context needed for encoding (receiver of the tokens,
+    ///   router address, etc.)
+    ///
+    /// # Returns
+    /// The encoded swap data as bytes, directly executable on the executor contract
     fn encode_swap(
         &self,
         swap: Swap,
         encoding_context: EncodingContext,
     ) -> Result<Vec<u8>, EncodingError>;
 
-    /// The address of the executor that will be used to swap through a specific protocol.
+    /// Returns the address of the protocol-specific executor contract.
     fn executor_address(&self) -> &str;
 
-    /// The selector of the executor function that will be called in order to perform a swap.
+    /// Returns the function selector used to execute the swap on the protocol.
     fn swap_selector(&self) -> &str;
 
-    /// Clones the swap encoder as a trait object.
+    /// Creates a cloned instance of the swap encoder.
+    ///
     /// This allows the encoder to be cloned when it is being used as a `Box<dyn SwapEncoder>`.
     fn clone_box(&self) -> Box<dyn SwapEncoder>;
 }

src/encoding/tycho_encoder.rs

@@ -3,9 +3,17 @@ use crate::encoding::{
     models::{Solution, Transaction},
 };
 
-/// An encoder must implement this trait in order to encode a solution into a Transaction for
-/// execution using a Tycho router or related contracts.
+/// A high-level encoder that converts solutions into executable transactions. Allows for modularity
+/// in the encoding process.
 pub trait TychoEncoder {
+    /// Encodes solutions into transactions that can be executed by the Tycho router.
+    ///
+    /// # Arguments
+    /// * `solutions` - Vector of solutions to encode, each potentially using different setups (swap
+    ///   paths, protocols, etc.)
+    ///
+    /// # Returns
+    /// * `Result<Vec<Transaction>, EncodingError>` - Vector of executable transactions
     fn encode_router_calldata(
         &self,
         solutions: Vec<Solution>,