From 1dd9af99e9d910c28f700725fd99684d7ae75cf7 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sat, 10 Jun 2017 13:51:27 +0200 Subject: Align all param comments so that they are more readable --- src/contract_wrappers/exchange_wrapper.ts | 86 ++++++++++++++----------- src/contract_wrappers/token_registry_wrapper.ts | 2 +- src/contract_wrappers/token_wrapper.ts | 52 ++++++++------- 3 files changed, 76 insertions(+), 64 deletions(-) (limited to 'src/contract_wrappers') diff --git a/src/contract_wrappers/exchange_wrapper.ts b/src/contract_wrappers/exchange_wrapper.ts index 48bfa9edb..76f86e464 100644 --- a/src/contract_wrappers/exchange_wrapper.ts +++ b/src/contract_wrappers/exchange_wrapper.ts @@ -79,8 +79,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. + * @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 { assert.isValidOrderHash('orderHashHex', orderHashHex); @@ -93,8 +94,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. + * @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 { assert.isValidOrderHash('orderHashHex', orderHashHex); @@ -107,8 +108,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. + * @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 { assert.isValidOrderHash('orderHashHex', orderHashHex); @@ -126,12 +128,12 @@ 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 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. + * @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. */ public async fillOrderAsync(signedOrder: SignedOrder, takerTokenFillAmount: BigNumber.BigNumber, shouldCheckTransfer: boolean, takerAddress: string): Promise { @@ -176,13 +178,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. + * @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. */ public async fillOrdersUpToAsync(signedOrders: SignedOrder[], takerTokenFillAmount: BigNumber.BigNumber, shouldCheckTransfer: boolean, takerAddress: string): Promise { @@ -247,12 +251,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. + * @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. */ public async batchFillOrderAsync(orderFillRequests: OrderFillRequest[], shouldCheckTransfer: boolean, takerAddress: string): Promise { @@ -312,10 +317,11 @@ 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. + * @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. */ public async fillOrKillOrderAsync(signedOrder: SignedOrder, takerTokenFillAmount: BigNumber.BigNumber, takerAddress: string): Promise { @@ -359,9 +365,9 @@ 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. + * @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. */ public async batchFillOrKillAsync(orderFillOrKillRequests: OrderFillOrKillRequest[], takerAddress: string): Promise { @@ -414,6 +420,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. */ public async cancelOrderAsync( order: Order|SignedOrder, takerTokenCancelAmount: BigNumber.BigNumber): Promise { @@ -447,7 +456,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. + * @param orderCancellationRequests An array of JS objects that conform to the OrderCancellationRequest + * interface. */ public async batchCancelOrderAsync(orderCancellationRequests: OrderCancellationRequest[]): Promise { const makers = _.map(orderCancellationRequests, cancellationRequest => cancellationRequest.order.maker); @@ -495,11 +505,11 @@ 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. + * @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): diff --git a/src/contract_wrappers/token_registry_wrapper.ts b/src/contract_wrappers/token_registry_wrapper.ts index 5987dfca6..96346a7a4 100644 --- a/src/contract_wrappers/token_registry_wrapper.ts +++ b/src/contract_wrappers/token_registry_wrapper.ts @@ -15,7 +15,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 JS objects that conform to the Token interface. */ public async getTokensAsync(): Promise { const tokenRegistryContract = await this.getTokenRegistryContractAsync(); diff --git a/src/contract_wrappers/token_wrapper.ts b/src/contract_wrappers/token_wrapper.ts index e6ef64c55..bb79cac47 100644 --- a/src/contract_wrappers/token_wrapper.ts +++ b/src/contract_wrappers/token_wrapper.ts @@ -21,8 +21,8 @@ export class TokenWrapper extends ContractWrapper { } /** * 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. + * @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 { assert.isETHAddressHex('ownerAddress', ownerAddress); @@ -38,10 +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. + * @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 { @@ -63,10 +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. + * @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); @@ -81,8 +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. + * @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); @@ -95,9 +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. + * @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 { @@ -110,10 +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. + * @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 { @@ -137,12 +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. + * @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): -- cgit