docs: tsdoc - public actions (wevm#347)

* docs: tsdoc

* wip: public actions

* build: strip comments from source

* wip: public actions

* docs: finish public actions

* docs: finish tsdoc for public actions

* build: split esm and types

.gitignore

@@ -8,7 +8,7 @@ cache
 coverage
 dist
 node_modules
-tsconfig.tsbuildinfo
+tsconfig*.tsbuildinfo
 
 # local env files
 .env

package.json

@@ -6,9 +6,10 @@
     "anvil": "dotenv -- sh -c 'anvil --fork-url $VITE_ANVIL_FORK_URL --fork-block-number $VITE_ANVIL_BLOCK_NUMBER --block-time $VITE_ANVIL_BLOCK_TIME'",
     "bench": "vitest bench --no-threads",
     "bench:ci": "CI=true vitest bench --no-threads",
-    "build": "pnpm run clean && pnpm run build:cjs && pnpm run build:esm+types && size-limit",
-    "build:cjs": "tsc --project tsconfig.build.json --module commonjs --outDir ./dist/cjs && echo > ./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
-    "build:esm+types": "tsc --project tsconfig.build.json --module es2015 --verbatimModuleSyntax --outDir ./dist/esm --declaration --declarationMap --declarationDir ./dist/types && echo > ./dist/esm/package.json '{\"type\":\"module\"}'",
+    "build": "pnpm run clean && pnpm run build:cjs && pnpm run build:esm && pnpm run build:types && size-limit",
+    "build:cjs": "tsc --project tsconfig.build.json --module commonjs --outDir ./dist/cjs --removeComments && echo > ./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
+    "build:esm": "tsc --project tsconfig.build.json --module es2015 --outDir ./dist/esm --removeComments --verbatimModuleSyntax && echo > ./dist/esm/package.json '{\"type\":\"module\"}'",
+    "build:types": "tsc --project tsconfig.build.json --module esnext --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap --verbatimModuleSyntax",
     "changeset": "changeset",
     "changeset:release": "pnpm build && changeset publish",
     "changeset:version": "changeset version && pnpm install --lockfile-only && pnpm bun scripts/updateVersion.ts",

site/docs/actions/public/createEventFilter.md

@@ -258,4 +258,4 @@ const filter = await publicClient.createEventFilter({
 
 ## JSON-RPC Methods
 
-[`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newFilter)
+[`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter)

site/docs/actions/public/getTransactionCount.md

@@ -23,7 +23,7 @@ Returns the number of [Transactions](/docs/glossary/terms#transaction) an Accoun
 ```ts [example.ts]
 import { publicClient } from './client'
 
-const block = await publicClient.getTransactionCount({  // [!code focus:99]
+const transactionCount = await publicClient.getTransactionCount({  // [!code focus:99]
   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
 })
 // 420
@@ -56,7 +56,7 @@ The number of transactions an account has sent.
 The address of the account.
 
 ```ts
-const balance = await publicClient.getTransactionCount({
+const transactionCount = await publicClient.getTransactionCount({
   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e', // [!code focus]
 })
 ```
@@ -68,7 +68,7 @@ const balance = await publicClient.getTransactionCount({
 Get the count at a block number.
 
 ```ts
-const balance = await publicClient.getTransactionCount({
+const transactionCount = await publicClient.getTransactionCount({
   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
   blockNumber: 69420n  // [!code focus]
 })
@@ -81,7 +81,7 @@ const balance = await publicClient.getTransactionCount({
 Get the count at a block tag.
 
 ```ts
-const balance = await publicClient.getTransactionCount({
+const transactionCount = await publicClient.getTransactionCount({
   address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
   blockTag: 'safe'  // [!code focus]
 })

site/docs/actions/public/uninstallFilter.md

@@ -14,7 +14,7 @@ head:
 
 # uninstallFilter
 
-Destroys a Filter that was created from one of the following Actions:
+Destroys a [`Filter`](/docs/glossary/types.html#filter) that was created from one of the following Actions:
 
 - [`createBlockFilter`](/docs/actions/public/createBlockFilter)
 - [`createEventFilter`](/docs/actions/public/createEventFilter)

site/docs/actions/public/waitForTransactionReceipt.md

@@ -16,7 +16,7 @@ head:
 
 Waits for the [Transaction](/docs/glossary/terms#transaction) to be included on a [Block](/docs/glossary/terms#block) (one confirmation), and then returns the [Transaction Receipt](/docs/glossary/terms#transaction-receipt). If the Transaction reverts, then the action will throw an error.
 
-The `waitForTransactionReceipt` action additionally supports Replacement detection (ie. sped up Transactions).
+The `waitForTransactionReceipt` action additionally supports Replacement detection (e.g. sped up Transactions).
 
 ## Usage
 

site/docs/actions/public/watchEvent.md

@@ -18,7 +18,7 @@ Watches and returns emitted [Event Logs](/docs/glossary/terms#event-log).
 
 This Action will batch up all the Event Logs found within the [`pollingInterval`](#pollinginterval-optional), and invoke them via [`onLogs`](#onLogs).
 
-`watchEvent` will attempt to create an [Event Filter](/docs/actions/public/watchEvent) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (ie. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](/docs/actions/public/getLogs) instead.
+`watchEvent` will attempt to create an [Event Filter](https://viem.sh/docs/actions/public/createEventFilter.html) and listen to changes to the Filter per polling interval, however, if the RPC Provider does not support Filters (ie. `eth_newFilter`), then `watchEvent` will fall back to using [`getLogs`](/docs/actions/public/getLogs) instead.
 
 ## Usage
 

site/docs/contract/deployContract.md

@@ -24,7 +24,7 @@ Deploys a contract to the network, given bytecode & constructor arguments.
 import { wagmiAbi } from './abi'
 import { account, walletClient } from './config'
 
-await walletClient.deployContract({
+const hash = await walletClient.deployContract({
   abi,
   account,
   bytecode: '0x608060405260405161083e38038061083e833981016040819052610...',
@@ -70,7 +70,7 @@ import { deployContract } from 'viem'
 import { wagmiAbi } from './abi'
 import { account, walletClient } from './config'
 
-await walletClient.deployContract({
+const hash = await walletClient.deployContract({
   abi,
   account,
   args: [69420],
@@ -108,6 +108,12 @@ export const account = privateKeyToAccount(...)
 
 :::
 
+## Returns
+
+[`Hash`](/docs/glossary/types#hash)
+
+The [Transaction](/docs/glossary/terms#transaction) hash.
+
 ## Parameters
 
 ### abi
@@ -117,7 +123,7 @@ export const account = privateKeyToAccount(...)
 The contract's ABI.
 
 ```ts
-await walletClient.deployContract({
+const hash = await walletClient.deployContract({
   abi: wagmiAbi, // [!code focus]
   account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   bytecode: '0x608060405260405161083e38038061083e833981016040819052610...',
@@ -133,7 +139,7 @@ The Account to deploy the contract from.
 Accepts a [JSON-RPC Account](/docs/clients/wallet#json-rpc-accounts) or [Local Account (Private Key, etc)](/docs/clients/wallet#local-accounts-private-key-mnemonic-etc).
 
 ```ts
-await walletClient.deployContract({
+const hash = await walletClient.deployContract({
   abi: wagmiAbi, 
   account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266', // [!code focus]
   bytecode: '0x608060405260405161083e38038061083e833981016040819052610...',
@@ -147,7 +153,7 @@ await walletClient.deployContract({
 The contract's bytecode.
 
 ```ts
-await walletClient.deployContract({
+const hash = await walletClient.deployContract({
   abi: wagmiAbi,
   account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   bytecode: '0x608060405260405161083e38038061083e833981016040819052610...', // [!code focus]
@@ -161,7 +167,7 @@ await walletClient.deployContract({
 Constructor arguments to call upon deployment.
 
 ```ts
-await walletClient.deployContract({
+const hash = await walletClient.deployContract({
   abi: wagmiAbi,
   account: '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266',
   bytecode: '0x608060405260405161083e38038061083e833981016040819052610...',

site/docs/contract/estimateContractGas.md

@@ -16,6 +16,8 @@ head:
 
 Estimates the gas required to successfully execute a contract write function call. 
 
+Internally, `estimateContractGas` uses a [Public Client](/docs/clients/public) to call the [`estimateGas` action](/docs/actions/public/estimateGas) with [ABI-encoded `data`](/docs/contract/encodeFunctionData).
+
 ## Usage
 
 Below is a very basic example of how to estimate gas (with no arguments).

site/docs/contract/getBytecode.md

@@ -58,4 +58,8 @@ The contract address.
 const bytecode = await publicClient.getBytecode({
   address: '0xFBA3912Ca04dd458c843e2EE08967fC04f3579c2', // [!code focus]
 })
-```
+```
+
+## JSON-RPC Method
+
+[`eth_getCode`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getcode)

site/docs/contract/getContract.md

@@ -155,7 +155,7 @@ Depending on if you create a contract instance with a Public Client, Wallet Clie
 
 #### With Public Client
 
-If you pass in a [`publicClient`](/docs/contract/getContract#publicclient), the following methods are available:
+If you pass in a [`publicClient`](https://viem.sh/docs/clients/public.html), the following methods are available:
 
 - [`createEventFilter`](/docs/contract/createContractEventFilter.html)
 - [`estimateGas`](/docs/contract/estimateContractGas.html)
@@ -165,7 +165,7 @@ If you pass in a [`publicClient`](/docs/contract/getContract#publicclient), the
 
 #### With Wallet Client
 
-If you pass in a [`walletClient`](/docs/contract/getContract#walletclient), the following methods are available:
+If you pass in a [`walletClient`](/docs/clients/wallet.html), the following methods are available:
 
 - [`write`](/docs/contract/writeContract.html)
 

site/docs/contract/getStorageAt.md

@@ -77,3 +77,6 @@ const data = await publicClient.getStorageAt({
 })
 ```
 
+## JSON-RPC Method
+
+[`eth_getStorageAt`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getstorageat)

site/docs/contract/simulateContract.md

@@ -38,7 +38,6 @@ const { result } = await publicClient.simulateContract({
   functionName: 'mint',
   account,
 })
-// 69420
 ```
 
 ```ts [abi.ts]
@@ -94,7 +93,6 @@ const { result } = await publicClient.simulateContract({
   args: [69420],
   account,
 })
-// 69420
 ```
 
 ```ts [abi.ts]
@@ -184,7 +182,7 @@ export const publicClient = createPublicClient({
 
 ## Return Value
 
-The response from the contract. Type is inferred.
+The simulation result and write request. Type is inferred.
 
 ## Parameters
 

site/docs/ens/actions/getEnsAvatar.md

@@ -16,6 +16,8 @@ head:
 
 Gets the avatar of an ENS name.
 
+Calls [`getEnsText`](/docs/ens/actions/getEnsText.html) with `key` set to `'avatar'`.
+
 ## Usage
 
 ::: code-group

site/docs/ens/actions/getEnsText.md

@@ -16,6 +16,8 @@ head:
 
 Gets a text record for specified ENS name.
 
+Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.
+
 ## Usage
 
 ::: code-group

src/actions/ens/getEnsAddress.ts

@@ -17,20 +17,43 @@ import type { ReadContractParameters } from '../public/index.js'
 
 export type GetEnsAddressParameters = Prettify<
   Pick<ReadContractParameters, 'blockNumber' | 'blockTag'> & {
-    /** ENS name to get address. */
+    /** Name to get the address for. */
     name: string
-    /** Address of ENS Universal Resolver Contract */
+    /** Address of ENS Universal Resolver Contract. */
     universalResolverAddress?: Address
   }
 >
 
 export type GetEnsAddressReturnType = Address | null
 
 /**
- * @description Gets address for ENS name.
+ * Gets address for ENS name.
  *
- * - Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.
- * - Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this.
+ * - Docs: https://viem.sh/docs/ens/actions/getEnsAddress.html
+ * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens
+ *
+ * @remarks
+ * Calls `resolve(bytes, bytes)` on ENS Universal Resolver Contract.
+ *
+ * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetEnsAddressParameters}
+ * @returns Address for ENS name or `null` if not found. {@link GetEnsAddressReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getEnsAddress, normalize } from 'viem/ens'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const ensAddress = await getEnsAddress(client, {
+ *   name: normalize('wagmi-dev.eth'),
+ * })
+ * // '0xd2135CfB216b74109775236E36d4b433F1DF507B'
  */
 export async function getEnsAddress<TChain extends Chain | undefined,>(
   client: PublicClient<Transport, TChain>,

src/actions/ens/getEnsAvatar.ts

@@ -6,15 +6,41 @@ import type { GetEnsTextParameters } from './getEnsText.js'
 
 export type GetEnsAvatarParameters = Prettify<
   Omit<GetEnsTextParameters, 'key'> & {
-    /** Custom gateways to use */
+    /** Gateway urls to resolve IPFS and/or Arweave assets. */
     gatewayUrls?: AssetGatewayUrls
   }
 >
 
 export type GetEnsAvatarReturnType = string | null
 
 /**
- * @description Gets avatar URI for ENS name.
+ * Gets the avatar of an ENS name.
+ *
+ * - Docs: https://viem.sh/docs/ens/actions/getEnsAvatar.html
+ * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens
+ *
+ * @remarks
+ * Calls [`getEnsText`](https://viem.sh/docs/ens/actions/getEnsText.html) with `key` set to `'avatar'`.
+ *
+ * Since ENS names prohibit certain forbidden characters (e.g. underscore) and have other validation rules, you likely want to [normalize ENS names](https://docs.ens.domains/contract-api-reference/name-processing#normalising-names) with [UTS-46 normalization](https://unicode.org/reports/tr46) before passing them to `getEnsAddress`. You can use the built-in [`normalize`](https://viem.sh/docs/ens/utilities/normalize.html) function for this.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetEnsAvatarParameters}
+ * @returns Avatar URI or `null` if not found. {@link GetEnsAvatarReturnType}
+ *
+ * @example
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getEnsAvatar, normalize } from 'viem/ens'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const ensAvatar = await getEnsAvatar(client, {
+ *   name: normalize('wagmi-dev.eth'),
+ * })
+ * // 'https://ipfs.io/ipfs/Qma8mnp6xV3J2cRNf3mTth5C8nV11CAnceVinc3y8jSbio'
  */
 export async function getEnsAvatar<TChain extends Chain | undefined>(
   client: PublicClient<Transport, TChain>,

src/actions/ens/getEnsName.ts

@@ -20,12 +20,28 @@ export type GetEnsNameParameters = Prettify<
 export type GetEnsNameReturnType = string | null
 
 /**
- * @description Gets primary name for specified address.
+ * Gets primary name for specified address.
  *
- * - Calls `reverse(bytes)` on ENS Universal Resolver Contract.
+ * - Docs: https://viem.sh/docs/ens/actions/getEnsName.html
+ * - Examples: https://stackblitz.com/github/wagmi-dev/viem/tree/main/examples/ens
+ *
+ * @remarks
+ * Calls `reverse(bytes)` on ENS Universal Resolver Contract to "reverse resolve" the address to the primary ENS name.
+ *
+ * @param client - Client to use
+ * @param parameters - {@link GetEnsNameParameters}
+ * @returns Name or `null` if not found. {@link GetEnsNameReturnType}
  *
  * @example
- * const ensName = await getEnsName(publicClient, {
+ * import { createPublicClient, http } from 'viem'
+ * import { mainnet } from 'viem/chains'
+ * import { getEnsName } from 'viem/ens'
+ *
+ * const client = createPublicClient({
+ *   chain: mainnet,
+ *   transport: http(),
+ * })
+ * const ensName = await getEnsName(client, {
  *   address: '0xd2135CfB216b74109775236E36d4b433F1DF507B',
  * })
  * // 'wagmi-dev.eth'