diff --git a/src.ts/address/contract-address.ts b/src.ts/address/contract-address.ts
index 79576939f..ec96d6ef9 100644
--- a/src.ts/address/contract-address.ts
+++ b/src.ts/address/contract-address.ts
@@ -9,6 +9,18 @@ import type { BigNumberish, BytesLike } from "../utils/index.js";
 
 
 // http://ethereum.stackexchange.com/questions/760/how-is-the-address-of-an-ethereum-contract-computed
+
+/**
+ *  Returns the address that would result from a ``CREATE`` for %%tx%%.
+ *
+ *  This can be used to compute the address a contract will be
+ *  deployed to by an EOA when sending a deployment transaction (i.e.
+ *  when the ``to`` address is ``null``).
+ *
+ *  This can also be used to compute the address a contract will be
+ *  deployed to by a contract, by using the contract's address as the
+ *  ``to`` and the contract's nonce.
+ */
 export function getCreateAddress(tx: { from: string, nonce: BigNumberish }): string {
     const from = getAddress(tx.from);
     const nonce = getBigInt(tx.nonce, "tx.nonce");
@@ -25,6 +37,13 @@ export function getCreateAddress(tx: { from: string, nonce: BigNumberish }): str
     return getAddress(dataSlice(keccak256(encodeRlp([ from, nonceHex ])), 12));
 }
 
+/**
+ *  Returns the address that would result from a ``CREATE2`` operation
+ *  with the given %%from%%, %%salt%% and %%initCodeHash%%.
+ *
+ *  To compute the %%initCodeHash%% from a contract's init code, use
+ *  the [[keccak256]] function.
+ */
 export function getCreate2Address(_from: string, _salt: BytesLike, _initCodeHash: BytesLike): string {
     const from = getAddress(_from);
     const salt = getBytes(_salt, "salt");
diff --git a/src.ts/address/index.ts b/src.ts/address/index.ts
index 06cbde843..c572c99ab 100644
--- a/src.ts/address/index.ts
+++ b/src.ts/address/index.ts
@@ -1,3 +1,10 @@
+/**
+ *  Addresses in Ethereum can be of several formats. These functions
+ *  help convert between them, checksum them, etc.
+ *
+ *  @_section: api/address:Addresses  [addresses]
+ */
+
 export interface Addressable {
     getAddress(): Promise<string>;
 }