From cfcc1a5e2c52ab5460a98f6aa01acba3f8e7294f Mon Sep 17 00:00:00 2001 From: Victor Wiebe Date: Wed, 8 Jan 2020 12:39:24 -0800 Subject: [PATCH] docs: make more documentation changes based on review --- src/entities/Erc20TokenBalance.ts | 20 ++++-- src/entities/Investment.ts | 26 ++++++-- src/entities/PolyTransaction.ts | 64 +++++++++++++++++-- src/entities/Shareholder.ts | 32 ++++++++-- src/entities/TaxWithholding.ts | 17 +++-- .../factories/Erc20TokenBalanceFactory.ts | 4 +- src/entities/factories/InvestmentFactory.ts | 4 +- src/entities/factories/ShareholderFactory.ts | 4 +- .../factories/TaxWithholdingFactory.ts | 5 +- 9 files changed, 138 insertions(+), 38 deletions(-) diff --git a/src/entities/Erc20TokenBalance.ts b/src/entities/Erc20TokenBalance.ts index f085b89..5c80a08 100644 --- a/src/entities/Erc20TokenBalance.ts +++ b/src/entities/Erc20TokenBalance.ts @@ -5,7 +5,7 @@ import { PolymathError } from '../PolymathError'; import { ErrorCode } from '../types'; /** - * Represents the balance for an erc20 token holder + * Unique properties to identify an erc20 token holder */ export interface UniqueIdentifiers { tokenAddress: string; @@ -19,7 +19,7 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers } /** - * Represents information for an erc20 token holders balance + * Unique properties including information for an erc20 token holders balance */ export interface Params { tokenSymbol: string | null; @@ -55,20 +55,30 @@ export class Erc20TokenBalance extends Entity { return unserialized; } + /** + * Unique generated identifier for an ERC20 token balance + */ public uid: string; public tokenSymbol: string | null; + /** + * Address of the security token + */ public tokenAddress: string; + /** + * Wallet address of the token holder + */ public walletAddress: string; + /** + * Total number of tokens belonging to token holder + */ public balance: BigNumber; /** * Create an entity instance with erc20 token holder balance - * @param params parameters for an erc20 token balance and unique identifiers - * @param context the sdk is being used in */ constructor(params: Params & UniqueIdentifiers) { super(); @@ -101,7 +111,7 @@ export class Erc20TokenBalance extends Entity { } /** - * Hydrating the entity + * Hydrate the entity */ public _refresh(params: Partial) { const { tokenSymbol, balance } = params; diff --git a/src/entities/Investment.ts b/src/entities/Investment.ts index 80bcbe8..8f2bcdf 100644 --- a/src/entities/Investment.ts +++ b/src/entities/Investment.ts @@ -5,7 +5,7 @@ import { PolymathError } from '../PolymathError'; import { ErrorCode } from '../types'; /** - * Represents a unique shareholder for a specific investment + * Properties unique to a shareholder for a specific STO investment */ export interface UniqueIdentifiers { securityTokenId: string; @@ -22,7 +22,7 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers } /** - * Represents information for a specific security token investment + * Represents information for a specific security token offering investment */ export interface Params { securityTokenSymbol: string; @@ -61,26 +61,42 @@ export class Investment extends Entity { return unserialized; } + /** + * Unique generated identifier for an investment + */ public uid: string; public securityTokenId: string; + /** + * Unique ID for the investment STO + */ public stoId: string; public securityTokenSymbol: string; + /** + * Wallet address of token holder + */ public address: string; + /** + * Index of the investment + */ public index: number; + /** + * Total amount of tokens involved in the investment + */ public tokenAmount: BigNumber; + /** + * Amount of funds used to make investment + */ public investedFunds: BigNumber; /** * Create an investment instance - * @param params parameters defining an investment and unique identifiers - * @param context the sdk is being used in */ constructor(params: Params & UniqueIdentifiers) { super(); @@ -137,7 +153,7 @@ export class Investment extends Entity { } /** - * Hydrating the entity + * Hydrate the entity */ public _refresh(params: Partial) { const { securityTokenSymbol, address, investedFunds, tokenAmount } = params; diff --git a/src/entities/PolyTransaction.ts b/src/entities/PolyTransaction.ts index fbb1a60..47748fe 100644 --- a/src/entities/PolyTransaction.ts +++ b/src/entities/PolyTransaction.ts @@ -37,30 +37,63 @@ export class PolyTransaction extends E }); } + /** + * Unique generated identifier of the poly transaction + */ public uid: string; + /** + * Current status of the transaction + */ public status: TransactionStatus = TransactionStatus.Idle; + /** + * Queue of pending transactions + */ public transactionQueue: TransactionQueue; + /** + * Promise for the poly transaction + */ public promise: Promise; + /** + * Optional error for the poly transaction + */ public error?: PolymathError; + /** + * Optional receipt for the poly transaction + */ public receipt?: TransactionReceiptWithDecodedLogs | string; + /** + * Poly transaction tag + */ public tag: PolyTransactionTag; + /** + * Optional transaction hash for a poly transaction + */ public txHash?: string; + /** + * Transaction specification arguments + */ public args: TransactionSpec['args']; + /** + * @hidden + */ protected method: TransactionSpec< Args, Values, TransactionReceiptWithDecodedLogs | string >['method']; + /** + * @hidden + */ private postResolvers: PostTransactionResolverArray< Values, TransactionReceiptWithDecodedLogs | string @@ -69,12 +102,13 @@ export class PolyTransaction extends E TransactionReceiptWithDecodedLogs | string >; + /** + * @hidden + */ private emitter: EventEmitter; /** * Creates a poly transaction - * @param transaction specifications about the traction being made - * @param transactionQueue queue of pending transactions */ constructor( transaction: TransactionSpec, @@ -154,8 +188,11 @@ export class PolyTransaction extends E } /** - * Trigger change in status based on event - * @param listener transaction listener method + * Subscribe to status changes + * + * @param listener - callback function that will be called whenever the status changes + * + * @returns unsubscribe function */ public onStatusChange = (listener: (transaction: this) => void) => { this.emitter.on(Event.StatusChange, listener); @@ -165,10 +202,19 @@ export class PolyTransaction extends E }; }; + /** + * @hidden + */ protected resolve: (val?: any) => void = () => {}; + /** + * @hidden + */ protected reject: (reason?: any) => void = () => {}; + /** + * @hidden + */ private async internalRun() { this.updateStatus(TransactionStatus.Unapproved); @@ -218,6 +264,9 @@ export class PolyTransaction extends E return result; } + /** + * @hidden + */ private updateStatus = (status: TransactionStatus) => { this.status = status; @@ -246,6 +295,9 @@ export class PolyTransaction extends E /* eslint-enable default-case */ }; + /** + * @hidden + */ private unwrapArg(arg: PostTransactionResolver | T) { if (isPostTransactionResolver(arg)) { return arg.result; @@ -254,7 +306,7 @@ export class PolyTransaction extends E } /** - * Picks all post-transaction resolvers and unwraps their values + * @hidden */ private unwrapArgs(args: TransactionSpec['args']) { return mapValues(args, (arg: any) => { @@ -267,7 +319,7 @@ export class PolyTransaction extends E } /** - * Hydrating the entity + * Hydrate the entity */ public _refresh() {} } diff --git a/src/entities/Shareholder.ts b/src/entities/Shareholder.ts index c0835cd..c3a715a 100644 --- a/src/entities/Shareholder.ts +++ b/src/entities/Shareholder.ts @@ -5,7 +5,7 @@ import { PolymathError } from '../PolymathError'; import { ErrorCode } from '../types'; /** - * Represents a unique shareholder for a specific security token + * Basic properties of a unique shareholder for a specific security token */ export interface UniqueIdentifiers { securityTokenId: string; @@ -19,7 +19,7 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers } /** - * Represents information for a specific shareholder on a security token + * Properties for a specific shareholder on a security token */ export interface Params { securityTokenSymbol: string; @@ -60,30 +60,52 @@ export class Shareholder extends Entity { return unserialized; } + /** + * Unique generated id for a shareholder + */ public uid: string; public securityTokenSymbol: string; public securityTokenId: string; + /** + * Date after which a shareholder can transfer tokens from their address + */ public canSendAfter: Date; + /** + * Date after which a shareholder can transfer tokens to their address + */ public canReceiveAfter: Date; + /** + * Date when kyc approval will expire + */ public kycExpiry: Date; + /** + * Whether shareholder is accredited or not + */ public isAccredited: boolean; + /** + * Whether shareholder can purchase from an STO or not + */ public canBuyFromSto: boolean; + /** + * Total security token balance of a shareholder + */ public balance: BigNumber; + /** + * Shareholder address + */ public address: string; /** * Create a new shareholder instance - * @param params parameters for a shareholder and unique identifiers - * @param context the sdk is being used in */ constructor(params: Params & UniqueIdentifiers) { super(); @@ -161,7 +183,7 @@ export class Shareholder extends Entity { } /** - * Hydrating the entity + * Hydrate the entity */ public _refresh(params: Partial) { const { diff --git a/src/entities/TaxWithholding.ts b/src/entities/TaxWithholding.ts index 8790351..0a9bdf2 100644 --- a/src/entities/TaxWithholding.ts +++ b/src/entities/TaxWithholding.ts @@ -4,7 +4,7 @@ import { ErrorCode } from '../types'; import { PolymathError } from '../PolymathError'; /** - * Represents unique tax withholding properties for a specific security token holder + * Properties unique to tax withholding properties for a specific security token holder */ export interface UniqueIdentifiers { securityTokenId: string; @@ -22,7 +22,7 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers } /** - * Represents information for tax withholding information for a security token + * Unique properties for tax withholding of a security token */ export interface Params { securityTokenSymbol: string; @@ -57,20 +57,27 @@ export class TaxWithholding extends Entity { return unserialized; } + /** + * Unique generated identifer for tax withholding entity + */ public uid: string; public securityTokenSymbol: string; public securityTokenId: string; + /** + * Shareholder address for tax withholding properties + */ public shareholderAddress: string; + /** + * Percentage of tax to be withheld + */ public percentage: number; /** * Create a new tax withholding information instance - * @param params parameters for tax withholding and unique identifiers - * @param context the sdk is being used in */ constructor(params: Params & UniqueIdentifiers) { super(); @@ -103,7 +110,7 @@ export class TaxWithholding extends Entity { } /** - * Hydrating the entity + * Hydrate the entity */ public _refresh(params: Partial) { const { securityTokenSymbol, percentage } = params; diff --git a/src/entities/factories/Erc20TokenBalanceFactory.ts b/src/entities/factories/Erc20TokenBalanceFactory.ts index d815d61..285226c 100644 --- a/src/entities/factories/Erc20TokenBalanceFactory.ts +++ b/src/entities/factories/Erc20TokenBalanceFactory.ts @@ -25,9 +25,7 @@ export class Erc20TokenBalanceFactory extends Factory< }; /** - * Creates an instance of the erc20 token balance factory - * - * @param context the context in which sdk will be used + * Create an instance of the erc20 token balance factory */ constructor(context: Context) { super(Erc20TokenBalance, context); diff --git a/src/entities/factories/InvestmentFactory.ts b/src/entities/factories/InvestmentFactory.ts index 789d49d..fe6254d 100644 --- a/src/entities/factories/InvestmentFactory.ts +++ b/src/entities/factories/InvestmentFactory.ts @@ -103,9 +103,7 @@ export class InvestmentFactory extends Factory