docs: make more documentation changes based on review

PolymathNetwork · Jan 8, 2020 · cfcc1a5 · cfcc1a5
1 parent 7ca9ded
commit cfcc1a5
Show file tree

Hide file tree

Showing 9 changed files with 138 additions and 38 deletions.
diff --git 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<Params> {
     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<Params> {
   }
 
   /**
-   * Hydrating the entity
+   * Hydrate the entity
    */
   public _refresh(params: Partial<Params>) {
     const { tokenSymbol, balance } = params;

diff --git 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<Params> {
     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<Params> {
   }
 
   /**
-   * Hydrating the entity
+   * Hydrate the entity
    */
   public _refresh(params: Partial<Params>) {
     const { securityTokenSymbol, address, investedFunds, tokenAmount } = params;

diff --git a/src/entities/PolyTransaction.ts b/src/entities/PolyTransaction.ts
@@ -37,30 +37,63 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> 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<any>;
 
+  /**
+   * 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, Values, TransactionReceiptWithDecodedLogs | string>['args'];
 
+  /**
+   * @hidden
+   */
   protected method: TransactionSpec<
     Args,
     Values,
     TransactionReceiptWithDecodedLogs | string
   >['method'];
 
+  /**
+   * @hidden
+   */
   private postResolvers: PostTransactionResolverArray<
     Values,
     TransactionReceiptWithDecodedLogs | string
@@ -69,12 +102,13 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> 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<Args, Values, TransactionReceiptWithDecodedLogs | string>,
@@ -154,8 +188,11 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> 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<Args = any, Values extends any[] = any[]> 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<Args = any, Values extends any[] = any[]> extends E
     return result;
   }
 
+  /**
+   * @hidden
+   */
   private updateStatus = (status: TransactionStatus) => {
     this.status = status;
 
@@ -246,6 +295,9 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> extends E
     /* eslint-enable default-case */
   };
 
+  /**
+   * @hidden
+   */
   private unwrapArg<T>(arg: PostTransactionResolver<T> | T) {
     if (isPostTransactionResolver<T>(arg)) {
       return arg.result;
@@ -254,7 +306,7 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> extends E
   }
 
   /**
-   * Picks all post-transaction resolvers and unwraps their values
+   * @hidden
    */
   private unwrapArgs<T>(args: TransactionSpec<T>['args']) {
     return mapValues(args, (arg: any) => {
@@ -267,7 +319,7 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> extends E
   }
 
   /**
-   * Hydrating the entity
+   * Hydrate the entity
    */
   public _refresh() {}
 }
diff --git 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<Params> {
     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<Params> {
   }
 
   /**
-   * Hydrating the entity
+   * Hydrate the entity
    */
   public _refresh(params: Partial<Params>) {
     const {