[react, react-core] - Migrate Docs content to JSDoc comments (#2084)

Author: MananTank

.changeset/bright-impalas-remain.md

@@ -0,0 +1,11 @@
+---
+"@thirdweb-dev/react-native": patch
+"@thirdweb-dev/react-core": patch
+"@thirdweb-dev/storage": patch
+"@thirdweb-dev/wallets": patch
+"@thirdweb-dev/chains": patch
+"@thirdweb-dev/react": patch
+"@thirdweb-dev/sdk": patch
+---
+
+JSDoc comments Improvements

packages/chains/src/async.ts

@@ -83,7 +83,7 @@ export async function fetchChains(options?: {
 /**
  *
  * @param chainId - the chainId of the chain to resolve
- * @returns a Promise that resolves to the Chain object
+ * @returns A Promise that resolves to the Chain object
  * @throws if the chainId is not found
  */
 export async function getChainByChainIdAsync(chainId: number): Promise<Chain> {
@@ -98,7 +98,7 @@ export async function getChainByChainIdAsync(chainId: number): Promise<Chain> {
 /**
  *
  * @param slug - the slug of the chain to resolve
- * @returns a Promise that resolves to the Chain object
+ * @returns A Promise that resolves to the Chain object
  * @throws if the slug is not found
  */
 export async function getChainBySlugAsync(slug: string): Promise<Chain> {

packages/react-core/src/core/hooks/useNetwork.ts

@@ -35,23 +35,120 @@ type NetworkMetadata = {
  * It's important to note that some wallet apps do not support programmatic network switching and switchNetwork will be undefined.
  * For those situations, you can typically switch networks in the wallet app this hook will still work.
  *
+ * Hook for getting information about the current network and switching to a different network.
+ *
+ * Returns an array value containing two elements.
+ *
+ * 1. An object containing the following properties:
+ *
+ *    - `data` object contains information about the wallet's current and supported networks.
+ *    - `loading` indicates if the switch network request is in progress.
+ *    - `error` holds the `Error` object if there was an error when attempting to switch network.
+ *
+ * 2. A function to switch to a different network.
+ *
  * @example
  * ```javascript
  * import { useNetwork } from "@thirdweb-dev/react";
  *
- * const App = () => {
- *   const [, switchNetwork] = useNetwork();
+ * function App() {
+ *   const [{ data, error, loading }, switchNetwork] = useNetwork();
+ *
  *   return (
- *      // switchNetwork is undefined if the wallet does not support programmatic network switching
- *      // 137 is the chainId for Polygon in this example
- *     <button onClick={() => switchNetwork(137)}>
- *        Switch Network
+ *     <button
+ *       onClick={async () => {
+ *         if (!switchNetwork) {
+ *           console.log("can not switch network");
+ *           return;
+ *         }
+ *
+ *         const result = await switchNetwork(80001);
+ *         if (result.data) {
+ *           console.log("Switched to Mumbai testnet successfully");
+ *         } else {
+ *           console.log("Error switching to Mumbai testnet", result.error);
+ *         }
+ *       }}
+ *     >
+ *       Switch to Mumbai
  *     </button>
  *   );
- * };
+ * }
+ * ```
+ *
+ * @returns
+ *
+ * ```ts
+ * const [{ data, error, loading }, switchNetwork] = useNetwork();
+ * ```
+ * #### data
+ *
+ * If wallet is connected to a network that is one of `supportedChains` provided in `ThirdwebProvider` or one of the default supported chains, `data` object will contain the following:
+ *
+ * ```ts
+ * {
+ *   chain: Chain; // The connected network
+ *   chains: Chain[]; // All supported networks
+ * }
+ * ```
+ *
+ * If wallet is connected to a network that is NOT one of `supportedChains` provided in `ThirdwebProvider` or default supported, `data` object will contain the following:
+ *
+ * ```ts
+ * {
+ *   // chainId of current connected network + unsupported flag
+ *   chain: { chainId: number, unsupported: true };
+ *   // All supported networks
+ *   chains: Chain[];
+ * }
+ * ```
+ *
+ * If wallet is not connected, `data` object will contain the following:
+ *
+ * ```ts
+ * {
+ *   chain: undefined;
+ *   chains: []; // Empty array
+ * }
+ * ```
+ *
+ * #### error
+ *
+ * `error` contains an `Error` object if there was an error when attempting to switch network using the `switchNetwork` function
+ *
+ * `undefined` if there is no switch network error
+ *
+ * ```ts
+ * Error | undefined;
+ * ```
+ *
+ * #### loading
+ *
+ * `loading` is `true` when switching network using the `switchNetwork` function, and `false` otherwise.
+ *
+ *
+ * #### switchNetwork
+ *
+ * `switchNetwork` is a function to switch to a different network. It takes a `chainId` as an argument and returns a promise that resolves to an object containing `data` and `error` properties.
+ *
+ * If switching network was successful, `data` will contain the new network information. and `error` will be `undefined`. If switching network failed, `data` will be `undefined` and `error` will contain an `Error` object.
+ *
+ * `switchNetwork` is `undefined` if not connected to a wallet or if the connected wallet does not allow programmatic switching.
+ *
+ * ```ts
+ * type SwitchNetwork = undefined | (chainId: number) => Promise<
+ *   | {
+ *       data: Chain | undefined;
+ *       error: undefined;
+ *     }
+ *   | {
+ *       data: undefined;
+ *       error: Error;
+ *     }>
  * ```
  *
- * @deprecated - use `useChain`, `useSwitchChain`, `useChainId` instead
+ * @deprecated use `useChain`, `useSwitchChain`, `useChainId` instead
+ * @internal
  */
 export function useNetwork(): [NetworkMetadata, SwitchNetwork | undefined] {
   const chain = useChain();