From fe63a81f6a15a521c643b74f4442cdbf037202cf Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 16 Jun 2017 16:30:35 +0200 Subject: Add and improve comments --- src/0x.ts | 23 ++++++++++++++++++----- src/contract_wrappers/exchange_wrapper.ts | 18 +++++++++++------- src/contract_wrappers/token_registry_wrapper.ts | 5 ++++- src/contract_wrappers/token_wrapper.ts | 14 ++++++++++---- 4 files changed, 43 insertions(+), 17 deletions(-) (limited to 'src') 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 { 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 { @@ -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 { 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 { 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, -- cgit