doc: Make the docs more robust with examples (#2226)

* doc: Make the docs more robust with examples

packages/xrpl/package.json

@@ -60,7 +60,7 @@
     "watch": "run-s build:lib --watch",
     "clean": "rm -rf dist build coverage",
     "docgen": "tsc --build tsconfig.docs.json && typedoc && echo js.xrpl.org >> ../../docs/CNAME",
-    "prepublish": "run-s clean build",
+    "prepublish": "npx run-s clean build",
     "test": "jest --verbose false --silent=false ./test/**/*.test.ts --testPathIgnorePatterns=./test/integration --testPathIgnorePatterns=./test/fixtures",
     "test:integration": "TS_NODE_PROJECT=tsconfig.build.json jest --verbose false --silent=false --runInBand ./test/integration/**/*.test.ts",
     "test:browser": "npm run build && npm run build:browserTests && karma start ./karma.config.js --single-run",

packages/xrpl/src/Wallet/fundWallet.ts

@@ -20,15 +20,49 @@ const INTERVAL_SECONDS = 1
 const MAX_ATTEMPTS = 20
 
 /**
- * Generates a random wallet with some amount of XRP (usually 1000 XRP).
+ * The fundWallet() method is used to send an amount of XRP (usually 1000) to a new (randomly generated)
+ * or existing XRP Ledger wallet.
  *
  * @example
- * ```typescript
+ *
+ * Example 1: Fund a randomly generated wallet
+ * const { Client, Wallet } = require('xrpl')
+ *
+ * const client = new Client('wss://s.altnet.rippletest.net:51233')
+ * await client.connect()
+ * const { balance, wallet } = await client.fundWallet()
+ *
+ * Under the hood, this will use `Wallet.generate()` to create a new random wallet, then ask a testnet faucet
+ * To send it XRP on ledger to make it a real account. If successful, this will return the new account balance in XRP
+ * Along with the Wallet object to track the keys for that account. If you'd like, you can also re-fill an existing
+ * Account by passing in a Wallet you already have.
+ * ```ts
  * const api = new xrpl.Client("wss://s.altnet.rippletest.net:51233")
  * await api.connect()
  * const { wallet, balance } = await api.fundWallet()
  * ```
  *
+ * Example 2: Fund wallet using a custom faucet host and known wallet address
+ *
+ * `fundWallet` will try to infer the url of a faucet API from the network your client is connected to.
+ * There are hardcoded default faucets for popular test networks like testnet and devnet.
+ * However, if you're working with a newer or more obscure network, you may have to specify the faucetHost
+ * And faucetPath so `fundWallet` can ask that faucet to fund your wallet.
+ *
+ * ```ts
+ * const newWallet = Wallet.generate()
+ * const { balance, wallet  } = await client.fundWallet(newWallet, {
+ *       amount: '10',
+ *       faucetHost: 'https://custom-faucet.example.com',
+ *       faucetPath: '/accounts'
+ *     })
+ *     console.log(`Sent 10 XRP to wallet: ${address} from the given faucet. Resulting balance: ${balance} XRP`)
+ *   } catch (error) {
+ *     console.error(`Failed to fund wallet: ${error}`)
+ *   }
+ * }
+ * ```
+ *
  * @param this - Client.
  * @param wallet - An existing XRPL Wallet to fund. If undefined or null, a new Wallet will be created.
  * @param options - See below.

packages/xrpl/src/Wallet/index.ts

@@ -117,7 +117,15 @@ class Wallet {
   }
 
   /**
-   * Generates a new Wallet using a generated seed.
+   * `generate()` creates a new random Wallet. In order to make this a valid account on ledger, you must
+   * Send XRP to it. On test networks that can be done with "faucets" which send XRP to any account which asks
+   * For it. You can call `client.fundWallet()` in order to generate credentials and fund the account on test networks.
+   *
+   * @example
+   * ```ts
+   * const { Wallet } = require('xrpl')
+   * const wallet = Wallet.generate()
+   * ```
    *
    * @param algorithm - The digital signature algorithm to generate an address for.
    * @returns A new Wallet derived from a generated seed.
@@ -296,6 +304,53 @@ class Wallet {
   /**
    * Signs a transaction offline.
    *
+   * @example
+   *
+   * ```ts
+   * const { Client, Wallet } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   *
+   * async function signTransaction() {
+   *   await client.connect()
+   *   const { balance: balance1, wallet: wallet1 } = client.fundWallet()
+   *   const { balance: balance2, wallet: wallet2 } = client.fundWallet()
+   *
+   *   const transaction = {
+   *     TransactionType: 'Payment',
+   *     Account: wallet1.address,
+   *     Destination: wallet2.address,
+   *     Amount: '10'
+   *   }
+   *
+   *   try {
+   *     await client.autofill(transaction)
+   *     const { tx_blob: signed_tx_blob, hash} = await wallet1.sign(transaction)
+   *     console.log(signed_tx_blob)
+   *   } catch (error) {
+   *     console.error(`Failed to sign transaction: ${error}`)
+   *   }
+   *   const result = await client.submit(signed_tx_blob)
+   *   await client.disconnect()
+   * }
+   *
+   * signTransaction()
+   * ```
+   * In order for a transaction to be validated, it must be signed by the account sending the transaction to prove
+   * That the owner is actually the one deciding to take that action.
+   *
+   * In this example, we created, signed, and then submitted a transaction to testnet. You may notice that the
+   * Output of `sign` includes a `tx_blob` and a `hash`, both of which are needed to submit & verify the results.
+   * Note: If you pass a `Wallet` to `client.submit` or `client.submitAndWait` it will do signing like this under the hood.
+   *
+   * `tx_blob` is a binary representation of a transaction on the XRP Ledger. It's essentially a byte array
+   * that encodes all of the data necessary to execute the transaction, including the source address, the destination
+   * address, the amount, and any additional fields required for the specific transaction type.
+   *
+   * `hash` is a unique identifier that's generated from the signed transaction data on the XRP Ledger. It's essentially
+   * A cryptographic digest of the signed transaction blob, created using a hash function. The signed transaction hash is
+   * Useful for identifying and tracking specific transactions on the XRP Ledger. It can be used to query transaction
+   * Information, verify the authenticity of a transaction, and detect any tampering with the transaction data.
+   *
    * @param this - Wallet instance.
    * @param transaction - A transaction to be signed offline.
    * @param multisign - Specify true/false to use multisign or actual address (classic/x-address) to make multisign tx request.

packages/xrpl/src/client/index.ts

@@ -564,6 +564,19 @@ class Client extends EventEmitter {
   /**
    * Tells the Client instance to connect to its rippled server.
    *
+   * @example
+   *
+   * Client.connect() establishes a connection between a Client object and the server.
+   *
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * // do something with the client
+   * await client.disconnect()
+   * ```
+   * If you open a client connection, be sure to close it with `await client.disconnect()`
+   * before exiting your application.
    * @returns A promise that resolves with a void value when a connection is established.
    * @category Network
    */
@@ -572,7 +585,21 @@ class Client extends EventEmitter {
   }
 
   /**
-   * Tells the Client instance to disconnect from it's rippled server.
+   * Disconnects the XRPL client from the server and cancels all pending requests and subscriptions. Call when
+   * you want to disconnect the client from the server, such as when you're finished using the client or when you
+   * need to switch to a different server.
+   *
+   * @example
+   *
+   * To use the disconnect() method, you first need to create a new Client object and connect it to a server:
+   *
+   * ```ts
+   * const { Client } = require('xrpl')
+   * const client = new Client('wss://s.altnet.rippletest.net:51233')
+   * await client.connect()
+   * // do something with the client
+   * await client.disconnect()
+   * ```
    *
    * @returns A promise that resolves with a void value when a connection is destroyed.
    * @category Network

packages/xrpl/src/sugar/autofill.ts

@@ -23,6 +23,37 @@ interface ClassicAccountAndTag {
  * is connected to. It also converts all X-Addresses to classic addresses and
  * flags interfaces into numbers.
  *
+ * @example
+ *
+ * ```ts
+ * const { Client } = require('xrpl')
+ *
+ * const client = new Client('wss://s.altnet.rippletest.net:51233')
+ *
+ * async function createAndAutofillTransaction() {
+ *   const transaction = {
+ *     TransactionType: 'Payment',
+ *     Account: 'rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh',
+ *     Destination: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59',
+ *     Amount: '10000000' // 10 XRP in drops (1/1,000,000th of an XRP)
+ *   }
+ *
+ *   try {
+ *     const autofilledTransaction = await client.autofill(transaction)
+ *     console.log(autofilledTransaction)
+ *   } catch (error) {
+ *     console.error(`Failed to autofill transaction: ${error}`)
+ *   }
+ * }
+ *
+ * createAndAutofillTransaction()
+ * ```
+ *
+ * Autofill helps fill in fields which should be included in a transaction, but can be determined automatically
+ * such as `LastLedgerSequence` and `Fee`. If you override one of the fields `autofill` changes, your explicit
+ * values will be used instead. By default, this is done as part of `submit` and `submitAndWait` when you pass
+ * in an unsigned transaction along with your wallet to be submitted.
+ *
  * @param this - A client.
  * @param transaction - A {@link Transaction} in JSON format
  * @param signersCount - The expected number of signers for this transaction.

packages/xrpl/src/sugar/submit.ts

@@ -52,12 +52,55 @@ async function submit(
  * validated ledger (or has errored/will not be included for some reason).
  * See [Reliable Transaction Submission](https://xrpl.org/reliable-transaction-submission.html).
  *
+ * @example
+ *
+ * ```ts
+ * const { Client, Wallet } = require('xrpl')
+ * const client = new Client('wss://s.altnet.rippletest.net:51233')
+ *
+ * async function submitTransaction() {
+ *   const senderWallet = client.fundWallet()
+ *   const recipientWallet = client.fundWallet()
+ *
+ *   const transaction = {
+ *     TransactionType: 'Payment',
+ *     Account: senderWallet.address,
+ *     Destination: recipientWallet.address,
+ *     Amount: '10'
+ *   }
+ *
+ *   try {
+ *     await client.submit(signedTransaction, { wallet: senderWallet })
+ *     console.log(result)
+ *   } catch (error) {
+ *     console.error(`Failed to submit transaction: ${error}`)
+ *   }
+ * }
+ *
+ * submitTransaction()
+ * ```
+ *
+ * In this example we submit a payment transaction between two newly created testnet accounts.
+ *
+ * Under the hood, `submit` will call `client.autofill` by default, and because we've passed in a `Wallet` it
+ * Will also sign the transaction for us before submitting the signed transaction binary blob to the ledger.
+ *
+ * This is similar to `submitAndWait` which does all of the above, but also waits to see if the transaction has been validated.
  * @param this - A Client.
  * @param transaction - A transaction to autofill, sign & encode, and submit.
  * @param opts - (Optional) Options used to sign and submit a transaction.
  * @param opts.autofill - If true, autofill a transaction.
  * @param opts.failHard - If true, and the transaction fails locally, do not retry or relay the transaction to other servers.
  * @param opts.wallet - A wallet to sign a transaction. It must be provided when submitting an unsigned transaction.
+ * @throws Connection errors: If the `Client` object is unable to establish a connection to the specified WebSocket endpoint,
+ * an error will be thrown.
+ * @throws Transaction errors: If the submitted transaction is invalid or cannot be included in a validated ledger for any
+ * reason, the promise returned by `submitAndWait()` will be rejected with an error. This could include issues with insufficient
+ * balance, invalid transaction fields, or other issues specific to the transaction being submitted.
+ * @throws Ledger errors: If the ledger being used to submit the transaction is undergoing maintenance or otherwise unavailable,
+ * an error will be thrown.
+ * @throws Timeout errors: If the transaction takes longer than the specified timeout period to be included in a validated
+ * ledger, the promise returned by `submitAndWait()` will be rejected with an error.
  * @returns A promise that contains TxResponse, that will return when the transaction has been validated.
  */
 async function submitAndWait(