From aedfcb62407e47a015180a509498179467131c21 Mon Sep 17 00:00:00 2001
From: Shiba <44804845+DeepDoge@users.noreply.github.com>
Date: Tue, 15 Oct 2024 21:31:43 +0000
Subject: [PATCH] added more docs

---
 jsr.json     |  2 +-
 types/abi.ts | 89 ++++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/jsr.json b/jsr.json
index 120cb17..07e78d3 100644
--- a/jsr.json
+++ b/jsr.json
@@ -1,6 +1,6 @@
 {
 	"name": "@nomadshiba/typed-contracts",
-	"version": "0.2.4",
+	"version": "0.2.5",
 	"exports": {
 		"./abi": "./types/abi.ts",
 		"./ethers6": "./types/ethers6/exports.ts"
diff --git a/types/abi.ts b/types/abi.ts
index 97bfff3..f924549 100644
--- a/types/abi.ts
+++ b/types/abi.ts
@@ -1,16 +1,47 @@
 /**
- * Shape of Solidity ABI
+ * `Abi` represents the structure of an Ethereum contract's Application Binary Interface (ABI),
+ * which defines the functions, events, and errors that can be interacted with in the contract.
+ * It is a readonly array of `Abi.Item`, which can represent functions, events, or errors.
+ *
+ * @example
+ * Example ABI structure:
+ * ```ts
+ * const exampleAbi: Abi = [
+ *   {
+ *     type: "function",
+ *     name: "transfer",
+ *     inputs: [
+ *       { name: "to", type: "address", internalType: "address" },
+ *       { name: "value", type: "uint256", internalType: "uint256" },
+ *     ],
+ *     outputs: [],
+ *     stateMutability: "nonpayable",
+ *   },
+ *   {
+ *     type: "event",
+ *     name: "Transfer",
+ *     inputs: [
+ *       { name: "from", type: "address", internalType: "address", indexed: true },
+ *       { name: "to", type: "address", internalType: "address", indexed: true },
+ *       { name: "value", type: "uint256", internalType: "uint256", indexed: false },
+ *     ],
+ *     anonymous: false,
+ *   },
+ * ];
+ * ```
  */
 export type Abi = readonly Abi.Item[]
+
 export namespace Abi {
+	/**
+	 * `Abi.Item` represents a single item in an ABI, which can be either a function, event, or error.
+	 */
 	export type Item = FunctionItem | EventItem | ErrorItem
 
-	type Argument = {
-		type: string
-		name: string
-		internalType: string
-	}
-
+	/**
+	 * `Abi.FunctionItem` defines a function in a contract's ABI, including its name, inputs, outputs,
+	 * and state mutability.
+	 */
 	export type FunctionItem =
 		| {
 				type: "function"
@@ -24,10 +55,24 @@ export namespace Abi {
 				inputs: readonly FunctionItem.Input[]
 				stateMutability: "nonpayable"
 		  }
+
+	/**
+	 * `Abi.FunctionItem.Input` and `Abi.FunctionItem.Output` represent the arguments and return values of a function.
+	 * They both share the same structure, defined by `Abi.Argument`, which includes the argument's type, name,
+	 * and internal type used in Solidity.
+	 */
 	export namespace FunctionItem {
-		export type Type = FunctionItem["type"]
 		export type Input = Argument & {}
 		export type Output = Argument & {}
+
+		/**
+		 * `Abi.FunctionItem.StateMutability` defines the mutability of a function, which can be:
+		 * - `pure`: does not read or modify the blockchain state.
+		 * - `view`: reads but does not modify the blockchain state.
+		 * - `constant`: synonym for `view` (legacy usage).
+		 * - `nonpayable`: does not accept Ether but may modify the state.
+		 * - `payable`: accepts Ether and may modify the state.
+		 */
 		export type StateMutability =
 			| "pure"
 			| "view"
@@ -36,24 +81,48 @@ export namespace Abi {
 			| "payable"
 	}
 
+	/**
+	 * `Abi.EventItem` defines an event in the contract's ABI, which can be emitted by the contract.
+	 * Each event has a name, inputs, and an `anonymous` flag indicating whether the event is anonymous.
+	 */
 	export type EventItem = {
 		type: "event"
 		name: string
 		inputs: readonly EventItem.Input[]
 		anonymous: boolean
 	}
+
 	export namespace EventItem {
-		export type Type = EventItem["type"]
+		/**
+		 * `Abi.EventItem.Input` represents an argument to an event, with an additional `indexed` flag
+		 * indicating whether the argument can be used to filter event logs.
+		 */
 		export type Input = Argument & { indexed: boolean }
 	}
 
+	/**
+	 * `Abi.ErrorItem` defines an error in the contract's ABI, which can be used for custom error handling.
+	 */
 	export type ErrorItem = {
 		type: "error"
 		name: string
 		inputs: readonly ErrorItem.Input[]
 	}
+
 	export namespace ErrorItem {
-		export type Type = ErrorItem["type"]
+		/**
+		 * `Abi.ErrorItem.Input` represents an argument to an error.
+		 */
 		export type Input = Argument & {}
 	}
+
+	/**
+	 * `Abi.Argument` represents a single argument in a function, event, or error.
+	 * It includes the argument's `type`, `name`, and `internalType` used by Solidity.
+	 */
+	type Argument = {
+		type: string
+		name: string
+		internalType: string
+	}
 }