docs: clean up documentation for Client (#1749)

* update phrasing

* account -> address

src/sugar/autofill.ts

@@ -18,12 +18,16 @@ interface ClassicAccountAndTag {
 }
 
 /**
- * Autofills fields in a transaction.
+ * Autofills fields in a transaction. This will set `Sequence`, `Fee`,
+ * `lastLedgerSequence` according to the current state of the server this Client
+ * is connected to. It also converts all X-Addresses to classic addresses and
+ * flags interfaces into numbers.
  *
  * @param this - A client.
- * @param transaction - A transaction to autofill fields.
- * @param signersCount - The expected number of signers for this transaction. Used for multisign.
- * @returns An autofilled transaction.
+ * @param transaction - A {@link Transaction} in JSON format
+ * @param signersCount - The expected number of signers for this transaction.
+ * Only used for multisigned transactions.
+ * @returns The autofilled transaction.
  */
 async function autofill<T extends Transaction>(
   this: Client,

src/sugar/balances.ts

@@ -35,19 +35,31 @@ interface GetBalancesOptions {
 /**
  * Get the XRP balance for an account.
  *
+ * @example
+ * ```ts
+ * const client = new Client(wss://s.altnet.rippletest.net:51233)
+ * const balance = await client.getXrpBalance('rG1QQv2nh2gr7RCZ1P8YYcBUKCCN633jCn')
+ * console.log(balance)
+ * /// '200'
+ * ```
+ *
  * @param this - Client.
- * @param account - Account address.
+ * @param address - Address of the account to retrieve XRP balance.
  * @param options - Options to include for getting the XRP balance.
+ * @param options.ledger_index - Retrieve the account balances at a given
+ * ledger_index.
+ * @param options.ledger_hash - Retrieve the account balances at the ledger with
+ * a given ledger_hash.
  * @returns The XRP balance of the account (as a string).
  */
 async function getXrpBalance(
   this: Client,
-  account: string,
+  address: string,
   options: GetXrpBalanceOptions = {},
 ): Promise<string> {
   const xrpRequest: AccountInfoRequest = {
     command: 'account_info',
-    account,
+    account: address,
     ledger_index: options.ledger_index ?? 'validated',
     ledger_hash: options.ledger_hash,
   }
@@ -59,9 +71,9 @@ async function getXrpBalance(
  * Get XRP/non-XRP balances for an account.
  *
  * @param this - Client.
- * @param account - Account address.
- * @param options - Allows the user to to look up balance in a ledger with given
- * ledger_index or ledger_hash, filter by peer, and limit number of balances.
+ * @param address - Address of the account to retrieve balances for.
+ * @param options - Allows the client to specify a ledger_hash, ledger_index,
+ * filter by peer, and/or limit number of balances.
  * @param options.ledger_index - Retrieve the account balances at a given
  * ledger_index.
  * @param options.ledger_hash - Retrieve the account balances at the ledger with
@@ -72,7 +84,7 @@ async function getXrpBalance(
  */
 async function getBalances(
   this: Client,
-  account: string,
+  address: string,
   options: GetBalancesOptions = {},
 ): Promise<Balance[]> {
   const balances: Balance[] = []
@@ -80,7 +92,7 @@ async function getBalances(
   // get XRP balance
   let xrpPromise: Promise<string> = Promise.resolve('')
   if (!options.peer) {
-    xrpPromise = this.getXrpBalance(account, {
+    xrpPromise = this.getXrpBalance(address, {
       ledger_hash: options.ledger_hash,
       ledger_index: options.ledger_index,
     })
@@ -89,7 +101,7 @@ async function getBalances(
   // get non-XRP balances
   const linesRequest: AccountLinesRequest = {
     command: 'account_lines',
-    account,
+    account: address,
     ledger_index: options.ledger_index ?? 'validated',
     ledger_hash: options.ledger_hash,
     peer: options.peer,

src/sugar/ledgerIndex.ts

@@ -4,7 +4,7 @@ import type { Client } from '..'
  * Returns the index of the most recently validated ledger.
  *
  * @param this - The Client used to connect to the ledger.
- * @returns The ledger index.
+ * @returns The most recently validated ledger index.
  */
 export default async function getLedgerIndex(this: Client): Promise<number> {
   const ledgerResponse = await this.request({

src/sugar/orderbook.ts

@@ -38,12 +38,21 @@ interface OrderbookOptions {
  * Fetch orderbook (buy/sell orders) between two accounts.
  *
  * @param this - Client.
- * @param takerPays - Specs of the currency account taking the offer pays.
- * @param takerGets - Specs of the currency account taking the offer receives.
- * @param options - Options to include for getting orderbook between payer and receiver.
+ * @param takerPays - Specification of which currency the account taking the
+ * offer would pay, as an object with `currency` and `issuer` fields.
+ * @param takerGets - Specification of which currency the account taking the
+ * offer would receive, as an object with `currency` and `issuer` fields.
+ * @param options - Options allowing the client to specify ledger_index,
+ * ledger_hash, filter by taker, and/or limit number of orders.
+ * @param options.ledger_index - Retrieve the orderbook at a given ledger_index.
+ * @param options.ledger_hash - Retrieve the orderbook at the ledger with a
+ * given ledger_hash.
+ * @param options.taker - Filter orders by taker.
+ * @param options.limit - Limit number of order books to fetch for each side of
+ * the order book. Defaults to 20.
  * @returns An object containing buy and sell objects.
  */
-// eslint-disable-next-line max-params -- Function needs 4 params.
+// eslint-disable-next-line max-params -- Once bound to Client, getOrderbook only has 3 parameters.
 async function getOrderbook(
   this: Client,
   takerPays: TakerAmount,