docs: add comprehensive JSDoc documentation

.changeset/comprehensive-jsdoc-docs.md

@@ -0,0 +1,6 @@
+---
+'@solana/client': patch
+'@solana/react-hooks': patch
+---
+
+Add comprehensive JSDoc documentation for LLM-ready API docs

packages/client/src/features/sol.ts

@@ -28,40 +28,100 @@ import type { SolanaClientRuntime } from '../rpc/types';
 import { createWalletTransactionSigner, isWalletSession, resolveSignerMode } from '../signers/walletTransactionSigner';
 import type { WalletSession } from '../wallet/types';
 
+/**
+ * Blockhash and last valid block height for transaction lifetime.
+ * Used to ensure transactions expire after a certain block height.
+ */
 type BlockhashLifetime = Readonly<{
 	blockhash: Blockhash;
 	lastValidBlockHeight: bigint;
 }>;
 
+/**
+ * Amount of SOL to transfer. Can be specified as:
+ * - `bigint`: Raw lamports (1 SOL = 1_000_000_000 lamports)
+ * - `number`: SOL amount as decimal (e.g., 1.5 for 1.5 SOL)
+ * - `string`: SOL amount as string (e.g., "1.5" for 1.5 SOL)
+ */
 type SolTransferAmount = bigint | number | string;
 
+/**
+ * Authority that signs the SOL transfer transaction.
+ * Can be either a connected wallet session or a raw transaction signer.
+ */
 type SolTransferAuthority = TransactionSigner<string> | WalletSession;
 
 type SignableSolTransactionMessage = Parameters<typeof signTransactionMessageWithSigners>[0];
 
+/**
+ * Configuration for preparing a SOL transfer transaction.
+ *
+ * @example
+ * ```ts
+ * const config: SolTransferPrepareConfig = {
+ *   amount: 1_000_000_000n, // 1 SOL in lamports
+ *   authority: walletSession,
+ *   destination: 'RecipientAddress...',
+ *   commitment: 'confirmed',
+ * };
+ * ```
+ */
 export type SolTransferPrepareConfig = Readonly<{
+	/** Amount of SOL to transfer in lamports, decimal SOL, or string SOL. */
 	amount: SolTransferAmount;
+	/** Authority that signs the transaction. Can be a WalletSession or raw TransactionSigner. */
 	authority: SolTransferAuthority;
+	/** Commitment level for fetching blockhash and sending transaction. Defaults to client commitment. */
 	commitment?: Commitment;
+	/** Destination wallet address to receive the SOL. */
 	destination: Address | string;
+	/** Optional pre-fetched blockhash lifetime. If not provided, one will be fetched. */
 	lifetime?: BlockhashLifetime;
+	/** Transaction version. Defaults to 0 (legacy). */
 	transactionVersion?: TransactionVersion;
 }>;
 
+/**
+ * Options for sending a SOL transfer transaction.
+ *
+ * @example
+ * ```ts
+ * const options: SolTransferSendOptions = {
+ *   commitment: 'confirmed',
+ *   maxRetries: 3,
+ *   skipPreflight: false,
+ * };
+ * ```
+ */
 export type SolTransferSendOptions = Readonly<{
+	/** AbortSignal to cancel the transaction. */
 	abortSignal?: AbortSignal;
+	/** Commitment level for transaction confirmation. */
 	commitment?: Commitment;
+	/** Maximum number of times to retry sending the transaction. */
 	maxRetries?: bigint | number;
+	/** Minimum slot that the request can be evaluated at. */
 	minContextSlot?: Slot;
+	/** If true, skip the preflight transaction checks. */
 	skipPreflight?: boolean;
 }>;
 
+/**
+ * A prepared SOL transfer transaction ready to be signed and sent.
+ * Contains the transaction message, signer, and metadata needed for submission.
+ */
 type PreparedSolTransfer = Readonly<{
+	/** Commitment level used for this transaction. */
 	commitment?: Commitment;
+	/** Blockhash lifetime for transaction expiration. */
 	lifetime: BlockhashLifetime;
+	/** The unsigned transaction message. */
 	message: SignableSolTransactionMessage;
+	/** Signing mode: 'send' for wallets that sign+send, 'partial' for separate signing. */
 	mode: 'partial' | 'send';
+	/** The transaction signer. */
 	signer: TransactionSigner;
+	/** Transaction plan for execution. */
 	plan?: TransactionPlan;
 }>;
 
@@ -96,19 +156,74 @@ function toLamportAmount(input: SolTransferAmount): bigint {
 	return lamportsMath.fromLamports(input);
 }
 
+/**
+ * Helper interface for native SOL transfers using the System Program.
+ * Provides methods to prepare, sign, and send SOL transfer transactions.
+ *
+ * @example
+ * ```ts
+ * import { createSolTransferHelper } from '@solana/client';
+ *
+ * const helper = createSolTransferHelper(runtime);
+ *
+ * // Simple transfer
+ * const signature = await helper.sendTransfer({
+ *   amount: 1_000_000_000n, // 1 SOL
+ *   authority: walletSession,
+ *   destination: 'RecipientAddress...',
+ * });
+ *
+ * // Or prepare and send separately
+ * const prepared = await helper.prepareTransfer({ ... });
+ * const signature = await helper.sendPreparedTransfer(prepared);
+ * ```
+ */
 export type SolTransferHelper = Readonly<{
+	/**
+	 * Prepares a SOL transfer transaction without sending it.
+	 * Use this when you need to inspect or modify the transaction before sending.
+	 */
 	prepareTransfer(config: SolTransferPrepareConfig): Promise<PreparedSolTransfer>;
+	/**
+	 * Sends a previously prepared SOL transfer transaction.
+	 * Use this after prepareTransfer() to submit the transaction.
+	 */
 	sendPreparedTransfer(
 		prepared: PreparedSolTransfer,
 		options?: SolTransferSendOptions,
 	): Promise<ReturnType<typeof signature>>;
+	/**
+	 * Prepares and sends a SOL transfer in one call.
+	 * This is the simplest way to transfer SOL.
+	 */
 	sendTransfer(
 		config: SolTransferPrepareConfig,
 		options?: SolTransferSendOptions,
 	): Promise<ReturnType<typeof signature>>;
 }>;
 
-/** Creates documented helpers that build and submit System Program SOL transfers. */
+/**
+ * Creates helpers for building and submitting native SOL transfers via the System Program.
+ *
+ * @param runtime - The Solana client runtime with RPC connection.
+ * @returns A SolTransferHelper with methods to prepare and send SOL transfers.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from '@solana/client';
+ *
+ * const client = createClient({ cluster: 'devnet' });
+ * const helper = client.helpers.sol;
+ *
+ * // Transfer 0.5 SOL
+ * const sig = await helper.sendTransfer({
+ *   amount: 0.5, // Can use decimal SOL
+ *   authority: session,
+ *   destination: 'RecipientAddress...',
+ * });
+ * console.log('Transfer signature:', sig);
+ * ```
+ */
 export function createSolTransferHelper(runtime: SolanaClientRuntime): SolTransferHelper {
 	async function prepareTransfer(config: SolTransferPrepareConfig): Promise<PreparedSolTransfer> {
 		const commitment = config.commitment;