feat: improve documentation of chain utils methods (#45)

* improve documentation of add chain * improve documentation of switch chain * update unclear documentation of switchChain
VGLoic · Aug 17, 2023 · e435991 · e435991
1 parent 6e6b9a0
commit e435991
Show file tree

Hide file tree

Showing 3 changed files with 35 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -99,14 +99,14 @@ function WrongNetwork() {
   const { addChain } = useMetaMask();
   const gnosisChainNetworkParams = {
     chainId: "0x64",
-    chainName: "Gnosis Chain",
-    rpcUrls: ["https://rpc.gnosischain.com/"],
+    chainName: "Gnosis",
     nativeCurrency: {
-      name: "xDAI",
-      symbol: "xDAI",
-      decimals: 18,
+        name: "xDai",
+        symbol: "XDAI",
+        decimals: 18,
     },
-    blockExplorerUrls: ["https://blockscout.com/xdai/mainnet/"]
+    rpcUrls: ["https://rpc.gnosischain.com/"],
+    blockExplorerUrls: ["https://gnosisscan.io/"],
   };
   // Request to add Gnosis chain and then switch to it
   return (

diff --git a/src/__tests__/index.test.tsx b/src/__tests__/index.test.tsx
@@ -6,18 +6,16 @@ import { useMetaMask, MetaMaskProvider } from "../";
 describe("MetaMask provider", () => {
   const addChainPrams = {
     chainId: "0x64",
-    chainName: "xDAI Chain",
-    rpcUrls: ["https://dai.poa.network"],
-    iconUrls: [
-      "https://xdaichain.com/fake/example/url/xdai.svg",
-      "https://xdaichain.com/fake/example/url/xdai.png",
-    ],
+    chainName: "Gnosis",
     nativeCurrency: {
-      name: "xDAI",
-      symbol: "xDAI",
+      name: "xDai",
+      symbol: "XDAI",
       decimals: 18,
     },
+    rpcUrls: ["https://rpc.gnosischain.com/"],
+    blockExplorerUrls: ["https://gnosisscan.io/"],
   };
+
   const address = "0x19F7Fa0a30d5829acBD9B35bA2253a759a37EfC5";
 
   describe("when MetaMask is not available", () => {

diff --git a/src/metamask-context.ts b/src/metamask-context.ts
@@ -57,16 +57,36 @@ export type IMetaMaskContext = MetaMaskState & {
    */
   connect: () => Promise<string[] | null>;
   /**
-   * Request addition of a new network
-   * @param parameters New chain parameters, see [EIP-3085](https://eips.ethereum.org/EIPS/eip-3085) for full description
+   * Request addition of a new chain to MetaMask
+   * @dev See [MetaMask API](https://docs.metamask.io/wallet/reference/rpc-api/#wallet_addethereumchain) or [EIP-3085](https://eips.ethereum.org/EIPS/eip-3085) for full description
+   * @param parameters The chain parameters
+   * @example ```ts
+   * const { addChain } = useMetaMask();
+   * const GNOSIS_MAINNET_PARAMS = {
+   *  chainId: "0x64",
+   *  chainName: "Gnosis",
+   *  nativeCurrency: {
+   *    name: "xDai",
+   *    symbol: "XDAI",
+   *    decimals: 18,
+   *  },
+   *  rpcUrls: ["https://rpc.gnosischain.com/"],
+   *  blockExplorerUrls: ["https://gnosisscan.io/"],
+   * }
+   * // Add Gnosis chain to MetaMask
+   * const onClick = () => addChain(GNOSIS_MAINNET_PARAMS);
+   * ```
    */
   addChain: (parameters: AddEthereumChainParameter) => Promise<void>;
   /**
    * Request a switch of network
+   * @dev See [MetaMask API](https://docs.metamask.io/wallet/reference/rpc-api/#wallet_switchethereumchain) or [EIP-3326](https://ethereum-magicians.org/t/eip-3326-wallet-switchethereumchain/5471) for full description
+   * @dev An error with code `4902` will be thrown if the chain has not been added to MetaMask. In this case, one would need to use the `addChain` method in order to add the chain to MetaMask and switch to it.
    * @param chainId Chain ID of the network in hexadecimal
    * @example ```ts
+   * const { addChain } = useMetaMask();
    * // Switch chain to Ethereum Mainnet
-   * await context.switchChain("0x1");
+   * const onClick = () => switchChain("0x1");
    * ```
    */
   switchChain: (chainId: string) => Promise<void>;