docs: fix review comments

src/entities/Erc20TokenBalance.ts

@@ -5,7 +5,7 @@ import { PolymathError } from '../PolymathError';
 import { ErrorCode } from '../types';
 
 /**
- * Unique properties to identify an erc20 token holder
+ * Properties that uniquely identify an ERC20 token balance
  */
 export interface UniqueIdentifiers {
   tokenAddress: string;
@@ -19,15 +19,15 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers
 }
 
 /**
- * Unique properties including information for an erc20 token holders balance
+ * Constructor parameters
  */
 export interface Params {
   tokenSymbol: string | null;
   balance: BigNumber;
 }
 
 /**
- * Used to manage erc20 token holder balances
+ * Used to manage a ERC20 token balance
  */
 export class Erc20TokenBalance extends Entity<Params> {
   public static generateId({ tokenAddress, walletAddress }: UniqueIdentifiers) {
@@ -63,7 +63,7 @@ export class Erc20TokenBalance extends Entity<Params> {
   public tokenSymbol: string | null;
 
   /**
-   * address of the security token
+   * address of the ERC20 token
    */
   public tokenAddress: string;
 
@@ -78,7 +78,7 @@ export class Erc20TokenBalance extends Entity<Params> {
   public balance: BigNumber;
 
   /**
-   * Create an entity instance with erc20 token holder balance
+   * Create an ERC20 Token balance instance
    */
   constructor(params: Params & UniqueIdentifiers) {
     super();

src/entities/Investment.ts

@@ -5,7 +5,7 @@ import { PolymathError } from '../PolymathError';
 import { ErrorCode } from '../types';
 
 /**
- * Properties unique to a shareholder for a specific STO investment
+ * Properties that uniquely identify an Investment
  */
 export interface UniqueIdentifiers {
   securityTokenId: string;
@@ -22,7 +22,7 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers
 }
 
 /**
- * Represents constructor parameters for specific security token offering investment
+ * Constructor parameters
  */
 export interface Params {
   securityTokenSymbol: string;
@@ -32,7 +32,7 @@ export interface Params {
 }
 
 /**
- * Used to manage an investment in a security token
+ * Used to manage an Investment in a Security Token Offering
  */
 export class Investment extends Entity<Params> {
   public static generateId({ securityTokenId, stoId, index }: UniqueIdentifiers) {
@@ -44,9 +44,9 @@ export class Investment extends Entity<Params> {
   }
 
   /**
-   * Unserialize a serialized investment entity
+   * Unserialize a serialized Investment entity
    *
-   * @param serialized - string with investment entity information
+   * @param serialized - string with Investment entity information
    */
   public static unserialize(serialized: string) {
     const unserialized = unserialize(serialized);
@@ -62,14 +62,14 @@ export class Investment extends Entity<Params> {
   }
 
   /**
-   * unique generated identifier for an investment
+   * unique generated identifier for an Investment
    */
   public uid: string;
 
   public securityTokenId: string;
 
   /**
-   * unique ID for the investment STO
+   * unique ID for the Investment
    */
   public stoId: string;
 
@@ -81,22 +81,22 @@ export class Investment extends Entity<Params> {
   public address: string;
 
   /**
-   * index of the investment
+   * index of the Investment
    */
   public index: number;
 
   /**
-   * total amount of tokens involved in the investment
+   * total amount of tokens involved in the Investment
    */
   public tokenAmount: BigNumber;
 
   /**
-   * amount of funds used to make investment
+   * amount of funds used to make Investment
    */
   public investedFunds: BigNumber;
 
   /**
-   * Create an investment instance
+   * Create an Investment instance
    */
   constructor(params: Params & UniqueIdentifiers) {
     super();

src/entities/PolyTransaction.ts

@@ -28,7 +28,7 @@ const mapValuesDeep = (
 
 // TODO @monitz87: Make properties private where appliccable
 /**
- * Class to manage poly transactions to interact with blockchain extrinsics
+ * Wrapper class for a Polymath Transaction
  */
 export class PolyTransaction<Args = any, Values extends any[] = any[]> extends Entity<void> {
   public static generateId() {
@@ -48,37 +48,37 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> extends E
   public status: TransactionStatus = TransactionStatus.Idle;
 
   /**
-   * queue of pending transactions
+   * transaction queue to which this transaction belongs
    */
   public transactionQueue: TransactionQueue;
 
   /**
-   * promise for the poly transaction
+   * internal promise that resolves when the transaction has finished running
    */
   public promise: Promise<any>;
 
   /**
-   * optional error for the poly transaction
+   * stores errors thrown while running the transaction (if any)
    */
   public error?: PolymathError;
 
   /**
-   * optional receipt for the poly transaction
+   * stores the transaction receipt (if successful)
    */
   public receipt?: TransactionReceiptWithDecodedLogs | string;
 
   /**
-   * poly transaction tag
+   * type of transaction represented by this instance for display purposes
    */
   public tag: PolyTransactionTag;
 
   /**
-   * optional transaction hash for a poly transaction
+   * transaction hash (available after running)
    */
   public txHash?: string;
 
   /**
-   * transaction specification arguments
+   * arguments with which the transaction will be called
    */
   public args: TransactionSpec<Args, Values, TransactionReceiptWithDecodedLogs | string>['args'];
 
@@ -160,7 +160,7 @@ export class PolyTransaction<Args = any, Values extends any[] = any[]> extends E
   }
 
   /**
-   * Run the poly tranasaction and update a transaction status
+   * Run the poly transaction and update the transaction status
    */
   public async run() {
     try {

src/entities/Shareholder.ts

@@ -5,7 +5,7 @@ import { PolymathError } from '../PolymathError';
 import { ErrorCode } from '../types';
 
 /**
- * Basic properties of a unique shareholder for a specific security token
+ * Properties that uniquely identify a Shareholder of a specific Security Token
  */
 export interface UniqueIdentifiers {
   securityTokenId: string;
@@ -19,7 +19,7 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers
 }
 
 /**
- * Constructor properties for a specific shareholder on a security token
+ * Constructor parameters
  */
 export interface Params {
   securityTokenSymbol: string;
@@ -32,7 +32,7 @@ export interface Params {
 }
 
 /**
- * Used to manage a shareholder
+ * Used to manage a Shareholder
  */
 export class Shareholder extends Entity<Params> {
   public static generateId({ securityTokenId, address }: UniqueIdentifiers) {
@@ -43,9 +43,9 @@ export class Shareholder extends Entity<Params> {
   }
 
   /**
-   * Unserialize a serialized shareholder entity
+   * Unserialize a serialized Shareholder entity
    *
-   * @param serialized - string with shareholder entity information
+   * @param serialized - string with Shareholder entity information
    */
   public static unserialize(serialized: string) {
     const unserialized = unserialize(serialized);
@@ -61,7 +61,7 @@ export class Shareholder extends Entity<Params> {
   }
 
   /**
-   * unique generated id for a shareholder
+   * unique generated id for a Shareholder
    */
   public uid: string;
 
@@ -70,42 +70,42 @@ export class Shareholder extends Entity<Params> {
   public securityTokenId: string;
 
   /**
-   * date after which a shareholder can transfer tokens from their address
+   * 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
+   * date after which a Shareholder can transfer tokens to their address
    */
   public canReceiveAfter: Date;
 
   /**
-   * date when kyc approval will expire
+   * date when the Shareholder's KYC will expire
    */
   public kycExpiry: Date;
 
   /**
-   * whether shareholder is accredited or not
+   * whether the Shareholder is accredited or not
    */
   public isAccredited: boolean;
 
   /**
-   * whether shareholder can purchase from an STO or not
+   * whether the Shareholder can purchase from an STO or not
    */
   public canBuyFromSto: boolean;
 
   /**
-   * total security token balance of a shareholder
+   * total Security Token balance of the Shareholder
    */
   public balance: BigNumber;
 
   /**
-   * shareholder address
+   * wallet address
    */
   public address: string;
 
   /**
-   * Create a new shareholder instance
+   * Create a new Shareholder instance
    */
   constructor(params: Params & UniqueIdentifiers) {
     super();
@@ -138,7 +138,7 @@ export class Shareholder extends Entity<Params> {
   }
 
   /**
-   * Checks if this shareholder's KYC has been manually revoked
+   * Checks if this Shareholder's KYC has been manually revoked
    */
   public isRevoked() {
     const { canReceiveAfter, canSendAfter, kycExpiry } = this;

src/entities/TaxWithholding.ts

@@ -4,7 +4,7 @@ import { ErrorCode } from '../types';
 import { PolymathError } from '../PolymathError';
 
 /**
- * Properties unique to tax withholding properties for a specific security token holder
+ * Properties that uniquely identify a Tax Withholding percentage
  */
 export interface UniqueIdentifiers {
   securityTokenId: string;
@@ -22,15 +22,15 @@ function isUniqueIdentifiers(identifiers: any): identifiers is UniqueIdentifiers
 }
 
 /**
- * Unique properties for tax withholding of a security token
+ * Constructor parameters
  */
 export interface Params {
   securityTokenSymbol: string;
   percentage: number;
 }
 
 /**
- * Used to manage tax withholding amounts
+ * Represents the percentage that should be withheld from a Shareholder's dividend payment for tax purposes
  */
 export class TaxWithholding extends Entity<Params> {
   public static generateId({ securityTokenId, shareholderAddress }: UniqueIdentifiers) {
@@ -67,18 +67,15 @@ export class TaxWithholding extends Entity<Params> {
 
   public securityTokenId: string;
 
-  /**
-   * shareholder address for tax withholding properties
-   */
   public shareholderAddress: string;
 
   /**
-   * percentage of tax to be withheld
+   * percentage of tax to be withheld (0 to 1)
    */
   public percentage: number;
 
   /**
-   * Create a new tax withholding information instance
+   * Create a new tax withholding instance
    */
   constructor(params: Params & UniqueIdentifiers) {
     super();

src/entities/factories/Erc20TokenBalanceFactory.ts

@@ -3,7 +3,7 @@ import { Context } from '../../Context';
 import { Erc20TokenBalance, Params, UniqueIdentifiers } from '../Erc20TokenBalance';
 
 /**
- * Factory generates information for an erc20 token balance
+ * Factory generates information for an ERC20 Token Balance
  */
 export class Erc20TokenBalanceFactory extends Factory<
   Erc20TokenBalance,
@@ -28,7 +28,7 @@ export class Erc20TokenBalanceFactory extends Factory<
   };
 
   /**
-   * Create an instance of the erc20 token balance factory
+   * Create an instance of the ERC20 Token Balance Factory
    */
   constructor(context: Context) {
     super(Erc20TokenBalance, context);

src/entities/factories/InvestmentFactory.ts

@@ -17,7 +17,7 @@ import { PolymathError } from '../../PolymathError';
 const { weiToValue } = conversionUtils;
 
 /**
- * Factory generates information for an investment entity
+ * Factory generates information for an Investment entity
  */
 export class InvestmentFactory extends Factory<Investment, Params, UniqueIdentifiers> {
   /**
@@ -106,7 +106,7 @@ export class InvestmentFactory extends Factory<Investment, Params, UniqueIdentif
   };
 
   /**
-   * Create an instance of the investment factory
+   * Create an instance of the Investment Factory
    */
   constructor(context: Context) {
     super(Investment, context);