Add and improve comments

4 files changed, 43 insertions, 17 deletions

diff --git a/src/0x.ts b/src/0x.ts
index f01c918d6..d9e7b1b82 100644
--- a/src/0x.ts
+++ b/src/0x.ts
@@ -22,6 +22,10 @@ import {orderSchema} from './schemas/order_schemas';
 // Customize our BigNumber instances
 bigNumberConfigs.configure();
 
+/**
+ * The ZeroEx class is the single entry-point into the 0x.js library. It contains all of the library's functionality
+ * and all calls to the library should be made through a ZeroEx instance.
+ */
 export class ZeroEx {
     /**
      * When creating an order without a specified taker or feeRecipient you must supply the Solidity
@@ -30,15 +34,24 @@ export class ZeroEx {
      */
     public static NULL_ADDRESS = constants.NULL_ADDRESS;
 
+    /**
+     * An instance of the ExchangeWrapper class containing methods for interacting with the 0x Exchange smart contract.
+     */
     public exchange: ExchangeWrapper;
+    /**
+     * An instance of the TokenRegistryWrapper class containing methods for interacting with the 0x TokenRegistry smart contract.
+     */
     public tokenRegistry: TokenRegistryWrapper;
+    /**
+     * An instance of the TokenWrapper class containing methods for interacting with any ERC20 token smart contract.
+     */
     public token: TokenWrapper;
     private _web3Wrapper: Web3Wrapper;
     /**
      * Verifies that the elliptic curve signature `signature` was generated
      * by signing `data` with the private key corresponding to the `signerAddress` address.
      * @param   data          The hex encoded data signed by the supplied signature.
-     * @param   signature     A JS object containing the elliptic curve signature parameters.
+     * @param   signature     An object containing the elliptic curve signature parameters.
      * @param   signerAddress The hex encoded address that signed the data, producing the supplied signature.
      * @return  Whether the signature is valid for the supplied signerAddress and data.
      */
@@ -145,8 +158,8 @@ export class ZeroEx {
         this.token.invalidateContractInstances();
     }
     /**
-     * Get addresses available throught the supplied web3 instance available for sending transactions.
-     * @return  An array of Ethereum addresses available.
+     * Get user Ethereum addresses available through the supplied web3 instance available for sending transactions.
+     * @return  An array of available user Ethereum addresses.
      */
     public async getAvailableAddressesAsync(): Promise<string[]> {
         const availableAddresses = await this._web3Wrapper.getAvailableAddressesAsync();
@@ -154,7 +167,7 @@ export class ZeroEx {
     }
     /**
      * Computes the orderHash for a supplied order.
-     * @param   order   A JS object that conforms to the Order or SignedOrder interface definitions.
+     * @param   order   An object that conforms to the Order or SignedOrder interface definitions.
      * @return  The resulting orderHash from hashing the supplied order.
      */
     public async getOrderHashHexAsync(order: Order|SignedOrder): Promise<string> {
@@ -170,7 +183,7 @@ export class ZeroEx {
      * @param   orderHash       Hex encoded orderHash to sign.
      * @param   signerAddress   The hex encoded Ethereum address you wish to sign it with. This address
      *          must be available via the Web3.Provider supplied to 0x.js.
-     * @return  A JS object containing the Elliptic curve signature parameters generated by signing the orderHash.
+     * @return  An object containing the Elliptic curve signature parameters generated by signing the orderHash.
      */
     public async signOrderHashAsync(orderHash: string, signerAddress: string): Promise<ECSignature> {
         assert.isHexString('orderHash', orderHash);
diff --git a/src/contract_wrappers/exchange_wrapper.ts b/src/contract_wrappers/exchange_wrapper.ts
index 4698089eb..92eaa0f45 100644
--- a/src/contract_wrappers/exchange_wrapper.ts
+++ b/src/contract_wrappers/exchange_wrapper.ts
@@ -37,6 +37,10 @@ import {constants} from '../utils/constants';
 import {TokenWrapper} from './token_wrapper';
 import {decorators} from '../utils/decorators';
 
+/**
+ * This class includes all the functionality related to calling methods and subscribing to
+ * events of the 0x Exchange smart contract.
+ */
 export class ExchangeWrapper extends ContractWrapper {
     private _exchangeContractErrCodesToMsg = {
         [ExchangeContractErrCodes.ERROR_FILL_EXPIRED]: ExchangeContractErrs.ORDER_FILL_EXPIRED,
@@ -129,7 +133,7 @@ export class ExchangeWrapper extends ContractWrapper {
      * we allow you to specify `shouldCheckTransfer`. If true, the smart contract will not throw if while
      * executing, the parties do not have sufficient balances/allowances, preserving gas costs. Setting it to
      * false forgoes this check and causes the smart contract to throw (using all the gas supplied) instead.
-     * @param   signedOrder             A JS object that conforms to the SignedOrder interface.
+     * @param   signedOrder             An object that conforms to the SignedOrder interface.
      * @param   takerTokenFillAmount    The amount of the order (in taker tokens baseUnits) that you wish to fill.
      * @param   shouldCheckTransfer     Whether or not you wish for the contract call to throw if upon
      *                                  execution the tokens cannot be transferred.
@@ -254,7 +258,7 @@ export class ExchangeWrapper extends ContractWrapper {
      * Executes multiple fills atomically in a single transaction.
      * If shouldCheckTransfer is set to true, it will continue filling subsequent orders even when earlier ones fail.
      * When shouldCheckTransfer is set to false, if any fill fails, the entire batch fails.
-     * @param   orderFillRequests       An array of JS objects that conform to the OrderFillRequest interface.
+     * @param   orderFillRequests       An array of objects that conform to the OrderFillRequest interface.
      * @param   shouldCheckTransfer     Whether or not you wish for the contract call to throw if upon
      *                                  execution any of the tokens cannot be transferred. If set to false,
      *                                  the call will continue to fill subsequent signedOrders even when some
@@ -321,7 +325,7 @@ export class ExchangeWrapper extends ContractWrapper {
     /**
      * Attempts to fill a specific amount of an order. If the entire amount specified cannot be filled,
      * the fill order is abandoned.
-     * @param   signedOrder             A JS object that conforms to the SignedOrder interface. The
+     * @param   signedOrder             An object that conforms to the SignedOrder interface. The
      *                                  signedOrder you wish to fill.
      * @param   takerTokenFillAmount    The total amount of the takerTokens you would like to fill.
      * @param   takerAddress            The user Ethereum address who would like to fill this order.
@@ -370,7 +374,7 @@ export class ExchangeWrapper extends ContractWrapper {
     /**
      * Batch version of fillOrKill. Allows a taker to specify a batch of orders that will either be atomically
      * filled (each to the specified fillAmount) or aborted.
-     * @param   orderFillOrKillRequests     An array of JS objects that conform to the OrderFillOrKillRequest interface.
+     * @param   orderFillOrKillRequests     An array of objects that conform to the OrderFillOrKillRequest interface.
      * @param   takerAddress                The user Ethereum address who would like to fill there orders.
      *                                      Must be available via the supplied Web3.Provider passed to 0x.js.
      */
@@ -426,7 +430,7 @@ export class ExchangeWrapper extends ContractWrapper {
     }
     /**
      * Cancel a given fill amount of an order. Cancellations are cumulative.
-     * @param   order                   A JS object that conforms to the Order or SignedOrder interface.
+     * @param   order                   An object that conforms to the Order or SignedOrder interface.
      *                                  The order you would like to cancel.
      * @param   takerTokenCancelAmount  The amount (specified in taker tokens) that you would like to cancel.
      */
@@ -463,7 +467,7 @@ export class ExchangeWrapper extends ContractWrapper {
     /**
      * Batch version of cancelOrderAsync. Atomically cancels multiple orders in a single transaction.
      * All orders must be from the same maker.
-     * @param   orderCancellationRequests   An array of JS objects that conform to the OrderCancellationRequest
+     * @param   orderCancellationRequests   An array of objects that conform to the OrderCancellationRequest
      *                                      interface.
      */
     @decorators.contractCallErrorHandler
@@ -515,7 +519,7 @@ export class ExchangeWrapper extends ContractWrapper {
      * Subscribe to an event type emitted by the Exchange smart contract
      * @param   eventName           The exchange contract event you would like to subscribe to.
      * @param   subscriptionOpts    Subscriptions options that let you configure the subscription.
-     * @param   indexFilterValues   A JS object where the keys are indexed args returned by the event and
+     * @param   indexFilterValues   An object where the keys are indexed args returned by the event and
      *                              the value is the value you are interested in. E.g `{maker: aUserAddressHex}`
      * @return                      ContractEventEmitter object
      */
diff --git a/src/contract_wrappers/token_registry_wrapper.ts b/src/contract_wrappers/token_registry_wrapper.ts
index ab0218777..3e87e4852 100644
--- a/src/contract_wrappers/token_registry_wrapper.ts
+++ b/src/contract_wrappers/token_registry_wrapper.ts
@@ -5,6 +5,9 @@ import {assert} from '../utils/assert';
 import {ContractWrapper} from './contract_wrapper';
 import * as TokenRegistryArtifacts from '../artifacts/TokenRegistry.json';
 
+/**
+ * This class includes all the functionality related to interacting with the 0x Token Registry smart contract.
+ */
 export class TokenRegistryWrapper extends ContractWrapper {
     private _tokenRegistryContractIfExists?: TokenRegistryContract;
     constructor(web3Wrapper: Web3Wrapper) {
@@ -15,7 +18,7 @@ export class TokenRegistryWrapper extends ContractWrapper {
     }
     /**
      * Retrieves all the tokens currently listed in the Token Registry smart contract
-     * @return  An array of JS objects that conform to the Token interface.
+     * @return  An array of objects that conform to the Token interface.
      */
     public async getTokensAsync(): Promise<Token[]> {
         const tokenRegistryContract = await this._getTokenRegistryContractAsync();
diff --git a/src/contract_wrappers/token_wrapper.ts b/src/contract_wrappers/token_wrapper.ts
index 98da6c2cd..29f9b2d1c 100644
--- a/src/contract_wrappers/token_wrapper.ts
+++ b/src/contract_wrappers/token_wrapper.ts
@@ -10,6 +10,11 @@ import {TokenContract, ZeroExError} from '../types';
 
 const ALLOWANCE_TO_ZERO_GAS_AMOUNT = 45730;
 
+/**
+ * This class includes all the functionality related to interacting with ERC20 token contracts.
+ * All ERC20 method calls are supported, along with some convenience methods for getting/setting allowances
+ * to the 0x Proxy smart contract.
+ */
 export class TokenWrapper extends ContractWrapper {
     private _tokenContractsByAddress: {[address: string]: TokenContract};
     constructor(web3Wrapper: Web3Wrapper) {
@@ -138,12 +143,13 @@ export class TokenWrapper extends ContractWrapper {
     /**
      * Transfers `amountInBaseUnits` ERC20 tokens from `fromAddress` to `toAddress`.
      * Requires the fromAddress to have sufficient funds and to have approved an allowance of
-     * `amountInBaseUnits` for senderAddress.
+     * `amountInBaseUnits` to `senderAddress`.
      * @param   tokenAddress        The hex encoded contract Ethereum address where the ERC20 token is deployed.
-     * @param   fromAddress         The hex encoded user Ethereum address that will send the funds.
+     * @param   fromAddress         The hex encoded user Ethereum address whose funds are being sent.
      * @param   toAddress           The hex encoded user Ethereum address that will receive the funds.
-     * @param   senderAddress       The hex encoded user Ethereum address whose funds are being sent. The senderAddress
-     *                              must have set an allowance to the fromAddress before this call.
+     * @param   senderAddress       The hex encoded user Ethereum address whose initiates the fund transfer. The
+     *                              `fromAddress` must have set an allowance to the `senderAddress`
+     *                              before this call.
      * @param   amountInBaseUnits   The amount (specified in baseUnits) of the token to transfer.
      */
     public async transferFromAsync(tokenAddress: string, fromAddress: string, toAddress: string,