Merge branch 'master' into error-decorator

3 files changed, 93 insertions, 12 deletions

diff --git a/src/contract_wrappers/exchange_wrapper.ts b/src/contract_wrappers/exchange_wrapper.ts
index b03e55d8c..e3044042e 100644
--- a/src/contract_wrappers/exchange_wrapper.ts
+++ b/src/contract_wrappers/exchange_wrapper.ts
@@ -80,6 +80,9 @@ export class ExchangeWrapper extends ContractWrapper {
      * Returns the unavailable takerAmount of an order. Unavailable amount is defined as the total
      * amount that has been filled or cancelled. The remaining takerAmount can be calculated by
      * subtracting the unavailable amount from the total order takerAmount.
+     * @param   orderHashHex    The hex encoded orderHash for which you would like to retrieve the
+     *                          unavailable takerAmount.
+     * @return  The amount of the order (in taker tokens) that has either been filled or canceled.
      */
     public async getUnavailableTakerAmountAsync(orderHashHex: string): Promise<BigNumber.BigNumber> {
         assert.isValidOrderHash('orderHashHex', orderHashHex);
@@ -92,6 +95,8 @@ export class ExchangeWrapper extends ContractWrapper {
     }
     /**
      * Retrieve the takerAmount of an order that has already been filled.
+     * @param   orderHashHex    The hex encoded orderHash for which you would like to retrieve the filled takerAmount.
+     * @return  The amount of the order (in taker tokens) that has already been filled.
      */
     public async getFilledTakerAmountAsync(orderHashHex: string): Promise<BigNumber.BigNumber> {
         assert.isValidOrderHash('orderHashHex', orderHashHex);
@@ -104,6 +109,9 @@ export class ExchangeWrapper extends ContractWrapper {
     }
     /**
      * Retrieve the takerAmount of an order that has been cancelled.
+     * @param   orderHashHex    The hex encoded orderHash for which you would like to retrieve the
+     *                          cancelled takerAmount.
+     * @return  The amount of the order (in taker tokens) that has been cancelled.
      */
     public async getCanceledTakerAmountAsync(orderHashHex: string): Promise<BigNumber.BigNumber> {
         assert.isValidOrderHash('orderHashHex', orderHashHex);
@@ -120,7 +128,13 @@ export class ExchangeWrapper extends ContractWrapper {
      * could arise where a users balance or allowance changes before the fillOrder executes. Because of this,
      * 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 instead.
+     * 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   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.
+     * @param   takerAddress            The user Ethereum address who would like to fill this order.
+     *                                  Must be available via the supplied Web3.Provider passed to 0x.js.
      */
     @decorators.contractCallErrorHandler
     public async fillOrderAsync(signedOrder: SignedOrder, takerTokenFillAmount: BigNumber.BigNumber,
@@ -166,6 +180,15 @@ export class ExchangeWrapper extends ContractWrapper {
      * Sequentially and atomically fills signedOrders up to the specified takerTokenFillAmount.
      * If the fill amount is reached - it succeeds and does not fill the rest of the orders.
      * If fill amount is not reached - it fills as much of the fill amount as possible and succeeds.
+     * @param   signedOrders            The array of signedOrders that you would like to fill until
+     *                                  takerTokenFillAmount is reached.
+     * @param   takerTokenFillAmount    The total amount of the takerTokens you would like to fill.
+     * @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 cannot be filled.
+     * @param   takerAddress            The user Ethereum address who would like to fill these orders.
+     *                                  Must be available via the supplied Web3.Provider passed to 0x.js.
      */
     @decorators.contractCallErrorHandler
     public async fillOrdersUpToAsync(signedOrders: SignedOrder[], takerTokenFillAmount: BigNumber.BigNumber,
@@ -231,6 +254,13 @@ 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   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
+     *                                  cannot be filled.
+     * @param   takerAddress            The user Ethereum address who would like to fill these orders.
+     *                                  Must be available via the supplied Web3.Provider passed to 0x.js.
      */
     @decorators.contractCallErrorHandler
     public async batchFillOrderAsync(orderFillRequests: OrderFillRequest[],
@@ -291,26 +321,31 @@ 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
+     *                                  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.
+     *                                  Must be available via the supplied Web3.Provider passed to 0x.js.
      */
     @decorators.contractCallErrorHandler
-    public async fillOrKillOrderAsync(signedOrder: SignedOrder, fillTakerAmount: BigNumber.BigNumber,
-                                      takerAddress: string) {
+    public async fillOrKillOrderAsync(signedOrder: SignedOrder, takerTokenFillAmount: BigNumber.BigNumber,
+                                      takerAddress: string): Promise<void> {
         assert.doesConformToSchema('signedOrder', signedOrder, signedOrderSchema);
-        assert.isBigNumber('fillTakerAmount', fillTakerAmount);
+        assert.isBigNumber('takerTokenFillAmount', takerTokenFillAmount);
         await assert.isSenderAddressAsync('takerAddress', takerAddress, this.web3Wrapper);
 
         const exchangeInstance = await this.getExchangeContractAsync();
-        await this.validateFillOrderAndThrowIfInvalidAsync(signedOrder, fillTakerAmount, takerAddress);
+        await this.validateFillOrderAndThrowIfInvalidAsync(signedOrder, takerTokenFillAmount, takerAddress);
 
         await this.validateFillOrKillOrderAndThrowIfInvalidAsync(signedOrder, exchangeInstance.address,
-                                                                 fillTakerAmount);
+                                                                 takerTokenFillAmount);
 
         const [orderAddresses, orderValues] = ExchangeWrapper.getOrderAddressesAndValues(signedOrder);
 
         const gas = await exchangeInstance.fillOrKill.estimateGas(
             orderAddresses,
             orderValues,
-            fillTakerAmount,
+            takerTokenFillAmount,
             signedOrder.ecSignature.v,
             signedOrder.ecSignature.r,
             signedOrder.ecSignature.s,
@@ -321,7 +356,7 @@ export class ExchangeWrapper extends ContractWrapper {
         const response: ContractResponse = await exchangeInstance.fillOrKill(
             orderAddresses,
             orderValues,
-            fillTakerAmount,
+            takerTokenFillAmount,
             signedOrder.ecSignature.v,
             signedOrder.ecSignature.r,
             signedOrder.ecSignature.s,
@@ -335,10 +370,13 @@ 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   takerAddress                The user Ethereum address who would like to fill there orders.
+     *                                      Must be available via the supplied Web3.Provider passed to 0x.js.
      */
     @decorators.contractCallErrorHandler
     public async batchFillOrKillAsync(orderFillOrKillRequests: OrderFillOrKillRequest[],
-                                      takerAddress: string) {
+                                      takerAddress: string): Promise<void> {
         await assert.isSenderAddressAsync('takerAddress', takerAddress, this.web3Wrapper);
         assert.doesConformToSchema('orderFillOrKillRequests', orderFillOrKillRequests, orderFillOrKillRequestsSchema);
         const exchangeInstance = await this.getExchangeContractAsync();
@@ -388,6 +426,9 @@ 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.
+     *                                  The order you would like to cancel.
+     * @param   takerTokenCancelAmount  The amount (specified in taker tokens) that you would like to cancel.
      */
     @decorators.contractCallErrorHandler
     public async cancelOrderAsync(
@@ -422,6 +463,8 @@ 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
+     *                                      interface.
      */
     @decorators.contractCallErrorHandler
     public async batchCancelOrderAsync(orderCancellationRequests: OrderCancellationRequest[]): Promise<void> {
@@ -429,7 +472,8 @@ export class ExchangeWrapper extends ContractWrapper {
         assert.hasAtMostOneUniqueValue(makers, ExchangeContractErrs.MULTIPLE_MAKERS_IN_SINGLE_CANCEL_BATCH_DISALLOWED);
         const maker = makers[0];
         await assert.isSenderAddressAsync('maker', maker, this.web3Wrapper);
-        assert.doesConformToSchema('orderCancellationRequests', orderCancellationRequests, orderCancellationRequestsSchema);
+        assert.doesConformToSchema('orderCancellationRequests', orderCancellationRequests,
+                                   orderCancellationRequestsSchema);
         for (const cancellationRequest of orderCancellationRequests) {
             await this.validateCancelOrderAndThrowIfInvalidAsync(
                 cancellationRequest.order, cancellationRequest.takerTokenCancelAmount,
@@ -469,9 +513,15 @@ 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
+     *                              the value is the value you are interested in. E.g `{maker: aUserAddressHex}`
+     * @param   callback            The callback that will be called everytime a matching event is found.
      */
     public async subscribeAsync(eventName: ExchangeEvents, subscriptionOpts: SubscriptionOpts,
-                                indexFilterValues: IndexFilterValues, callback: EventCallback) {
+                                indexFilterValues: IndexFilterValues, callback: EventCallback):
+                                Promise<void> {
         const exchangeContract = await this.getExchangeContractAsync();
         let createLogEvent: CreateContractEvent;
         switch (eventName) {
diff --git a/src/contract_wrappers/token_registry_wrapper.ts b/src/contract_wrappers/token_registry_wrapper.ts
index 86bea1c5d..96346a7a4 100644
--- a/src/contract_wrappers/token_registry_wrapper.ts
+++ b/src/contract_wrappers/token_registry_wrapper.ts
@@ -13,6 +13,10 @@ export class TokenRegistryWrapper extends ContractWrapper {
     public invalidateContractInstance(): void {
         delete this.tokenRegistryContractIfExists;
     }
+    /**
+     * Retrieves all the tokens currently listed in the Token Registry smart contract
+     * @return  An array of JS 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 4412b1299..bb79cac47 100644
--- a/src/contract_wrappers/token_wrapper.ts
+++ b/src/contract_wrappers/token_wrapper.ts
@@ -20,7 +20,9 @@ export class TokenWrapper extends ContractWrapper {
         this.tokenContractsByAddress = {};
     }
     /**
-     * Returns an owner's ERC20 token balance.
+     * Retrieves an owner's ERC20 token balance.
+     * @param   tokenAddress    The hex encoded contract Ethereum address where the ERC20 token is deployed.
+     * @param   ownerAddress    The hex encoded user Ethereum address whose balance you would like to check.
      */
     public async getBalanceAsync(tokenAddress: string, ownerAddress: string): Promise<BigNumber.BigNumber> {
         assert.isETHAddressHex('ownerAddress', ownerAddress);
@@ -36,6 +38,11 @@ export class TokenWrapper extends ContractWrapper {
     /**
      * Sets the spender's allowance to a specified number of baseUnits on behalf of the owner address.
      * Equivalent to the ERC20 spec method `approve`.
+     * @param   tokenAddress        The hex encoded contract Ethereum address where the ERC20 token is deployed.
+     * @param   ownerAddress        The hex encoded user Ethereum address who would like to set an allowance
+     *                              for spenderAddress.
+     * @param   spenderAddress      The hex encoded user Ethereum address who will be able to spend the set allowance.
+     * @param   amountInBaseUnits   The allowance amount you would like to set.
      */
     public async setAllowanceAsync(tokenAddress: string, ownerAddress: string, spenderAddress: string,
                                    amountInBaseUnits: BigNumber.BigNumber): Promise<void> {
@@ -57,6 +64,10 @@ export class TokenWrapper extends ContractWrapper {
     }
     /**
      * Retrieves the owners allowance in baseUnits set to the spender's address.
+     * @param   tokenAddress    The hex encoded contract Ethereum address where the ERC20 token is deployed.
+     * @param   ownerAddress    The hex encoded user Ethereum address whose allowance to spenderAddress
+     *                          you would like to retrieve.
+     * @param   spenderAddress  The hex encoded user Ethereum address who can spend the allowance you are fetching.
      */
     public async getAllowanceAsync(tokenAddress: string, ownerAddress: string, spenderAddress: string) {
         assert.isETHAddressHex('ownerAddress', ownerAddress);
@@ -71,6 +82,8 @@ export class TokenWrapper extends ContractWrapper {
     }
     /**
      * Retrieves the owner's allowance in baseUnits set to the 0x proxy contract.
+     * @param   tokenAddress    The hex encoded contract Ethereum address where the ERC20 token is deployed.
+     * @param   ownerAddress    The hex encoded user Ethereum address whose proxy contract allowance we are retrieving.
      */
     public async getProxyAllowanceAsync(tokenAddress: string, ownerAddress: string) {
         assert.isETHAddressHex('ownerAddress', ownerAddress);
@@ -83,6 +96,10 @@ export class TokenWrapper extends ContractWrapper {
     /**
      * Sets the 0x proxy contract's allowance to a specified number of a tokens' baseUnits on behalf
      * of an owner address.
+     * @param   tokenAddress        The hex encoded contract Ethereum address where the ERC20 token is deployed.
+     * @param   ownerAddress        The hex encoded user Ethereum address who is setting an allowance
+     *                              for the Proxy contract.
+     * @param   amountInBaseUnits   The allowance amount specified in baseUnits.
      */
     public async setProxyAllowanceAsync(tokenAddress: string, ownerAddress: string,
                                         amountInBaseUnits: BigNumber.BigNumber): Promise<void> {
@@ -95,6 +112,10 @@ export class TokenWrapper extends ContractWrapper {
     }
     /**
      * Transfers `amountInBaseUnits` ERC20 tokens from `fromAddress` to `toAddress`.
+     * @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   toAddress           The hex encoded user Ethereum address that will receive the funds.
+     * @param   amountInBaseUnits   The amount (specified in baseUnits) of the token to transfer.
      */
     public async transferAsync(tokenAddress: string, fromAddress: string, toAddress: string,
                                amountInBaseUnits: BigNumber.BigNumber): Promise<void> {
@@ -118,6 +139,12 @@ 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.
+     * @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   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   amountInBaseUnits   The amount (specified in baseUnits) of the token to transfer.
      */
     public async transferFromAsync(tokenAddress: string, fromAddress: string, toAddress: string,
                                    senderAddress: string, amountInBaseUnits: BigNumber.BigNumber):