more docs

src/entities/token.ts

@@ -16,6 +16,11 @@ export class Token extends Currency {
     this.address = validateAndParseAddress(address)
   }
 
+  /**
+   * Returns true if the two tokens are equivalent.
+   * @param other other token to compare
+   * @throws if the tokens share the address and chain ID but have different metadata
+   */
   public equals(other: Token): boolean {
     // short circuit on reference equality
     if (this === other) {
@@ -31,6 +36,12 @@ export class Token extends Currency {
     return equivalent
   }
 
+  /**
+   * Returns true if the address of this token sorts before the address of the other token
+   * @param other other token to compare
+   * @throws if the tokens have the same address
+   * @throws if the tokens are on different chains
+   */
   public sortsBefore(other: Token): boolean {
     invariant(this.chainId === other.chainId, 'CHAIN_IDS')
     invariant(this.address !== other.address, 'ADDRESSES')

src/entities/trade.ts

@@ -12,8 +12,12 @@ import { Pair } from './pair'
 import { Route } from './route'
 import { currencyEquals, Token, WETH } from './token'
 
-// returns the percent difference between the mid price and the execution price
-// we call this price impact in the UI
+/**
+ * Returns the percent difference between the mid price and the execution price, i.e. price impact.
+ * @param midPrice mid price before the trade
+ * @param inputAmount the input amount of the trade
+ * @param outputAmount the output amount of the trade
+ */
 function computePriceImpact(midPrice: Price, inputAmount: CurrencyAmount, outputAmount: CurrencyAmount): Percent {
   const exactQuote = midPrice.raw.multiply(inputAmount.raw)
   // calculate slippage := (exactQuote - outputAmount) / exactQuote
@@ -95,23 +99,40 @@ function wrappedCurrency(currency: Currency, chainId: ChainId): Token {
   invariant(false, 'CURRENCY')
 }
 
+/**
+ * Represents a trade executed against a list of pairs.
+ * Does not account for slippage, i.e. trades that front run this trade and move the price.
+ */
 export class Trade {
+  /**
+   * The route of the trade, i.e. which pairs the trade goes through.
+   */
   public readonly route: Route
+  /**
+   * The type of the trade, either exact in or exact out.
+   */
   public readonly tradeType: TradeType
+  /**
+   * The input amount for the trade assuming no slippage.
+   */
   public readonly inputAmount: CurrencyAmount
+  /**
+   * The output amount for the trade assuming no slippage.
+   */
   public readonly outputAmount: CurrencyAmount
-  // the price expressed in terms of output/input
+  /**
+   * The price expressed in terms of output amount/input amount.
+   */
   public readonly executionPrice: Price
-  // the mid price after the trade executes assuming zero slippage
+  /**
+   * The mid price after the trade executes assuming no slippage.
+   */
   public readonly nextMidPrice: Price
-  // the percent difference between the mid price before the trade and the price after the trade
+  /**
+   * The percent difference between the mid price before the trade and the trade execution price.
+   */
   public readonly priceImpact: Percent
 
-  // this is a misnomer for price impact, but kept for compatibility
-  public get slippage(): Percent {
-    return this.priceImpact
-  }
-
   /**
    * Constructs an exact in trade with the given amount in and route
    * @param route route of the exact in trade