docs: add basic tsdoc comments

packages/eslint-config/index.js

@@ -1,4 +1,5 @@
 import eslint from "@eslint/js";
+import tsdoc from "eslint-plugin-tsdoc";
 import tseslint from "typescript-eslint";
 
 export default tseslint.config(
@@ -17,4 +18,12 @@ export default tseslint.config(
       ],
     },
   },
+  {
+    plugins: {
+      tsdoc,
+    },
+    rules: {
+      "tsdoc/syntax": "warn",
+    },
+  },
 );

packages/eslint-config/package.json

@@ -13,6 +13,7 @@
     "@types/eslint__js": "^8.42.3",
     "eslint-plugin-react": "^7.34.2",
     "eslint-plugin-react-hooks": "^4.6.2",
+    "eslint-plugin-tsdoc": "^0.3.0",
     "typescript": "^5.4.5",
     "typescript-eslint": "^7.12.0"
   },

packages/react/src/context.tsx

@@ -7,7 +7,12 @@ import { useHydrateAtoms } from "jotai/utils";
 import { PolkadotSigner } from "polkadot-api";
 import { PropsWithChildren, createContext, useMemo } from "react";
 
-export type ReDotProviderProps = PropsWithChildren<{ config: Config }>;
+export type ReDotProviderProps = PropsWithChildren<{
+  /**
+   * Global config used by Reactive DOT
+   */
+  config: Config;
+}>;
 
 const ReDotHydrator = (props: ReDotProviderProps) => {
   useHydrateAtoms(
@@ -37,6 +42,12 @@ const ReDotHydrator = (props: ReDotProviderProps) => {
   return null;
 };
 
+/**
+ * React context provider for Reactive DOT
+ *
+ * @param props - Component props
+ * @returns React element
+ */
 export const ReDotProvider = (props: ReDotProviderProps) => (
   <ScopeProvider atoms={[chainConfigsAtom]}>
     <ReDotHydrator {...props} />
@@ -50,6 +61,12 @@ export type ReDotChainProviderProps = PropsWithChildren<{
   chainId: ChainId;
 }>;
 
+/**
+ * React context provider for scoping to a specific chain
+ *
+ * @param props - Component props
+ * @returns React element
+ */
 export const ReDotChainProvider = (props: ReDotChainProviderProps) => (
   <ChainIdContext.Provider value={props.chainId}>
     {props.children}
@@ -61,9 +78,18 @@ export const SignerContext = createContext<PolkadotSigner | undefined>(
 );
 
 export type ReDotSignerProviderProps = PropsWithChildren<{
+  /**
+   * The default signer
+   */
   signer: PolkadotSigner | undefined;
 }>;
 
+/**
+ * React context provider to assign a default signer
+ *
+ * @param props - Component props
+ * @returns React element
+ */
 export const ReDotSignerProvider = (props: ReDotSignerProviderProps) => (
   <SignerContext.Provider value={props.signer}>
     {props.children}

packages/react/src/hooks/types.ts

@@ -0,0 +1,9 @@
+import type { ChainId } from "@reactive-dot/types";
+
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type ChainHookOptions<T = {}> = T & {
+  /**
+   * Override default chain ID
+   */
+  chainId?: ChainId;
+};

packages/react/src/hooks/useAccounts.ts

@@ -1,4 +1,9 @@
 import { accountsAtom } from "../stores/accounts.js";
 import { useAtomValue } from "jotai";
 
+/**
+ * Hook for getting currently connected accounts.
+ *
+ * @returns The currently connected accounts
+ */
 export const useAccounts = () => useAtomValue(accountsAtom);

packages/react/src/hooks/useBlock.ts

@@ -3,14 +3,21 @@ import {
   bestBlockAtomFamily,
   finalizedBlockAtomFamily,
 } from "../stores/block.js";
+import type { ChainHookOptions } from "./types.js";
 import { ReDotError } from "@reactive-dot/core";
-import { ChainId } from "@reactive-dot/types";
 import { useAtomValue } from "jotai";
 import { useContext } from "react";
 
+/**
+ * Hook for fetching information about the latest block.
+ *
+ * @param tag - Which block to target
+ * @param options - Additional options
+ * @returns The latest finalized or best block
+ */
 export const useBlock = (
   tag: "best" | "finalized" = "finalized",
-  options?: { chainId?: ChainId },
+  options?: ChainHookOptions,
 ) => {
   const contextChainId = useContext(ChainIdContext);
   const chainId = options?.chainId ?? contextChainId;

packages/react/src/hooks/useClient.ts

@@ -1,11 +1,17 @@
 import { ChainIdContext } from "../context.js";
 import { clientAtomFamily } from "../stores/client.js";
+import type { ChainHookOptions } from "./types.js";
 import { ReDotError } from "@reactive-dot/core";
-import type { ChainId } from "@reactive-dot/types";
 import { useAtomValue } from "jotai";
 import { useContext } from "react";
 
-export const useClient = (options?: { chainId?: ChainId }) => {
+/**
+ * Hook for getting Polkadot-API client instance.
+ *
+ * @param options - Additional options
+ * @returns Polkadot-API client
+ */
+export const useClient = (options?: ChainHookOptions) => {
   const defaultChainId = useContext(ChainIdContext);
   const chainId = options?.chainId ?? defaultChainId;
 

packages/react/src/hooks/useMutation.ts

@@ -1,5 +1,6 @@
 import { ChainIdContext, SignerContext } from "../context.js";
 import { typedApiAtomFamily } from "../stores/client.js";
+import type { ChainHookOptions } from "./types.js";
 import { IDLE, MutationError, PENDING } from "@reactive-dot/core";
 import type { ChainId, Chains, ReDotDescriptor } from "@reactive-dot/types";
 import { useAtomCallback } from "jotai/utils";
@@ -23,6 +24,13 @@ type TxOptions<T extends Transaction<any, any, any, any>> = Parameters<
   >
 >[1];
 
+/**
+ * Hook for sending transactions to chains.
+ *
+ * @param action - The function to create the transaction
+ * @param options - Additional options
+ * @returns The current transaction state & submit function
+ */
 export const useMutation = <
   TAction extends (
     builder: TypedApi<
@@ -33,11 +41,16 @@ export const useMutation = <
   TChainId extends ChainId | void = void,
 >(
   action: TAction,
-  options?: {
-    chainId?: TChainId;
+  options?: ChainHookOptions<{
+    /**
+     * Override default signer
+     */
     signer?: PolkadotSigner;
+    /**
+     * Additional transaction options
+     */
     txOptions?: TxOptions<ReturnType<TAction>>;
-  },
+  }>,
 ) => {
   const contextChainId = useContext(ChainIdContext);
   const contextSigner = useContext(SignerContext);

packages/react/src/hooks/useQuery.ts

@@ -2,6 +2,7 @@ import { ChainIdContext } from "../context.js";
 import { compoundQueryAtomFamily } from "../stores/query.js";
 import type { Falsy, FalsyGuard, FlatHead } from "../types.js";
 import { flatHead, stringify } from "../utils.js";
+import type { ChainHookOptions } from "./types.js";
 import {
   InferQueryBuilder,
   QueryBuilder,
@@ -12,6 +13,13 @@ import type { ChainId, Chains, ReDotDescriptor } from "@reactive-dot/types";
 import { atom, useAtomValue } from "jotai";
 import { useContext, useMemo } from "react";
 
+/**
+ * Hook for querying data from chain, and returning the response.
+ *
+ * @param builder - The function to create the query
+ * @param options - Additional options
+ * @returns The data response
+ */
 export const useQuery = <
   TQuery extends
     | ((
@@ -24,7 +32,7 @@ export const useQuery = <
   TChainId extends ChainId | void = void,
 >(
   builder: TQuery,
-  options?: { chainId?: TChainId },
+  options?: ChainHookOptions,
 ): TQuery extends false
   ? undefined
   : FalsyGuard<

packages/react/src/hooks/useTypedApi.ts

@@ -1,14 +1,21 @@
 import { ChainIdContext } from "../context.js";
 import { typedApiAtomFamily } from "../stores/client.js";
+import type { ChainHookOptions } from "./types.js";
 import { ReDotError } from "@reactive-dot/core";
 import type { Chains, ChainId, ReDotDescriptor } from "@reactive-dot/types";
 import { useAtomValue } from "jotai";
 import { TypedApi } from "polkadot-api";
 import { useContext } from "react";
 
-export const useTypedApi = <TChainId extends ChainId | void = void>(options?: {
-  chainId?: TChainId;
-}): TypedApi<
+/**
+ * Hook for getting Polkadot-API typed API.
+ *
+ * @param options - Additional options
+ * @returns Polkadot-API typed API
+ */
+export const useTypedApi = <TChainId extends ChainId | void = void>(
+  options?: ChainHookOptions,
+): TypedApi<
   TChainId extends void ? ReDotDescriptor : Chains[Exclude<TChainId, void>]
 > => {
   const contextChainId = useContext(ChainIdContext);

packages/react/src/hooks/useWallets.ts

@@ -1,6 +1,16 @@
 import { connectedWalletsAtom, walletsAtom } from "../stores/wallets.js";
 import { useAtomValue } from "jotai";
 
+/**
+ * Hook for getting all available wallets.
+ *
+ * @returns Available wallets
+ */
 export const useWallets = () => useAtomValue(walletsAtom);
 
+/**
+ * Hook for getting all connected wallets.
+ *
+ * @returns Connected wallets
+ */
 export const useConnectedWallets = () => useAtomValue(connectedWalletsAtom);