docs: Improve code documentation with detailed JSDoc comments

src/hooks/useBalance.ts

@@ -51,11 +51,13 @@ const getBalanceBySymbol = async (params: {
 };
 
 /**
- * @param token - The token to fetch the balance of.
- * @param chainId - The chain Id of the chain to execute the query on. If not specified, defaults to the chainId the user is connected to or undefined.
+ * Retrieves the balance of a specific token for a given account and chain.
+ *
+ * @param tokenSymbol - The symbol of the token to retrieve the balance for. If not provided, it will return the Ether (ETH) balance.
+ * @param chainId - The ID of the chain to execute the query on. If not specified, defaults to the chainId the user is connected to or undefined.
  * @param account - The account to query the balance of.
  * @remarks Passing the zero address as token will return the ETH balance. Passing no account will return the balance of the connected account.
- * @returns The balance of the account and the UseQueryResult object
+ * @returns An object containing the balance of the account (as a `BigNumber`) and the `UseQueryResult` object.
  */
 export function useBalanceBySymbol(
   tokenSymbol?: string,

src/hooks/useBridgeFees.ts

@@ -10,6 +10,7 @@ import { AxiosError } from "axios";
  * @param toChainId The chain Id of the receiving chain, its timestamp will be used to calculate the fees.
  * @param inputTokenSymbol - The input token symbol to check bridge fees for.
  * @param outputTokenSymbol - The output token symbol to check bridge fees for.
+ * @param recipientAddress - The recipient address for the bridged tokens.
  * @returns The bridge fees for the given amount and token symbol and the UseQueryResult object.
  */
 export function useBridgeFees(

src/utils/bridge.ts

@@ -46,13 +46,26 @@ export type GetBridgeFeesResult = BridgeFees & {
 };
 
 /**
+ * Retrieves the bridge fees for a given token bridging operation.
  *
- * @param amount - amount to bridge
- * @param inputTokenSymbol - symbol of the input token to bridge
- * @param outputTokenSymbol - symbol of the output token to bridge
- * @param fromChain The origin chain of this bridge action
- * @param toChain The destination chain of this bridge action
- * @returns Returns the `relayerFee` and `lpFee` fees for bridging the given amount of tokens, along with an `isAmountTooLow` flag indicating whether the amount is too low to bridge and an `isLiquidityInsufficient` flag indicating whether the liquidity is insufficient.
+ * @param amount - The amount of tokens to be bridged.
+ * @param inputTokenSymbol - The symbol of the input token to be bridged.
+ * @param outputTokenSymbol - The symbol of the output token to be received after bridging.
+ * @param fromChainId - The ID of the origin chain for the bridge operation.
+ * @param toChainId - The ID of the destination chain for the bridge operation.
+ * @param recipientAddress - The address of the recipient who will receive the bridged tokens.
+ * @returns An object containing the following properties:
+ *   - `totalRelayFee`: The total relay fee for the bridge operation.
+ *   - `relayerGasFee`: The gas fee paid to the relayer.
+ *   - `relayerCapitalFee`: The capital fee paid to the relayer.
+ *   - `lpFee`: The fee paid to the liquidity provider.
+ *   - `isAmountTooLow`: A boolean indicating whether the provided amount is too low to bridge.
+ *   - `quoteTimestamp`: The timestamp of the bridge fee quote.
+ *   - `quoteTimestampInMs`: The quote timestamp in milliseconds.
+ *   - `quoteBlock`: The block number of the bridge fee quote.
+ *   - `quoteLatency`: The latency of the bridge fee quote request in milliseconds.
+ *   - `limits`: An object containing the minimum and maximum bridge limits.
+ *   - `estimatedFillTimeSec`: The estimated time in seconds for the bridge operation to be filled.
  */
 export async function getBridgeFees({
   amount,
@@ -154,10 +167,14 @@ type NetworkMismatchHandler = (
 ) => void;
 
 /**
- * Makes a deposit on Across using the `SpokePoolVerifiers` contract's `deposit` function if possible.
- * @param signer A valid signer, must be connected to a provider.
+ * Makes a deposit on the Across protocol using the `SpokePoolVerifiers` contract's `deposit` function, if possible.
+ *
+ * @param signer - A valid Ethereum signer, which must be connected to a provider.
+ * @param spokePool - The `SpokePool` contract instance used for the deposit operation.
+ * @param spokePoolVerifier - The `SpokePoolVerifier` contract instance used for the deposit operation.
+ * @param onNetworkMismatch - An optional callback function that will be called if the signer's network does not match the from/to chain IDs.
  * @param depositArgs - An object containing the {@link AcrossDepositArgs arguments} to pass to the deposit function of the bridge contract.
- * @returns The transaction response obtained after sending the transaction.
+ * @returns The transaction response obtained after sending the deposit transaction.
  */
 export async function sendSpokePoolVerifierDepositTx(
   signer: ethers.Signer,

src/utils/format.ts

@@ -273,7 +273,9 @@ export function formatWeiPct(wei?: ethers.BigNumberish, precision: number = 3) {
 
 /**
  * Formats a number into a human readable format
- * @param num The number to format
+ *
+ * @param num - The number to be formatted.
+ * @param decimals - The number of decimal places to display. Default is 0.
  * @returns A human readable format. I.e. 1000 -> 1K, 1001 -> 1K+
  */
 export function humanReadableNumber(num: number, decimals = 0): string {

src/utils/notify.ts

@@ -48,11 +48,15 @@ export const notificationEmitter = async (
 
 /**
  * Calls and waits on the Notify API to resolve the status of a TX if the chain is supported by Onboard
+ *
+ * @param requiredChainId The ID of the chain that the transaction was executed on.
  * @param tx The transaction to wait for
  * @param notify The BNC Notify API that is used to handle the UI visualization
  * @param timingBuffer An optional waiting time in milliseconds to wait to resolve this promise on a successful tx confirmation in Notify (Default: 5000ms)
  * @param ignoreErrors An optional parameter to ignore tx failure and return successful
- **/
+ *
+ * @throws {Error} If the transaction fails and `ignoreErrors` is set to `false`.
+ */
 export const waitOnTransaction = async (
   requiredChainId: number,
   tx: ContractTransaction,

src/utils/staking-pool.ts

@@ -74,6 +74,8 @@ export type PoolQueryData = {
  * Calls on-chain data & the Vercel API to resolve information about the AcceleratingDistributor Contract
  * @param tokenAddress The address of the ERC-20 token on the current chain
  * @param account A user address to query against the on-chain data
+ * @param acxPriceInUSD The current price of the ACX token in US dollars
+ * @returns The staking pool information, or `undefined` if the required data is not available.
  */
 export async function fetchStakingPool(
   tokenAddress?: string,

src/utils/transactions.ts

@@ -8,7 +8,7 @@ import { parseUnits } from "./format";
 
 /**
  * This function takes a raw transaction and a signer and returns the result of signing the transaction.
- * @param tx The raw transaction to sign.
+ * @param rawTx The raw transaction to sign.
  * @param signer A signer used to sign the transaction
  * @returns The raw transaction signed by the given `signer`.
  */
@@ -55,6 +55,7 @@ export async function getPaddedGasEstimation(
  * Pads the gas estimation by a fixed amount dictated in the `REACT_SEND_TXN_GAS_ESTIMATION_MULTIPLIER` env var
  * @param contract The contract that this transaction will originate from
  * @param method The specific call method
+ * @param chainId The chain ID to use for the gas estimation.
  * @returns A completed or failed transaction
  */
 export function sendWithPaddedGas(

src/utils/weiMath.ts

@@ -11,7 +11,7 @@ export function toWeiSafe(
   numberToConvertToWei: string,
   desiredPrecision = DEFAULT_PRECISION
 ) {
-  // Try converting just the raw string first to avoid unneccessary stripping of precision.
+  // Try converting just the raw string first to avoid unnecessary stripping of precision.
   try {
     return toWei(numberToConvertToWei, desiredPrecision);
   } catch (err) {