docs: added more jsdocs and examples

src.ts/abi/abi-coder.ts

@@ -219,7 +219,7 @@ export class AbiCoder {
     }
 
     /**
-     *  Returns an ethers-compatible [[CALL_EXCEPTION]] Error for the given
+     *  Returns an ethers-compatible [[CallExceptionError]] Error for the given
      *  result %%data%% for the [[CallExceptionAction]] %%action%% against
      *  the Transaction %%tx%%.
      */

src.ts/abi/fragments.ts

@@ -1,7 +1,7 @@
 /**
  *  About frgaments...
  *
- *  @_subsection api/abi/abi-coder:Fragments
+ *  @_subsection api/abi/abi-coder:Fragments  [about-fragments]
  */
 
 import {
@@ -537,29 +537,28 @@ export class ParamType {
     /**
      *  True if the parameters is indexed.
      *
-     *  For non-indexable types (see [[ParamType_isIndexable]]) this
+     *  For non-indexable types this is ``null``.
-     *  is ``null``.
      */
     readonly indexed!: null | boolean;
 
     /**
      *  The components for the tuple.
      *
-     *  For non-tuple types (see [[ParamType_isTuple]]) this is ``null``.
+     *  For non-tuple types this is ``null``.
      */
     readonly components!: null | ReadonlyArray<ParamType>;
 
     /**
      *  The array length, or ``-1`` for dynamic-lengthed arrays.
      *
-     *  For non-array types (see [[ParamType_isArray]]) this is ``null``.
+     *  For non-array types this is ``null``.
      */
     readonly arrayLength!: null | number;
 
     /**
      *  The type of each child in the array.
      *
-     *  For non-array types (see [[ParamType_isArray]]) this is ``null``.
+     *  For non-array types this is ``null``.
      */
     readonly arrayChildren!: null | ParamType;
 

src.ts/abi/index.ts

@@ -1,7 +1,7 @@
 /**
  *  Explain about ABI here...
  *
- *  @_section api/abi:Application Binary Interface  [abi]
+ *  @_section api/abi:Application Binary Interface  [about-abi]
  *  @_navTitle: ABI
  */
 

src.ts/abi/interface.ts

@@ -660,7 +660,7 @@ export class Interface {
      *  specified error (see [[getError]] for valid values for
      *  %%key%%).
      *
-     *  Most developers should prefer the [[parseResult]] method instead,
+     *  Most developers should prefer the [[parseCallResult]] method instead,
      *  which will automatically detect a ``CALL_EXCEPTION`` and throw the
      *  corresponding error.
      */
@@ -742,7 +742,7 @@ export class Interface {
      *  specified function (see [[getFunction]] for valid values for
      *  %%key%%).
      *
-     *  Most developers should prefer the [[parseResult]] method instead,
+     *  Most developers should prefer the [[parseCallResult]] method instead,
      *  which will automatically detect a ``CALL_EXCEPTION`` and throw the
      *  corresponding error.
      */

src.ts/address/index.ts

@@ -10,7 +10,7 @@
  *  These functions help convert between various formats, validate
  *  addresses and safely resolve ENS names.
  *
- *  @_section: api/address:Addresses  [addresses]
+ *  @_section: api/address:Addresses  [about-addresses]
  */
 
 null;

src.ts/constants/index.ts

@@ -1,7 +1,7 @@
 /**
  *  Some common constants useful for Ethereum.
  *
- *  @_section: api/constants: Constants  [constants]
+ *  @_section: api/constants: Constants  [about-constants]
  */
 
 export { ZeroAddress } from "./addresses.js";

src.ts/contract/index.ts

@@ -1,7 +1,7 @@
 /**
  *  About contracts...
  *
- *  @_section: api/contract:Contracts  [contracts]
+ *  @_section: api/contract:Contracts  [about-contracts]
  */
 export {
     BaseContract, Contract

src.ts/crypto/index.ts

@@ -2,7 +2,7 @@
  *  A fundamental building block of Ethereum is the underlying
  *  cryptographic primitives.
  *
- *  @_section: api/crypto:Cryptographic Functions   [crypto]
+ *  @_section: api/crypto:Cryptographic Functions   [about-crypto]
  */
 
 null

src.ts/crypto/scrypt.ts

@@ -9,6 +9,8 @@ import type { BytesLike } from "../utils/index.js";
  *  UI or provide programatic access to the progress.
  *
  *  The %%percent%% is a value between ``0`` and ``1``.
+ *
+ *  @_docloc: api/crypto:Passwords
  */
 export type ProgressCallback = (percent: number) => void;
 

src.ts/crypto/signature.ts

@@ -1,3 +1,4 @@
+
 import { ZeroHash } from "../constants/index.js";
 import {
     concat, dataLength, getBigInt, getBytes, getNumber, hexlify,
@@ -22,6 +23,12 @@ const BN_35 = BigInt(35);
 const _guard = { };
 
 // @TODO: Allow Uint8Array
+
+/**
+ *  A SignatureLike
+ *
+ *  @_docloc: api/crypto:Signing
+ */
 export type SignatureLike = Signature | string | {
     r: string;
     s: string;
@@ -48,6 +55,9 @@ function toUint256(value: BigNumberish): string {
 
 /**
  *  A Signature  @TODO
+ *
+ *
+ *  @_docloc: api/crypto:Signing
  */
 export class Signature {
     #r: string;

src.ts/crypto/signing-key.ts

@@ -1,3 +1,8 @@
+/**
+ *  Add details about signing here.
+ *
+ *  @_subsection: api/crypto:Signing  [about-signing]
+ */
 
 import * as secp256k1 from "@noble/secp256k1";
 

src.ts/hash/index.ts

@@ -1,7 +1,7 @@
 /**
  *  About hashing here...
  *
- *  @_section: api/hashing:Hashing Utilities  [hashing]
+ *  @_section: api/hashing:Hashing Utilities  [about-hashing]
  */
 
 export { id } from "./id.js"

src.ts/providers/index.ts

@@ -1,7 +1,7 @@
 /**
  *  About providers.
  *
- *  @_section: api/providers:Providers  [providers]
+ *  @_section: api/providers:Providers  [about-providers]
  */
 
 

src.ts/transaction/index.ts

@@ -1,7 +1,7 @@
 /**
  *  Transactions..
  *
- *  @_section api/transaction:Transactions  [transactions]
+ *  @_section api/transaction:Transactions  [about-transactions]
  */
 
 null;

src.ts/utils/base64.ts

@@ -13,6 +13,19 @@ import type { BytesLike } from "./data.js";
 
 /**
  *  Decodes the base-64 encoded %%value%%.
+ *
+ *  @example:
+ *    // The decoded value is always binary data...
+ *    result = decodeBase64("SGVsbG8gV29ybGQhIQ==")
+ *    //_result:
+ *
+ *    // ...use toUtf8String to convert it to a string.
+ *    toUtf8String(result)
+ *    //_result:
+ *
+ *    // Decoding binary data
+ *    decodeBase64("EjQ=")
+ *    //_result:
  */
 export function decodeBase64(value: string): Uint8Array {
     return getBytesCopy(Buffer.from(value, "base64"));
@@ -20,6 +33,23 @@ export function decodeBase64(value: string): Uint8Array {
 
 /**
  *  Encodes %%data%% as a base-64 encoded string.
+ *
+ *  @example:
+ *    // Encoding binary data as a hexstring
+ *    encodeBase64("0x1234")
+ *    //_result:
+ *
+ *    // Encoding binary data as a Uint8Array
+ *    encodeBase64(new Uint8Array([ 0x12, 0x34 ]))
+ *    //_result:
+ *
+ *    // The input MUST be data...
+ *    encodeBase64("Hello World!!")
+ *    //_error:
+ *
+ *    // ...use toUtf8Bytes for this.
+ *    encodeBase64(toUtf8Bytes("Hello World!!"))
+ *    //_result:
  */
 export function encodeBase64(data: BytesLike): string {
     return Buffer.from(getBytes(data)).toString("base64");

src.ts/utils/data.ts

@@ -174,7 +174,7 @@ function zeroPad(data: BytesLike, length: number, left: boolean): string {
  *  Return the [[DataHexString]] of %%data%% padded on the **left**
  *  to %%length%% bytes.
  *
- *  If %%data%% already exceeds %%length%%, a [[BufferOverrun]] is
+ *  If %%data%% already exceeds %%length%%, a [[BufferOverrunError]] is
  *  thrown.
  *
  *  This pads data the same as **values** are in Solidity
@@ -188,7 +188,7 @@ export function zeroPadValue(data: BytesLike, length: number): string {
  *  Return the [[DataHexString]] of %%data%% padded on the **right**
  *  to %%length%% bytes.
  *
- *  If %%data%% already exceeds %%length%%, a [[BufferOverrun]] is
+ *  If %%data%% already exceeds %%length%%, a [[BufferOverrunError]] is
  *  thrown.
  *
  *  This pads data the same as **bytes** are in Solidity

src.ts/utils/index.ts

@@ -3,7 +3,7 @@
  *  Ethereum and to simplify the library, without increasing
  *  the library dependencies for simple functions.
  *
- *  @_section api/utils:Utilities  [utils]
+ *  @_section api/utils:Utilities  [about-utils]
  */
 
 export { decodeBase58, encodeBase58 } from "./base58.js";

src.ts/utils/maths.ts

@@ -89,7 +89,7 @@ export function mask(_value: BigNumberish, _bits: Numeric): bigint {
 }
 
 /**
- *  Gets a [[BigInt]] from %%value%%. If it is an invalid value for
+ *  Gets a BigInt from %%value%%. If it is an invalid value for
  *  a BigInt, then an ArgumentError will be thrown for %%name%%.
  */
 export function getBigInt(value: BigNumberish, name?: string): bigint {

src.ts/utils/units.ts

@@ -56,7 +56,7 @@ export function formatUnits(value: BigNumberish, unit?: string | Numeric): strin
 }
 
 /**
- *  Converts the //decimal string// %%value%% to a [[BigInt]], assuming
+ *  Converts the //decimal string// %%value%% to a BigInt, assuming
  *  %%unit%% decimal places. The %%unit%% may the number of decimal places
  *  or the name of a unit (e.g. ``"gwei"`` for 9 decimal places).
  */
@@ -83,7 +83,7 @@ export function formatEther(wei: BigNumberish): string {
 }
 
 /**
- *  Converts the //decimal string// %%ether%% to a [[BigInt]], using 18
+ *  Converts the //decimal string// %%ether%% to a BigInt, using 18
  *  decimal places.
  */
 export function parseEther(ether: string): bigint {

src.ts/utils/utf8.ts

@@ -120,7 +120,21 @@ function replaceFunc(reason: Utf8ErrorReason, offset: number, bytes: Uint8Array,
     return ignoreFunc(reason, offset, bytes, output, badCodepoint);
 }
 
-// Common error handing strategies
+/**
+ *  A handful of popular, built-in UTF-8 error handling strategies.
+ *
+ *  **``"error"``** - throws on ANY illegal UTF-8 sequence or
+ *  non-canonical (overlong) codepoints (this is the default)
+ *
+ *  **``"ignore"``** - silently drops any illegal UTF-8 sequence
+ *  and accepts non-canonical (overlong) codepoints
+ *
+ *  **``"replace"``** - replace any illegal UTF-8 sequence with the
+ *  UTF-8 replacement character (i.e. `\ufffd`) and accepts
+ *  non-canonical (overlong) codepoints
+ *
+ *  @returns: Record<"error" | "ignore" | "replace", Utf8ErrorFunc>
+ */
 export const Utf8ErrorFuncs: Readonly<Record<"error" | "ignore" | "replace", Utf8ErrorFunc>> = Object.freeze({
     error: errorFunc,
     ignore: ignoreFunc,
@@ -293,7 +307,7 @@ function _toUtf8String(codePoints: Array<number>): string {
  *
  *  When %%onError%% function is specified, it is called on UTF-8
  *  errors allowing recovery using the [[Utf8ErrorFunc]] API.
- *  (default: [error](Utf8ErrorFuncs-error))
+ *  (default: [error](Utf8ErrorFuncs))
  */
 export function toUtf8String(bytes: BytesLike, onError?: Utf8ErrorFunc): string {
     return _toUtf8String(getUtf8CodePoints(bytes, onError));

src.ts/wallet/index.ts

@@ -14,7 +14,7 @@
  *  low-level details of how an HD wallets are derived, exported
  *  or imported.
  *
- *  @_section: api/wallet:Wallets  [wallets]
+ *  @_section: api/wallet:Wallets  [about-wallets]
  */
 
 export { BaseWallet } from "./base-wallet.js";

src.ts/wallet/mnemonic.ts

@@ -102,7 +102,7 @@ function entropyToMnemonic(entropy: Uint8Array, wordlist?: null | Wordlist): str
 const _guard = { };
 
 /**
- *  A **Mnemonic** wraps all properties required to compute [[link-bip39]]
+ *  A **Mnemonic** wraps all properties required to compute [[link-bip-39]]
  *  seeds and convert between phrases and entropy.
  */
 export class Mnemonic {
@@ -188,7 +188,7 @@ export class Mnemonic {
     }
 
     /**
-     *  Returns true if %%phrase%% is a valid [[link-bip39]] phrase.
+     *  Returns true if %%phrase%% is a valid [[link-bip-39]] phrase.
      *
      *  This checks all the provided words belong to the %%wordlist%%,
      *  that the length is valid and the checksum is correct.

src.ts/wordlists/index.ts

@@ -15,7 +15,7 @@
  *  languages, but for maximal compatibility, the
  *  [English Wordlist](LangEn) is recommended.
  *
- *  @_section: api/wordlists:Wordlists [wordlists]
+ *  @_section: api/wordlists:Wordlists [about-wordlists]
  */
 export { Wordlist } from "./wordlist.js";
 export { LangEn } from "./lang-en.js";

src.ts/wordlists/wordlist.ts

@@ -2,7 +2,7 @@ import { defineProperties } from "../utils/index.js";
 
 /**
  *  A Wordlist represents a collection of language-specific
- *  words used to encode and devoce [[BIP-39]] encoded data
+ *  words used to encode and devoce [[link-bip-39]] encoded data
  *  by mapping words to 11-bit values and vice versa.
  */
 export abstract class Wordlist {