docs: more details on various APIs.

ricmoo · ricmoo · commit 7d0b33dc42b1 · 2021-02-08T14:52:31.000-05:00
diff --git a/docs.wrm/api/contract/contract.wrm b/docs.wrm/api/contract/contract.wrm
@@ -183,6 +183,24 @@ The //overrides// object for write methods may include any of:
 - ``overrides.value`` - the amount of ether (in wei) to forward with the call
 - ``overrides.nonce`` - the nonce to use for the [[Signer]]
 
+If the ``wait()`` method on the returned [[providers-TransactionResponse]]
+is called, there will be additional properties on the receipt:
+
+- ``receipt.events`` - an array of the logs, with additional properties
+  (if the ABI included a description for the events)
+- ``receipt.events[n].args`` - the parsed arguments
+- ``receipt.events[n].decode`` - a method that can be used to parse the
+  log topics and data (this was used to compute ``args``)
+- ``receipt.events[n].event`` - the name of the event
+- ``receipt.events[n].eventSignature`` - the full signature of the event
+- ``receipt.removeListener()`` - a method to remove the listener that trigger
+  this event
+- ``receipt.getBlock()`` - a method to return the [Block](providers-Block) this event occurred in
+- ``receipt.getTransaction()`` - a method to return the
+  [Transaction](providers-TransactionResponse) this event occurred in
+- ``receipt.getTransactionReceipt()`` - a method to return the
+  [Transaction Receipt](providers-TransactionReceipt) this event occurred in
+
 
 _heading: Write Methods Analysis @<Contract--check>
 
diff --git a/docs.wrm/api/providers/other.wrm b/docs.wrm/api/providers/other.wrm
@@ -1,7 +1,5 @@
 _section: Other Providers
 
-Others...
-
 _subsection: FallbackProvider  @<FallbackProvider> @INHERIT<[[Provider]]> @SRC<providers/fallback-provider:class.FallbackProvider>
 
 The **FallbackProvider** is the most advanced [[Provider]] available in
diff --git a/docs.wrm/api/providers/provider.wrm b/docs.wrm/api/providers/provider.wrm
@@ -1,6 +1,20 @@
 _section: Provider @<Provider>
 
-Explain what a provider is...
+A **Provider** in ethers is a read-only abstraction to
+access the blockchain data.
+
+_note: Coming from Web3.js?
+If you are coming from Web3.js, this is one of the biggest
+differences you will encounter using ethers.
+
+The ethers library creates a strong division between the
+operation a **Provider** can perform and those of a [[Signer]],
+which Web3.js lumps together.
+
+This separation of concerns and a stricted subset of Provider
+operations allows for a larger variety of backends, a more
+consistent API and ensures other libraries to operate without
+being able to rely on any underlying assumption.
 
 _subsection: Accounts Methods  @<Provider--account-methods>
 
diff --git a/docs.wrm/api/utils/bytes.wrm b/docs.wrm/api/utils/bytes.wrm
@@ -1,6 +1,13 @@
 _section: Byte Manipulation
 
-Tra la la...
+While there are many high-level APIs for interacting with
+Ethereum, such as [Contracts](Contract) and [Providers](Provider),
+a lot of the low level access requires byte manipulation
+operations.
+
+Many of these operations are used internally, but can also be
+used to help normalize binary data representations from the
+output of various functions and methods.
 
 _subsection: Types
 
diff --git a/docs.wrm/api/utils/hdnode.wrm b/docs.wrm/api/utils/hdnode.wrm
@@ -1,6 +1,16 @@
 _section: HD Wallet @<hdnodes>
 
-TODO: Explain [BIP32](link-bip-32) [BIP-39](link-bip-39) and whatnot here...
+The Hierarchal Desterministic (HD) Wallet was a standard
+created for Bitcoin, but lends itself well to a wide variety of
+Blockchains which rely on secp256k1 private keys.
+
+For a more detailed technical understanding:
+
+- [BIP-32](link-bip-32) - the hierarchal deterministic description
+- [BIP-39](link-bip-39) - the method used to derive the BIP-32 seed
+  from human-readable sequences of words (i.e. a mnemonic)
+- [BIP-44](link-bip-44) - a standard defined to make BIP-32 easy
+  to adapt to any future compatible blockchain
 
 _subsection: Types
 
diff --git a/docs.wrm/api/utils/properties.wrm b/docs.wrm/api/utils/properties.wrm
@@ -1,9 +1,40 @@
 _section: Property Utilities
 
-_property: ethers.utils.checkProperties() => void
+This is a collection of utility functions used for handling
+properties in a platform-safe way.
+
+The next major version of ethers will no longer be compatible
+with ES3, so many of these will be removed in favor of the
+built-in options available in ES2015 and above.
+
+_property: ethers.utils.checkProperties(object, check) => void
+
+Checks that //object// only contains properties included
+in //check//, and throws [INVALID_ARGUMENT](errors--invalid-argument) if not.
 
 _property: ethers.utils.deepCopy(anObject) => any
+
+Creates a recursive copy of //anObject//. Frozen (i.e. and other known
+immutable) objects are copied by reference.
+
 _property: ethers.utils.defineReadOnly(anObject, name, value) => void
+
+Uses the ``Object.defineProperty`` method to set a read-only property
+on an object.
+
 _property: ethers.utils.getStatic(aConstructor, key) => any
+
+Recursively check for a static method //key// on an inheritance chain
+from //aConstructor// to all ancestors.
+
+This is used to mimic behaviour in other languages where ``this`` in
+a static method will also search ancestors.
+
 _property: ethers.utils.resolveProperties(anObject) => Promise<any> @<utils-resolveproperties> @SRC<properties>
+
+Retruns a Promise which resolves all child values on //anObject//.
+
 _property: ethers.utils.shallowCopy(anObject) => any
+
+Returns a shallow copy of //anObject//. This is the same as
+using ``Object.assign({ }, anObject)``.
diff --git a/docs.wrm/api/utils/strings.wrm b/docs.wrm/api/utils/strings.wrm
@@ -1,7 +1,11 @@
 _section: Strings  @<strings>
 
-Tra la la
+A **String** is a representation of a human-readable input of output,
+which are often taken for granted.
 
+When dealing with blockchains, properly handling human-readable and
+human-provided data is important to prevent loss of funds, assets,
+incorrect permissions, etc.
 
 _subsection: Bytes32String @<Bytes32String>
 
diff --git a/docs.wrm/config.js b/docs.wrm/config.js
@@ -262,6 +262,7 @@ module.exports = {
       "link-eip-2304": { name: "EIP-2304", url: "https:/\/eips.ethereum.org/EIPS/eip-2304" },
       "link-bip-39": { name: "BIP-39", url: "https:/\/en.bitcoin.it/wiki/BIP_0039" },
       "link-bip-32": { name: "BIP-32", url: "https:/\/github.com/bitcoin/bips/blob/master/bip-0032.mediawiki" },
+      "link-bip-44": { name: "BIP-44", url: "https:/\/en.bitcoin.it/wiki/BIP_0044" },
 
       "link-npm-elliptic": { name: "elliptic", url: "https:/\/www.npmjs.com/package/elliptic" },
       "link-npm-ethersproject-shims": { name: "Shims", url: "https:/\/www.npmjs.com/package/@ethersproject/shims" },
