Skip to content

Commit 724881f

Browse files
ricmooricmoo
committed
docs: added examples to jsdocs
1 parent 30d2626 commit 724881f

37 files changed

Lines changed: 471 additions & 130 deletions

‎src.ts/_tests/test-providers-ccip.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import assert from "assert";
33
import {
44
concat, dataLength,
55
keccak256,
6-
toArray,
6+
toBeArray,
77
isCallException, isError
88
} from "../index.js";
99

@@ -15,8 +15,8 @@ describe("Test CCIP execution", function() {
1515
// processed data from the endpoint
1616
const verify = function(sender: string, data: string, result: string): void {
1717
const check = concat([
18-
toArray(dataLength(sender)), sender,
19-
toArray(dataLength(data)), data
18+
toBeArray(dataLength(sender)), sender,
19+
toBeArray(dataLength(data)), data
2020
]);
2121
assert.equal(result, keccak256(check), "response is equal");
2222
}

‎src.ts/_tests/test-providers-errors.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
import assert from "assert";
33

44
import {
5-
concat, dataSlice, id, toArray, zeroPadValue,
5+
concat, dataSlice, id, toBeArray, zeroPadValue,
66
isCallException
77
} from "../index.js";
88

@@ -60,7 +60,7 @@ describe("Tests Provider Errors", function() {
6060

6161
const data = concat([
6262
dataSlice(id("testPanic(uint256)"), 0, 4),
63-
zeroPadValue(toArray(code), 32)
63+
zeroPadValue(toBeArray(code), 32)
6464
]);
6565

6666
const tx = { to: testAddr, data };

‎src.ts/_tests/test-utils-maths.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import assert from "assert";
22

33
import {
44
isError,
5-
getBigInt, getNumber, toArray, toHex, toQuantity,
5+
getBigInt, getNumber, toBeArray, toBeHex, toQuantity,
66
} from "../index.js";
77

88
describe("Tests Quantity Functions", function() {
@@ -146,7 +146,7 @@ describe("Tests Bad Math Values", function() {
146146
{
147147
name: "negative value",
148148
value: -4,
149-
error: "cannot toHex negative value"
149+
error: "cannot toBeHex negative value"
150150
},
151151
{
152152
name: "width too short",
@@ -157,9 +157,9 @@ describe("Tests Bad Math Values", function() {
157157
];
158158

159159
for (const { name, value, error, width } of badHex) {
160-
it(`correctly fails on bad toHex values: ${ name }`, function() {
160+
it(`correctly fails on bad toBeHex values: ${ name }`, function() {
161161
assert.throws(() => {
162-
const result = toHex(value, width);
162+
const result = toBeHex(value, width);
163163
console.log(result);
164164
}, (e: any) => {
165165
return (isError(e, "INVALID_ARGUMENT") &&
@@ -168,13 +168,13 @@ describe("Tests Bad Math Values", function() {
168168
});
169169
}
170170

171-
it(`correctly fails on nad toArray values: negative value`, function() {
171+
it(`correctly fails on nad toBeArray values: negative value`, function() {
172172
assert.throws(() => {
173-
const result = toArray(-4);
173+
const result = toBeArray(-4);
174174
console.log(result);
175175
}, (e: any) => {
176176
return (isError(e, "INVALID_ARGUMENT") &&
177-
e.message.startsWith("cannot toArray negative value"));
177+
e.message.startsWith("cannot toBeArray negative value"));
178178
});
179179
});
180180
});

‎src.ts/abi/coders/abstract-coder.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11

22
import {
33
defineProperties, concat, getBytesCopy, getNumber, hexlify,
4-
toArray, toBigInt, toNumber,
4+
toBeArray, toBigInt, toNumber,
55
assert, assertPrivate, assertArgument
66
} from "../../utils/index.js";
77

@@ -188,7 +188,7 @@ export function checkResultErrors(result: Result): Array<{ path: Array<string |
188188
}
189189

190190
function getValue(value: BigNumberish): Uint8Array {
191-
let bytes = toArray(value);
191+
let bytes = toBeArray(value);
192192

193193
assert (bytes.length <= WordSize, "value out-of-bounds",
194194
"BUFFER_OVERRUN", { buffer: bytes, length: WordSize, offset: bytes.length });

‎src.ts/abi/coders/address.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { getAddress } from "../../address/index.js";
2-
import { toHex } from "../../utils/maths.js";
2+
import { toBeHex } from "../../utils/maths.js";
33

44
import { Typed } from "../typed.js";
55
import { Coder } from "./abstract-coder.js";
@@ -31,6 +31,6 @@ export class AddressCoder extends Coder {
3131
}
3232

3333
decode(reader: Reader): any {
34-
return getAddress(toHex(reader.readValue(), 20));
34+
return getAddress(toBeHex(reader.readValue(), 20));
3535
}
3636
}

‎src.ts/abi/interface.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import { keccak256 } from "../crypto/index.js"
88
import { id } from "../hash/index.js"
99
import {
1010
concat, dataSlice, getBigInt, getBytes, getBytesCopy,
11-
hexlify, zeroPadValue, isHexString, defineProperties, assertArgument, toHex,
11+
hexlify, zeroPadValue, isHexString, defineProperties, assertArgument, toBeHex,
1212
assert
1313
} from "../utils/index.js";
1414

@@ -789,7 +789,7 @@ export class Interface {
789789
}
790790

791791
if (param.type.match(/^u?int/)) {
792-
value = toHex(value);
792+
value = toBeHex(value);
793793
}
794794

795795
// Check addresses are valid

‎src.ts/address/address.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,20 @@ function fromBase36(value: string): bigint {
101101
* that you wish to bypass the safegaurds in place to protect
102102
* against an address that has been incorrectly copied from another
103103
* source.
104+
*
105+
* @example:
106+
* // Adds the checksum (via upper-casing specific letters)
107+
* getAddress("0x8ba1f109551bd432803012645ac136ddd64dba72")
108+
* //_result:
109+
*
110+
* // Converts ICAP address and adds checksum
111+
* getAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
112+
* //_result:
113+
*
114+
* // Throws an error if an address contains mixed case,
115+
* // but the checksum fails
116+
* getAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBA72")
117+
* //_error:
104118
*/
105119
export function getAddress(address: string): string {
106120

@@ -139,6 +153,17 @@ export function getAddress(address: string): string {
139153
* industry [IBAN format](link-wiki-iban] for bank accounts.
140154
*
141155
* It is no longer common or a recommended format.
156+
*
157+
* @example:
158+
* getIcapAddress("0x8ba1f109551bd432803012645ac136ddd64dba72");
159+
* //_result:
160+
*
161+
* getIcapAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36");
162+
* //_result:
163+
*
164+
* // Throws an error if the ICAP checksum is wrong
165+
* getIcapAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK37");
166+
* //_error:
142167
*/
143168
export function getIcapAddress(address: string): string {
144169
//let base36 = _base16To36(getAddress(address).substring(2)).toUpperCase();

‎src.ts/address/checks.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,45 @@ import type { Addressable, AddressLike, NameResolver } from "./index.js";
88
/**
99
* Returns true if %%value%% is an object which implements the
1010
* [[Addressable]] interface.
11+
*
12+
* @example:
13+
* // Wallets and AbstractSigner sub-classes
14+
* isAddressable(Wallet.createRandom())
15+
* //_result:
16+
*
17+
* // Contracts
18+
* contract = new Contract("dai.tokens.ethers.eth", [ ], provider)
19+
* isAddressable(contract)
20+
* //_result:
1121
*/
1222
export function isAddressable(value: any): value is Addressable {
1323
return (value && typeof(value.getAddress) === "function");
1424
}
1525

1626
/**
1727
* Returns true if %%value%% is a valid address.
28+
*
29+
* @example:
30+
* // Valid address
31+
* isAddress("0x8ba1f109551bD432803012645Ac136ddd64DBA72")
32+
* //_result:
33+
*
34+
* // Valid ICAP address
35+
* isAddress("XE65GB6LDNXYOFTX0NSV3FUWKOWIXAMJK36")
36+
* //_result:
37+
*
38+
* // Invalid checksum
39+
* isAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBa72")
40+
* //_result:
41+
*
42+
* // Invalid ICAP checksum
43+
* isAddress("0x8Ba1f109551bD432803012645Ac136ddd64DBA72")
44+
* //_result:
45+
*
46+
* // Not an address (an ENS name requires a provided and an
47+
* // asynchronous API to access)
48+
* isAddress("ricmoo.eth")
49+
* //_result:
1850
*/
1951
export function isAddress(value: any): boolean {
2052
try {
@@ -40,6 +72,35 @@ async function checkAddress(target: any, promise: Promise<null | string>): Promi
4072
*
4173
* If an ENS name is provided, but that name has not been correctly
4274
* configured a [[UnconfiguredNameError]] is thrown.
75+
*
76+
* @example:
77+
* addr = "0x6B175474E89094C44Da98b954EedeAC495271d0F"
78+
*
79+
* // Addresses are return synchronously
80+
* resolveAddress(addr, provider)
81+
* //_result:
82+
*
83+
* // Address promises are resolved asynchronously
84+
* resolveAddress(Promise.resolve(addr))
85+
* //_result:
86+
*
87+
* // ENS names are resolved asynchronously
88+
* resolveAddress("dai.tokens.ethers.eth", provider)
89+
* //_result:
90+
*
91+
* // Addressable objects are resolved asynchronously
92+
* contract = new Contract(addr, [ ])
93+
* resolveAddress(contract, provider)
94+
* //_result:
95+
*
96+
* // Unconfigured ENS names reject
97+
* resolveAddress("nothing-here.ricmoo.eth", provider)
98+
* //_error:
99+
*
100+
* // ENS names require a NameResolver object passed in
101+
* // (notice the provider was omitted)
102+
* resolveAddress("nothing-here.ricmoo.eth")
103+
* //_error:
43104
*/
44105
export function resolveAddress(target: AddressLike, resolver?: null | NameResolver): string | Promise<string> {
45106

‎src.ts/address/contract-address.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,13 @@ import type { BigNumberish, BytesLike } from "../utils/index.js";
2020
* This can also be used to compute the address a contract will be
2121
* deployed to by a contract, by using the contract's address as the
2222
* ``to`` and the contract's nonce.
23+
*
24+
* @example
25+
* from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72";
26+
* nonce = 5;
27+
*
28+
* getCreateAddress({ from, nonce });
29+
* //_result:
2330
*/
2431
export function getCreateAddress(tx: { from: string, nonce: BigNumberish }): string {
2532
const from = getAddress(tx.from);
@@ -43,6 +50,22 @@ export function getCreateAddress(tx: { from: string, nonce: BigNumberish }): str
4350
*
4451
* To compute the %%initCodeHash%% from a contract's init code, use
4552
* the [[keccak256]] function.
53+
*
54+
* For a quick overview and example of ``CREATE2``, see [[link-ricmoo-wisps]].
55+
*
56+
* @example
57+
* // The address of the contract
58+
* from = "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
59+
*
60+
* // The salt
61+
* salt = id("HelloWorld")
62+
*
63+
* // The hash of the initCode
64+
* initCode = "0x6394198df16000526103ff60206004601c335afa6040516060f3";
65+
* initCodeHash = keccak256(initCode)
66+
*
67+
* getCreate2Address(from, salt, initCodeHash)
68+
* //_result:
4669
*/
4770
export function getCreate2Address(_from: string, _salt: BytesLike, _initCodeHash: BytesLike): string {
4871
const from = getAddress(_from);

‎src.ts/constants/addresses.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11

22
/**
33
* A constant for the zero address.
4+
*
5+
* (**i.e.** ``"0x0000000000000000000000000000000000000000"``)
46
*/
57
export const ZeroAddress: string = "0x0000000000000000000000000000000000000000";
68

0 commit comments

Comments
 (0)