Add documentation to eth modules.

src/app/_eth/accountIndex.ts

@@ -1,14 +1,35 @@
-import {environment} from '@src/environments/environment';
+// Third party imports
 import Web3 from 'web3';
 
+// Application imports
+import {environment} from '@src/environments/environment';
+
+/** Fetch the account registry contract's ABI. */
 const abi: Array<any> = require('@src/assets/js/block-sync/data/AccountRegistry.json');
+/** Establish a connection to the blockchain network. */
 const web3: Web3 = new Web3(environment.web3Provider);
 
+/**
+ * Provides an instance of the accounts registry contract.
+ * Allows querying of accounts that have been registered as valid accounts in the network.
+ *
+ * @remarks
+ * This is our interface to the accounts registry contract.
+ */
 export class AccountIndex {
-  contractAddress: string;
-  signerAddress: string;
+  /** The instance of the account registry contract. */
   contract: any;
+  /** The deployed account registry contract's address. */
+  contractAddress: string;
+  /** The account address of the account that deployed the account registry contract. */
+  signerAddress: string;
 
+  /**
+   * Create a connection to the deployed account registry contract.
+   *
+   * @param contractAddress - The deployed account registry contract's address.
+   * @param signerAddress - The account address of the account that deployed the account registry contract.
+   */
   constructor(contractAddress: string, signerAddress?: string) {
     this.contractAddress = contractAddress;
     this.contract = new web3.eth.Contract(abi, this.contractAddress);
@@ -19,14 +40,58 @@ export class AccountIndex {
     }
   }
 
-  public async totalAccounts(): Promise<number> {
-    return await this.contract.methods.count().call();
+  /**
+   * Registers an account to the accounts registry.
+   * Requires availability of the signer address.
+   *
+   * @async
+   * @example
+   * Prints "true" for registration of '0xc0ffee254729296a45a3885639AC7E10F9d54979':
+   * ```typescript
+   * console.log(await addToAccountRegistry('0xc0ffee254729296a45a3885639AC7E10F9d54979'));
+   * ```
+   *
+   * @param address - The account address to be registered to the accounts registry contract.
+   * @returns true - If registration is successful or account had already been registered.
+   */
+  public async addToAccountRegistry(address: string): Promise<boolean> {
+    if (!await this.haveAccount(address)) {
+      return await this.contract.methods.add(address).send({from: this.signerAddress});
+    }
+    return true;
   }
 
+  /**
+   * Checks whether a specific account address has been registered in the accounts registry.
+   * Returns "true" for available and "false" otherwise.
+   *
+   * @async
+   * @example
+   * Prints "true" or "false" depending on whether '0xc0ffee254729296a45a3885639AC7E10F9d54979' has been registered:
+   * ```typescript
+   * console.log(await haveAccount('0xc0ffee254729296a45a3885639AC7E10F9d54979'));
+   * ```
+   *
+   * @param address - The account address to be validated.
+   * @returns true - If the address has been registered in the accounts registry.
+   */
   public async haveAccount(address: string): Promise<boolean> {
     return await this.contract.methods.accountIndex(address).call() !== 0;
   }
 
+  /**
+   * Returns a specified number of the most recently registered accounts.
+   *
+   * @async
+   * @example
+   * Prints an array of accounts:
+   * ```typescript
+   * console.log(await last(5));
+   * ```
+   *
+   * @param numberOfAccounts - The number of accounts to return from the accounts registry.
+   * @returns An array of registered account addresses.
+   */
   public async last(numberOfAccounts: number): Promise<Array<string>> {
     const count: number = await this.totalAccounts();
     let lowest: number = count - numberOfAccounts - 1;
@@ -41,10 +106,19 @@ export class AccountIndex {
     return accounts;
   }
 
-  public async addToAccountRegistry(address: string): Promise<boolean> {
-    if (!await this.haveAccount(address)) {
-      return await this.contract.methods.add(address).send({from: this.signerAddress});
-    }
-    return true;
+  /**
+   * Returns the total number of accounts that have been registered in the network.
+   *
+   * @async
+   * @example
+   * Prints the total number of registered accounts:
+   * ```typescript
+   * console.log(await totalAccounts());
+   * ```
+   *
+   * @returns The total number of registered accounts.
+   */
+  public async totalAccounts(): Promise<number> {
+    return await this.contract.methods.count().call();
   }
 }

src/app/_eth/token-registry.spec.ts

@@ -1,3 +1,4 @@
+// Application imports
 import { TokenRegistry } from '@app/_eth/token-registry';
 import {environment} from '@src/environments/environment';
 

src/app/_eth/token-registry.ts

@@ -1,14 +1,36 @@
+// Third party imports
 import Web3 from 'web3';
+
+// Application imports
 import {environment} from '@src/environments/environment';
 
+
+/** Fetch the token registry contract's ABI. */
 const abi: Array<any> = require('@src/assets/js/block-sync/data/TokenUniqueSymbolIndex.json');
+/** Establish a connection to the blockchain network. */
 const web3: Web3 = new Web3(environment.web3Provider);
 
+/**
+ * Provides an instance of the token registry contract.
+ * Allows querying of tokens that have been registered as valid tokens in the network.
+ *
+ * @remarks
+ * This is our interface to the token registry contract.
+ */
 export class TokenRegistry {
-  contractAddress: string;
-  signerAddress: string;
+  /** The instance of the token registry contract. */
   contract: any;
+  /** The deployed token registry contract's address. */
+  contractAddress: string;
+  /** The account address of the account that deployed the token registry contract. */
+  signerAddress: string;
 
+  /**
+   * Create a connection to the deployed token registry contract.
+   *
+   * @param contractAddress - The deployed token registry contract's address.
+   * @param signerAddress - The account address of the account that deployed the token registry contract.
+   */
   constructor(contractAddress: string, signerAddress?: string) {
     this.contractAddress = contractAddress;
     this.contract = new web3.eth.Contract(abi, this.contractAddress);
@@ -19,16 +41,54 @@ export class TokenRegistry {
     }
   }
 
-  public async totalTokens(): Promise<number> {
-    return await this.contract.methods.entryCount().call();
-  }
-
-  public async entry(serial: number): Promise<string> {
-    return await this.contract.methods.entry(serial).call();
-  }
-
+  /**
+   * Returns the address of the token with a given identifier.
+   *
+   * @async
+   * @example
+   * Prints the address of the token with the identifier 'sarafu':
+   * ```typescript
+   * console.log(await addressOf('sarafu'));
+   * ```
+   *
+   * @param identifier - The name or identifier of the token to be fetched from the token registry.
+   * @returns The address of the token assigned the specified identifier in the token registry.
+   */
   public async addressOf(identifier: string): Promise<string> {
     const id: string = web3.eth.abi.encodeParameter('bytes32', web3.utils.toHex(identifier));
     return await this.contract.methods.addressOf(id).call();
   }
+
+  /**
+   * Returns the address of a token with the given serial in the token registry.
+   *
+   * @async
+   * @example
+   * Prints the address of the token with the serial '2':
+   * ```typescript
+   * console.log(await entry(2));
+   * ```
+   *
+   * @param serial - The serial number of the token to be fetched.
+   * @return The address of the token with the specified serial number.
+   */
+  public async entry(serial: number): Promise<string> {
+    return await this.contract.methods.entry(serial).call();
+  }
+
+  /**
+   * Returns the total number of tokens that have been registered in the network.
+   *
+   * @async
+   * @example
+   * Prints the total number of registered tokens:
+   * ```typescript
+   * console.log(await totalTokens());
+   * ```
+   *
+   * @returns The total number of registered tokens.
+   */
+  public async totalTokens(): Promise<number> {
+    return await this.contract.methods.entryCount().call();
+  }
 }