Merge pull request #53 from malik672/chore(doc)

chore(doc): Update comments in code and improve clarity

Author: malik672

Cargo.toml

@@ -1,13 +1,11 @@
 [package]
 name = "uniswap-sdk-core"
-version = "0.17.1"
+version = "0.18.0"
 edition = "2021"
 authors = ["malik <aremumalik05@gmail.com>", "Shuhui Luo <twitter.com/aureliano_law>"]
 description = "The Uniswap SDK Core in Rust provides essential functionality for interacting with the Uniswap decentralized exchange"
 license = "MIT"
 
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
-
 [dependencies]
 alloy-primitives = "0.6"
 bigdecimal = "0.4.2"

rustfmt.toml

@@ -3,3 +3,5 @@ imports_granularity = "Crate"
 max_width = 100
 unstable_features = true
 use_field_init_shorthand = true
+wrap_comments = true
+comment_width = 100

src/addresses.rs

@@ -18,15 +18,15 @@ pub struct ChainAddresses {
 
 pub const DEFAULT_NETWORKS: [ChainId; 3] = [ChainId::MAINNET, ChainId::GOERLI, ChainId::SEPOLIA];
 
-/// returns an hashmap of key pair input of chainid to address
+/// returns a hashmap of key pair input of chainid to address
 ///
 /// # Arguments
 ///
-/// *  Address  
-/// * additional networks a vector of chainid
+/// * `address`: Address
+/// * `additional networks`: a vector of chain ids
 ///
 ///
-/// returns: AdresssMap
+/// returns: [`AdresssMap`]
 pub fn construct_same_address_map(address: Address, additional_networks: &[ChainId]) -> AddressMap {
     let mut networks = DEFAULT_NETWORKS.to_vec();
     networks.extend_from_slice(additional_networks);
@@ -79,7 +79,8 @@ lazy_static! {
 }
 
 impl Default for ChainAddresses {
-    /// Networks that share most of the same addresses i.e. Mainnet, Goerli, Optimism, Arbitrum, Polygon
+    /// Networks that share most of the same addresses i.e. Mainnet, Goerli, Optimism, Arbitrum,
+    /// Polygon
     fn default() -> Self {
         Self {
             v3_core_factory_address: address!("1F98431c8aD98523631AE4a59f267346ea31F984"),

src/entities/base_currency.rs

@@ -11,7 +11,8 @@ pub struct CurrencyLike<M> {
     pub meta: M,
 }
 
-/// A currency is any fungible financial instrument, including Ether, all ERC20 tokens, and other chain-native currencies
+/// A currency is any fungible financial instrument, including Ether, all ERC20 tokens, and other
+/// chain-native currencies
 pub trait BaseCurrency: Clone {
     /// The chain ID on which this currency resides
     fn chain_id(&self) -> ChainId;
@@ -26,7 +27,6 @@ pub trait BaseCurrency: Clone {
     fn name(&self) -> Option<String>;
 }
 
-// Implementation of methods for CurrencyLike
 impl<M: Clone> BaseCurrency for CurrencyLike<M> {
     fn chain_id(&self) -> ChainId {
         self.chain_id
@@ -45,6 +45,7 @@ impl<M: Clone> BaseCurrency for CurrencyLike<M> {
     }
 }
 
+/// Implement [`Deref`] to allow direct access to the metadata of the currency
 impl<M> Deref for CurrencyLike<M> {
     type Target = M;
 

src/entities/ether.rs

@@ -6,10 +6,9 @@ lazy_static! {
 }
 
 /// Ether is the main usage of a 'native' currency, i.e., for Ethereum mainnet and all testnets.
-/// Represents the native currency with additional metadata.
+/// Represents the native currency of the blockchain.
 pub type Ether = CurrencyLike<()>;
 
-/// Implementation of the `CurrencyTrait` for the `Ether` type.
 impl CurrencyTrait for Ether {
     /// Checks if the currency is native to the blockchain.
     fn is_native(&self) -> bool {
@@ -38,9 +37,8 @@ impl CurrencyTrait for Ether {
     }
 }
 
-/// Implementation of additional methods for the `Ether` type.
 impl Ether {
-    /// Creates a new instance of `Ether` with the specified chain ID.
+    /// Creates a new instance of [`Ether`] with the specified chain ID.
     pub fn new(chain_id: u64) -> Self {
         Self {
             chain_id,
@@ -51,7 +49,7 @@ impl Ether {
         }
     }
 
-    /// Retrieves or creates an `Ether` instance for the specified chain ID.
+    /// Retrieves or creates an [`Ether`] instance for the specified chain ID.
     pub fn on_chain(chain_id: u64) -> Self {
         let mut cache = ETHER_CACHE.lock().unwrap();
         match cache.get(&chain_id) {

src/entities/fractions/currency_amount.rs

@@ -1,9 +1,7 @@
 /// External crate dependencies
 use crate::prelude::*;
 
-/// Represents metadata about a currency.
-///
-/// This struct holds information about a currency, including its symbol and the number of decimals.
+/// Currency amount struct that represents a rational amount of a currency
 pub type CurrencyAmount<T> = FractionLike<CurrencyMeta<T>>;
 
 /// Struct representing metadata about a currency
@@ -13,7 +11,6 @@ pub struct CurrencyMeta<T: CurrencyTrait> {
     pub decimal_scale: BigUint,
 }
 
-/// Implementation of methods for CurrencyAmount
 impl<T: CurrencyTrait> CurrencyAmount<T> {
     /// Constructor method for creating a new currency amount
     fn new(
@@ -43,7 +40,7 @@ impl<T: CurrencyTrait> CurrencyAmount<T> {
         Self::new(currency, raw_amount, 1)
     }
 
-    /// Construct a currency amount with a denominator that is not equal to 1
+    /// Construct a currency amount with a denominator that is not equal to 0
     pub fn from_fractional_amount(
         currency: T,
         numerator: impl Into<BigInt>,
@@ -126,10 +123,7 @@ impl<T: CurrencyTrait> CurrencyAmount<T> {
                 .to_fixed(decimal_places, rounding),
         )
     }
-}
 
-/// Implementation for a specific type of CurrencyAmount (Token)
-impl<T: CurrencyTrait> CurrencyAmount<T> {
     /// Wrap the currency amount if the currency is not native
     pub fn wrapped(&self) -> Result<CurrencyAmount<Token>, Error> {
         CurrencyAmount::from_fractional_amount(

src/entities/fractions/fraction.rs

@@ -20,6 +20,7 @@ impl<M: Default> Default for FractionLike<M> {
     }
 }
 
+/// Implement [`Deref`] to allow direct access to the metadata of the fraction
 impl<M> Deref for FractionLike<M> {
     type Target = M;
 
@@ -38,7 +39,7 @@ impl Fraction {
     }
 }
 
-/// Function to convert the custom Rounding enum to `bigdecimal`'s `RoundingMode`
+/// Function to convert the custom Rounding enum to [`bigdecimal`]'s [`RoundingMode`]
 const fn to_rounding_strategy(rounding: Rounding) -> RoundingMode {
     match rounding {
         Rounding::RoundDown => RoundingMode::Down,
@@ -92,12 +93,13 @@ pub trait FractionBase<M>: Sized {
         Self::new(self.denominator(), self.numerator(), self.meta())
     }
 
-    /// Converts the fraction to a `bigdecimal::BigDecimal`
+    /// Converts the fraction to a [`BigDecimal`]
     fn to_decimal(&self) -> BigDecimal {
         BigDecimal::from(self.numerator()).div(BigDecimal::from(self.denominator()))
     }
 
-    /// Converts the fraction to a string with a specified number of significant digits and rounding strategy
+    /// Converts the fraction to a string with a specified number of significant digits and rounding
+    /// strategy
     fn to_significant(&self, significant_digits: u8, rounding: Rounding) -> Result<String, Error> {
         if significant_digits == 0 {
             return Err(Error::Incorrect());
@@ -111,7 +113,8 @@ pub trait FractionBase<M>: Sized {
         Ok(quotient.normalized().to_string())
     }
 
-    /// Converts the fraction to a string with a fixed number of decimal places and rounding strategy
+    /// Converts the fraction to a string with a fixed number of decimal places and rounding
+    /// strategy
     fn to_fixed(&self, decimal_places: u8, rounding: Rounding) -> String {
         let rounding_strategy = to_rounding_strategy(rounding);
         let quotient = self
@@ -121,17 +124,16 @@ pub trait FractionBase<M>: Sized {
         format!("{:.1$}", quotient, decimal_places as usize)
     }
 
-    /// Helper method for converting any superclass back to a simple Fraction
+    /// Helper method for converting any superclass back to a simple [`Fraction`]
     fn as_fraction(&self) -> Fraction {
         Fraction::new(self.numerator(), self.denominator())
     }
 }
 
-/// Implementation of the FractionTrait for FractionLike
 impl<M: Clone + PartialEq> FractionTrait<M> for FractionLike<M> {}
 
 impl<M: Clone> FractionBase<M> for FractionLike<M> {
-    /// Constructor for creating a new Fraction with metadata
+    /// Constructor for creating a new [`FractionLike`] with metadata
     fn new(numerator: impl Into<BigInt>, denominator: impl Into<BigInt>, meta: M) -> Self {
         let denominator = denominator.into();
         // Ensure the denominator is not zero
@@ -239,7 +241,6 @@ impl<M: Clone> Mul for FractionLike<M> {
 
     /// Multiplies the current fraction by another fraction
     fn mul(self, other: Self) -> Self::Output {
-        //There's little to no possibility of an error, so unwrap can be used
         FractionBase::new(
             self.numerator() * other.numerator(),
             self.denominator() * other.denominator(),

src/entities/fractions/percent.rs

@@ -10,29 +10,33 @@ lazy_static! {
 #[derive(Clone, Debug, Default, PartialEq)]
 pub struct IsPercent;
 
-/// Type alias for a Percent, a Fraction with the IsPercent metadata
+/// Type alias for a Percent, a [`FractionLike`] with the [`IsPercent`] metadata
 pub type Percent = FractionLike<IsPercent>;
 
 impl Percent {
-    /// Constructor for creating a new Percent instance
+    /// Constructor for creating a new [`Percent`] instance
     pub fn new(numerator: impl Into<BigInt>, denominator: impl Into<BigInt>) -> Self {
         FractionBase::new(numerator, denominator, IsPercent)
     }
 
-    /// Converts the Percent to a string with a specified number of significant digits and rounding strategy
+    /// Converts the [`Percent`] to a string with a specified number of significant digits and
+    /// rounding strategy
     pub fn to_significant(
         &self,
         significant_digits: u8,
         rounding: Rounding,
     ) -> Result<String, Error> {
-        // Convert the Percent to a simple Fraction, multiply by 100, and then call to_significant on the result
+        // Convert the Percent to a simple Fraction, multiply by 100, and then call to_significant
+        // on the result
         (self.as_fraction() * ONE_HUNDRED.as_fraction())
             .to_significant(significant_digits, rounding)
     }
 
-    /// Converts the Percent to a string with a fixed number of decimal places and rounding strategy
+    /// Converts the [`Percent`] to a string with a fixed number of decimal places and rounding
+    /// strategy
     pub fn to_fixed(&self, decimal_places: u8, rounding: Rounding) -> String {
-        // Convert the Percent to a simple Fraction, multiply by 100, and then call to_fixed on the result
+        // Convert the Percent to a simple Fraction, multiply by 100, and then call to_fixed on the
+        // result
         (self.as_fraction() * ONE_HUNDRED.as_fraction()).to_fixed(decimal_places, rounding)
     }
 }

src/entities/fractions/price.rs

@@ -1,10 +1,10 @@
 /// External crate dependencies
 use crate::prelude::*;
 
-/// Type alias for a Price, a Fraction with metadata PriceMeta
+/// Type alias for a Price, a [`FractionLike`] with metadata [`PriceMeta`]
 pub type Price<TBase, TQuote> = FractionLike<PriceMeta<TBase, TQuote>>;
 
-/// Struct representing metadata for a Price
+/// Struct representing metadata for a [`Price`]
 #[derive(Clone, Debug, PartialEq)]
 pub struct PriceMeta<TBase, TQuote>
 where
@@ -21,7 +21,7 @@ where
     TBase: CurrencyTrait,
     TQuote: CurrencyTrait,
 {
-    /// Constructor for creating a new Price instance
+    /// Constructor for creating a new [`Price`] instance
     pub fn new(
         base_currency: TBase,
         quote_currency: TQuote,
@@ -44,7 +44,7 @@ where
         )
     }
 
-    /// Create a Price instance from currency amounts of the base and quote currencies
+    /// Create a [`Price`] instance from currency amounts of the base and quote currencies
     pub fn from_currency_amounts(
         base_amount: CurrencyAmount<TBase>,
         quote_amount: CurrencyAmount<TQuote>,
@@ -109,7 +109,8 @@ where
         self.as_fraction() * self.scalar.clone()
     }
 
-    /// Converts the adjusted price to a string with a specified number of significant digits and rounding strategy
+    /// Converts the adjusted price to a string with a specified number of significant digits and
+    /// rounding strategy
     pub fn to_significant(
         &self,
         significant_digits: u8,
@@ -119,7 +120,8 @@ where
             .to_significant(significant_digits, rounding)
     }
 
-    /// Converts the adjusted price to a string with a fixed number of decimal places and rounding strategy
+    /// Converts the adjusted price to a string with a fixed number of decimal places and rounding
+    /// strategy
     pub fn to_fixed(&self, decimal_places: u8, rounding: Rounding) -> String {
         self.adjusted_for_decimals()
             .to_fixed(decimal_places, rounding)

src/entities/token.rs

@@ -83,7 +83,34 @@ impl Token {
     }
 }
 
-/// Shorthand macro to create a token
+/// Shorthand macro to create a [`Token`] with the given chain id, address, decimals, optional
+/// symbol and name.
+///
+/// # Arguments
+///
+/// * `chain_id`: The chain id
+/// * `address`: The address of the token as a string, [`Address`] or a string literal without "0x"
+/// * `decimals`: The decimals of the token
+/// * `symbol`: The symbol of the token, optional
+/// * `name`: The name of the token, optional
+///
+/// returns: [`Token`]
+///
+/// # Example
+///
+/// ```
+/// use uniswap_sdk_core::{prelude::*, token};
+///
+/// const DAI_MAINNET: &str = "0x6B175474E89094C44Da98b954EedeAC495271d0F";
+/// let dai: Token = token!(1, DAI_MAINNET, 18, "DAI", "Dai Stablecoin");
+/// let dai: Token = token!(
+///     1,
+///     "6B175474E89094C44Da98b954EedeAC495271d0F",
+///     18,
+///     "DAI",
+///     "Dai Stablecoin"
+/// );
+/// ```
 #[macro_export]
 macro_rules! token {
     ($chain_id:expr, $address:literal, $decimals:expr) => {
@@ -156,7 +183,8 @@ macro_rules! token {
 
 #[cfg(test)]
 mod tests {
-    ///should test for neg chain_id or neg decimals or neg buy_fee or neg sell_fee, but the compiler will panic by itself, so no need
+    ///should test for neg chain_id or neg decimals or neg buy_fee or neg sell_fee, but the
+    /// compiler will panic by itself, so no need
     use super::*;
 
     const ADDRESS_ONE: &str = "0x0000000000000000000000000000000000000001";

src/entities/weth9.rs

@@ -1,21 +1,21 @@
 use crate::{prelude::*, token};
 
-/// `WETH9` represents the WETH9 contract and provides information about WETH tokens on different Ethereum chains.
-
+/// Represents the WETH9 contract and provides information about WETH tokens on different Ethereum
+/// chains.
 #[derive(Clone, PartialEq, Debug)]
 pub struct WETH9 {
     /// A mapping of chain IDs to corresponding WETH tokens.
     tokens: HashMap<u64, Token>,
 }
 
-/// Default implementation for `WETH9`, creating an instance with predefined WETH tokens on various chains.
+/// Default implementation for [`WETH9`], creating an instance with predefined WETH tokens on
+/// various chains.
 impl Default for WETH9 {
     fn default() -> Self {
         Self::new()
     }
 }
 
-/// Implementation for methods specific to the `WETH9` struct.
 impl WETH9 {
     pub fn new() -> Self {
         let mut tokens = HashMap::new();

src/lib.rs

@@ -1,6 +1,7 @@
 //! # uniswap-sdk-core
 //!
-//! The Uniswap SDK Core in Rust provides essential functionality for interacting with the Uniswap decentralized exchange.
+//! The Uniswap SDK Core in Rust provides essential functionality for interacting with the Uniswap
+//! decentralized exchange.
 
 pub mod addresses;
 pub mod chains;