Comment Updates (Uniswap#45)

* updates various sdk comments`

* cleanup

* Fix code style issues with Prettier

* update re comments

* Fix code style issues with Prettier

* updates re comments

src/entities/route.ts

@@ -5,6 +5,8 @@ import { Pool } from './pool'
 
 /**
  * Represents a list of pools through which a swap can occur
+ * @template TInput The input token
+ * @template TOutput The output token
  */
 export class Route<TInput extends Currency, TOutput extends Currency> {
   public readonly pools: Pool[]
@@ -14,6 +16,12 @@ export class Route<TInput extends Currency, TOutput extends Currency> {
 
   private _midPrice: Price<TInput, TOutput> | null = null
 
+  /**
+   * Creates an instance of route.
+   * @param pools An array of `Pool` objects, ordered by the route the swap will take
+   * @param input The input token
+   * @param output The output token
+   */
   public constructor(pools: Pool[], input: TInput, output: TOutput) {
     invariant(pools.length > 0, 'POOLS')
 

src/entities/tickDataProvider.ts

@@ -12,9 +12,9 @@ export interface TickDataProvider {
 
   /**
    * Return the next tick that is initialized within a single word
-   * @param tick the current tick
-   * @param lte whether the next tick should be lte the current tick
-   * @param tickSpacing the tick spacing of the pool
+   * @param tick The current tick
+   * @param lte Whether the next tick should be lte the current tick
+   * @param tickSpacing The tick spacing of the pool
    */
   nextInitializedTickWithinOneWord(tick: number, lte: boolean, tickSpacing: number): Promise<[number, boolean]>
 }

src/entities/trade.ts

@@ -14,7 +14,15 @@ import { ONE, ZERO } from '../internalConstants'
 import { Pool } from './pool'
 import { Route } from './route'
 
-// extension of the input output comparator that also considers other dimensions of the trade in ranking them
+/**
+ * Trades comparator, an extension of the input output comparator that also considers other dimensions of the trade in ranking them
+ * @template TInput The input token, either Ether or an ERC-20
+ * @template TOutput The output token, either Ether or an ERC-20
+ * @template TTradeType The trade type, either exact input or exact output
+ * @param a The first trade to compare
+ * @param b The second trade to compare
+ * @returns A sorted ordering for two neighboring elements in a trade array
+ */
 export function tradeComparator<TInput extends Currency, TOutput extends Currency, TTradeType extends TradeType>(
   a: Trade<TInput, TOutput, TTradeType>,
   b: Trade<TInput, TOutput, TTradeType>
@@ -52,7 +60,11 @@ export interface BestTradeOptions {
 
 /**
  * Represents a trade executed against a list of pools.
- * Does not account for slippage, i.e. trades that front run this trade and move the price.
+ * Does not account for slippage, i.e., changes in price environment that can occur between
+ * the time the trade is submitted and when it is executed.
+ * @template TInput The input token, either Ether or an ERC-20
+ * @template TOutput The output token, either Ether or an ERC-20
+ * @template TTradeType The trade type, either exact input or exact output
  */
 export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType extends TradeType> {
   /**
@@ -110,8 +122,11 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
 
   /**
    * Constructs an exact in trade with the given amount in and route
-   * @param route route of the exact in trade
-   * @param amountIn the amount being passed in
+   * @template TInput The input token, either Ether or an ERC-20
+   * @template TOutput The output token, either Ether or an ERC-20
+   * @param route The route of the exact in trade
+   * @param amountIn The amount being passed in
+   * @returns The exact in trade
    */
   public static async exactIn<TInput extends Currency, TOutput extends Currency>(
     route: Route<TInput, TOutput>,
@@ -122,8 +137,11 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
 
   /**
    * Constructs an exact out trade with the given amount out and route
-   * @param route route of the exact out trade
-   * @param amountOut the amount returned by the trade
+   * @template TInput The input token, either Ether or an ERC-20
+   * @template TOutput The output token, either Ether or an ERC-20
+   * @param route The route of the exact out trade
+   * @param amountOut The amount returned by the trade
+   * @returns The exact out trade
    */
   public static async exactOut<TInput extends Currency, TOutput extends Currency>(
     route: Route<TInput, TOutput>,
@@ -134,9 +152,13 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
 
   /**
    * Constructs a trade by simulating swaps through the given route
+   * @template TInput The input token, either Ether or an ERC-20.
+   * @template TOutput The output token, either Ether or an ERC-20.
+   * @template TTradeType The type of the trade, either exact in or exact out.
    * @param route route to swap through
    * @param amount the amount specified, either input or output, depending on tradeType
    * @param tradeType whether the trade is an exact input or exact output swap
+   * @returns The route
    */
   public static async fromRoute<TInput extends Currency, TOutput extends Currency, TTradeType extends TradeType>(
     route: Route<TInput, TOutput>,
@@ -183,7 +205,11 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
   /**
    * Creates a trade without computing the result of swapping through the route. Useful when you have simulated the trade
    * elsewhere and do not have any tick data
-   * @param constructorArguments the arguments passed to the trade constructor
+   * @template TInput The input token, either Ether or an ERC-20
+   * @template TOutput The output token, either Ether or an ERC-20
+   * @template TTradeType The type of the trade, either exact in or exact out
+   * @param constructorArguments The arguments passed to the trade constructor
+   * @returns The unchecked trade
    */
   public static createUncheckedTrade<
     TInput extends Currency,
@@ -200,10 +226,10 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
 
   /**
    * Construct a trade by passing in the pre-computed property values
-   * @param route the route through which the trade occurs
-   * @param inputAmount the amount of input paid in the trade
-   * @param outputAmount the amount of output received in the trade
-   * @param tradeType the type of trade, exact input or exact output
+   * @param route The route through which the trade occurs
+   * @param inputAmount The amount of input paid in the trade
+   * @param outputAmount The amount of output received in the trade
+   * @param tradeType The type of trade, exact input or exact output
    */
   private constructor({
     route,
@@ -226,7 +252,8 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
 
   /**
    * Get the minimum amount that must be received from this trade for the given slippage tolerance
-   * @param slippageTolerance tolerance of unfavorable slippage from the execution price of this trade
+   * @param slippageTolerance The tolerance of unfavorable slippage from the execution price of this trade
+   * @returns The amount out
    */
   public minimumAmountOut(slippageTolerance: Percent): CurrencyAmount<TOutput> {
     invariant(!slippageTolerance.lessThan(ZERO), 'SLIPPAGE_TOLERANCE')
@@ -243,7 +270,8 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
 
   /**
    * Get the maximum amount in that can be spent via this trade for the given slippage tolerance
-   * @param slippageTolerance tolerance of unfavorable slippage from the execution price of this trade
+   * @param slippageTolerance The tolerance of unfavorable slippage from the execution price of this trade
+   * @returns The amount in
    */
   public maximumAmountIn(slippageTolerance: Percent): CurrencyAmount<TInput> {
     invariant(!slippageTolerance.lessThan(ZERO), 'SLIPPAGE_TOLERANCE')
@@ -259,6 +287,7 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
   /**
    * Return the execution price after accounting for slippage tolerance
    * @param slippageTolerance the allowed tolerated slippage
+   * @returns The execution price
    */
   public worstExecutionPrice(slippageTolerance: Percent): Price<TInput, TOutput> {
     return new Price(
@@ -282,6 +311,7 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
    * @param currentPools used in recursion; the current list of pools
    * @param currencyAmountIn used in recursion; the original value of the currencyAmountIn parameter
    * @param bestTrades used in recursion; the current list of best trades
+   * @returns The exact in trade
    */
   public static async bestTradeExactIn<TInput extends Currency, TOutput extends Currency>(
     pools: Pool[],
@@ -362,6 +392,7 @@ export class Trade<TInput extends Currency, TOutput extends Currency, TTradeType
    * @param maxHops maximum number of hops a returned trade can make, e.g. 1 hop goes through a single pool
    * @param currentPools used in recursion; the current list of pools
    * @param bestTrades used in recursion; the current list of best trades
+   * @returns The exact out trade
    */
   public static async bestTradeExactOut<TInput extends Currency, TOutput extends Currency>(
     pools: Pool[],

src/nonfungiblePositionManager.ts

@@ -327,8 +327,9 @@ export abstract class NonfungiblePositionManager extends SelfPermit {
 
   /**
    * Produces the calldata for completely or partially exiting a position
-   * @param position the position to exit
-   * @param options additional information necessary for generating the calldata
+   * @param position The position to exit
+   * @param options Additional information necessary for generating the calldata
+   * @returns The call parameters
    */
   public static removeCallParameters(position: Position, options: RemoveLiquidityOptions): MethodParameters {
     const calldatas: string[] = []

src/selfPermit.ts

@@ -21,7 +21,6 @@ export interface AllowedPermitArguments {
 
 export type PermitOptions = StandardPermitArguments | AllowedPermitArguments
 
-// type guard
 function isAllowedPermit(permitOptions: PermitOptions): permitOptions is AllowedPermitArguments {
   return 'nonce' in permitOptions
 }

src/utils/calldata.ts

@@ -15,6 +15,11 @@ export interface MethodParameters {
   value: string
 }
 
+/**
+ * Converts a big int to a hex string
+ * @param bigintIsh
+ * @returns The hex encoded calldata
+ */
 export function toHex(bigintIsh: BigintIsh) {
   const bigInt = JSBI.BigInt(bigintIsh)
   let hex = bigInt.toString(16)

src/utils/computePoolAddress.ts

@@ -9,6 +9,14 @@ import {
   POOL_INIT_CODE_HASH_OPTIMISM_KOVAN
 } from '../constants'
 
+/**
+ * Computes a pool address
+ * @param factoryAddress The Uniswap V3 factory address
+ * @param tokenA The first token of the pair, irrespective of sort order
+ * @param tokenB The second token of the pair, irrespective of sort order
+ * @param fee The fee tier of the pool
+ * @returns The pool address
+ */
 export function computePoolAddress({
   factoryAddress,
   tokenA,

src/utils/encodeSqrtRatioX96.ts

@@ -3,9 +3,11 @@ import { BigintIsh, sqrt } from '@uniswap/sdk-core'
 
 /**
  * Returns the sqrt ratio as a Q64.96 corresponding to a given ratio of amount1 and amount0
- * @param amount1 the numerator amount, i.e. amount of token1
- * @param amount0 the denominator amount, i.en amount of token0
+ * @param amount1 The numerator amount i.e., the amount of token1
+ * @param amount0 The denominator amount i.e., the amount of token0
+ * @returns The sqrt ratio
  */
+
 export function encodeSqrtRatioX96(amount1: BigintIsh, amount0: BigintIsh): JSBI {
   const numerator = JSBI.leftShift(JSBI.BigInt(amount1), JSBI.BigInt(192))
   const denominator = JSBI.BigInt(amount0)

src/utils/isSorted.ts

@@ -1,3 +1,9 @@
+/**
+ * Determines if a tick list is sorted
+ * @param list The tick list
+ * @param comparator The comparator
+ * @returns true if sorted
+ */
 export function isSorted<T>(list: Array<T>, comparator: (a: T, b: T) => number): boolean {
   for (let i = 0; i < list.length - 1; i++) {
     if (comparator(list[i], list[i + 1]) > 0) {

src/utils/maxLiquidityForAmounts.ts

@@ -2,6 +2,17 @@ import { BigintIsh } from '@uniswap/sdk-core'
 import JSBI from 'jsbi'
 import { Q96 } from '../internalConstants'
 
+/**
+ * Returns an imprecise maximum amount of liquidity received for a given amount of token 0.
+ * This function is available to accommodate LiquidityAmounts#getLiquidityForAmount0 in the v3 periphery,
+ * which could be more precise by at least 32 bits by dividing by Q64 instead of Q96 in the intermediate step,
+ * and shifting the subtracted ratio left by 32 bits. This imprecise calculation will likely be replaced in a future
+ * v3 router contract.
+ * @param sqrtRatioAX96 The price at the lower boundary
+ * @param sqrtRatioBX96 The price at the upper boundary
+ * @param amount0 The token0 amount
+ * @returns liquidity for amount0, imprecise
+ */
 function maxLiquidityForAmount0Imprecise(sqrtRatioAX96: JSBI, sqrtRatioBX96: JSBI, amount0: BigintIsh): JSBI {
   if (JSBI.greaterThan(sqrtRatioAX96, sqrtRatioBX96)) {
     ;[sqrtRatioAX96, sqrtRatioBX96] = [sqrtRatioBX96, sqrtRatioAX96]
@@ -10,6 +21,14 @@ function maxLiquidityForAmount0Imprecise(sqrtRatioAX96: JSBI, sqrtRatioBX96: JSB
   return JSBI.divide(JSBI.multiply(JSBI.BigInt(amount0), intermediate), JSBI.subtract(sqrtRatioBX96, sqrtRatioAX96))
 }
 
+/**
+ * Returns a precise maximum amount of liquidity received for a given amount of token 0 by dividing by Q64 instead of Q96 in the intermediate step,
+ * and shifting the subtracted ratio left by 32 bits.
+ * @param sqrtRatioAX96 The price at the lower boundary
+ * @param sqrtRatioBX96 The price at the upper boundary
+ * @param amount0 The token0 amount
+ * @returns liquidity for amount0, precise
+ */
 function maxLiquidityForAmount0Precise(sqrtRatioAX96: JSBI, sqrtRatioBX96: JSBI, amount0: BigintIsh): JSBI {
   if (JSBI.greaterThan(sqrtRatioAX96, sqrtRatioBX96)) {
     ;[sqrtRatioAX96, sqrtRatioBX96] = [sqrtRatioBX96, sqrtRatioAX96]
@@ -21,6 +40,13 @@ function maxLiquidityForAmount0Precise(sqrtRatioAX96: JSBI, sqrtRatioBX96: JSBI,
   return JSBI.divide(numerator, denominator)
 }
 
+/**
+ * Computes the maximum amount of liquidity received for a given amount of token1
+ * @param sqrtRatioAX96 The price at the lower tick boundary
+ * @param sqrtRatioBX96 The price at the upper tick boundary
+ * @param amount1 The token1 amount
+ * @returns liquidity for amount1
+ */
 function maxLiquidityForAmount1(sqrtRatioAX96: JSBI, sqrtRatioBX96: JSBI, amount1: BigintIsh): JSBI {
   if (JSBI.greaterThan(sqrtRatioAX96, sqrtRatioBX96)) {
     ;[sqrtRatioAX96, sqrtRatioBX96] = [sqrtRatioBX96, sqrtRatioAX96]