From 314595113c94ce97df0df1234646d2fa09bb07a2 Mon Sep 17 00:00:00 2001
From: Richard Moore <github@ricmoo.com>
Date: Sun, 12 Feb 2023 21:21:11 -0500
Subject: [PATCH] docs: added more jsdocs and examples

---
 src.ts/abi/abi-coder.ts      |  2 +-
 src.ts/abi/fragments.ts      | 11 +++++------
 src.ts/abi/index.ts          |  2 +-
 src.ts/abi/interface.ts      |  4 ++--
 src.ts/address/index.ts      |  2 +-
 src.ts/constants/index.ts    |  2 +-
 src.ts/contract/index.ts     |  2 +-
 src.ts/crypto/index.ts       |  2 +-
 src.ts/crypto/scrypt.ts      |  2 ++
 src.ts/crypto/signature.ts   | 10 ++++++++++
 src.ts/crypto/signing-key.ts |  5 +++++
 src.ts/hash/index.ts         |  2 +-
 src.ts/providers/index.ts    |  2 +-
 src.ts/transaction/index.ts  |  2 +-
 src.ts/utils/base64.ts       | 30 ++++++++++++++++++++++++++++++
 src.ts/utils/data.ts         |  4 ++--
 src.ts/utils/index.ts        |  2 +-
 src.ts/utils/maths.ts        |  2 +-
 src.ts/utils/units.ts        |  4 ++--
 src.ts/utils/utf8.ts         | 18 ++++++++++++++++--
 src.ts/wallet/index.ts       |  2 +-
 src.ts/wallet/mnemonic.ts    |  4 ++--
 src.ts/wordlists/index.ts    |  2 +-
 src.ts/wordlists/wordlist.ts |  2 +-
 24 files changed, 90 insertions(+), 30 deletions(-)

diff --git a/src.ts/abi/abi-coder.ts b/src.ts/abi/abi-coder.ts
index fb7fc7a04..657a2bc2e 100644
--- a/src.ts/abi/abi-coder.ts
+++ b/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%%.
      */
diff --git a/src.ts/abi/fragments.ts b/src.ts/abi/fragments.ts
index c7dc1ccd9..33889ce63 100644
--- a/src.ts/abi/fragments.ts
+++ b/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
-     *  is ``null``.
+     *  For non-indexable types this 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;
 
diff --git a/src.ts/abi/index.ts b/src.ts/abi/index.ts
index a01e24991..2a6873581 100644
--- a/src.ts/abi/index.ts
+++ b/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
  */
 
diff --git a/src.ts/abi/interface.ts b/src.ts/abi/interface.ts
index 3d30e8552..54abd097b 100644
--- a/src.ts/abi/interface.ts
+++ b/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.
      */
diff --git a/src.ts/address/index.ts b/src.ts/address/index.ts
index f148aed99..1bf31b22c 100644
--- a/src.ts/address/index.ts
+++ b/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;
diff --git a/src.ts/constants/index.ts b/src.ts/constants/index.ts
index 774f470d1..be2e67ecd 100644
--- a/src.ts/constants/index.ts
+++ b/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";
diff --git a/src.ts/contract/index.ts b/src.ts/contract/index.ts
index a5b307c93..6d2ebb010 100644
--- a/src.ts/contract/index.ts
+++ b/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
diff --git a/src.ts/crypto/index.ts b/src.ts/crypto/index.ts
index e8cb26fad..fef23693f 100644
--- a/src.ts/crypto/index.ts
+++ b/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
diff --git a/src.ts/crypto/scrypt.ts b/src.ts/crypto/scrypt.ts
index 4c48ce598..2844cb91f 100644
--- a/src.ts/crypto/scrypt.ts
+++ b/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;
 
diff --git a/src.ts/crypto/signature.ts b/src.ts/crypto/signature.ts
index 183f67d0e..a189c7029 100644
--- a/src.ts/crypto/signature.ts
+++ b/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;
diff --git a/src.ts/crypto/signing-key.ts b/src.ts/crypto/signing-key.ts
index 9df9e174f..ce3c6bcd5 100644
--- a/src.ts/crypto/signing-key.ts
+++ b/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";
 
diff --git a/src.ts/hash/index.ts b/src.ts/hash/index.ts
index e6308cf4a..a7a46a3d1 100644
--- a/src.ts/hash/index.ts
+++ b/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"
diff --git a/src.ts/providers/index.ts b/src.ts/providers/index.ts
index 3990c2bda..c1e206839 100644
--- a/src.ts/providers/index.ts
+++ b/src.ts/providers/index.ts
@@ -1,7 +1,7 @@
 /**
  *  About providers.
  *
- *  @_section: api/providers:Providers  [providers]
+ *  @_section: api/providers:Providers  [about-providers]
  */
 
 
diff --git a/src.ts/transaction/index.ts b/src.ts/transaction/index.ts
index 89458e43a..1e18e43cf 100644
--- a/src.ts/transaction/index.ts
+++ b/src.ts/transaction/index.ts
@@ -1,7 +1,7 @@
 /**
  *  Transactions..
  *
- *  @_section api/transaction:Transactions  [transactions]
+ *  @_section api/transaction:Transactions  [about-transactions]
  */
 
 null;
diff --git a/src.ts/utils/base64.ts b/src.ts/utils/base64.ts
index 2919ba5c0..62778cfb2 100644
--- a/src.ts/utils/base64.ts
+++ b/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");
diff --git a/src.ts/utils/data.ts b/src.ts/utils/data.ts
index dd7b8d7de..085172965 100644
--- a/src.ts/utils/data.ts
+++ b/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
diff --git a/src.ts/utils/index.ts b/src.ts/utils/index.ts
index 7f4690ef1..7aba68c4b 100644
--- a/src.ts/utils/index.ts
+++ b/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";
diff --git a/src.ts/utils/maths.ts b/src.ts/utils/maths.ts
index 18bff7fbe..66f13f790 100644
--- a/src.ts/utils/maths.ts
+++ b/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 {
diff --git a/src.ts/utils/units.ts b/src.ts/utils/units.ts
index 5d110960c..1d150b227 100644
--- a/src.ts/utils/units.ts
+++ b/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 {
diff --git a/src.ts/utils/utf8.ts b/src.ts/utils/utf8.ts
index eee664619..7c72d91a7 100644
--- a/src.ts/utils/utf8.ts
+++ b/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));
diff --git a/src.ts/wallet/index.ts b/src.ts/wallet/index.ts
index 55ee75f23..bff953fa3 100644
--- a/src.ts/wallet/index.ts
+++ b/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";
diff --git a/src.ts/wallet/mnemonic.ts b/src.ts/wallet/mnemonic.ts
index fc8dafb65..e133888c0 100644
--- a/src.ts/wallet/mnemonic.ts
+++ b/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.
diff --git a/src.ts/wordlists/index.ts b/src.ts/wordlists/index.ts
index 6d5d537b4..d4a8d74ff 100644
--- a/src.ts/wordlists/index.ts
+++ b/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";
diff --git a/src.ts/wordlists/wordlist.ts b/src.ts/wordlists/wordlist.ts
index f2321dd5c..1a6bc6df2 100644
--- a/src.ts/wordlists/wordlist.ts
+++ b/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 {