Added derive e2e tests and documentation (#898)

* export IExtrinsic

* Switch to localhos & enable tests in promise.spec

* Derive.accounts docs (copy from my other branch) + code examples

* Fixed existing accounts tests and added tests for all accounts.derive methods

* e2e tests and docs/ examples for balances.all and balances.fees

* Removed emty lines below jsdoc info

* tests & documentation dor derive.chain

* Addressed comments from former PR https://github.com/polkadot-js/api/pull/869

* Removed unused import

* obseralbe -> observable

* undo keith' commit

* use correct jsdocs syntax

* Re-enable skip

packages/api-derive/src/accounts/idAndIndex.ts

@@ -15,6 +15,19 @@ import { drr } from '../util/drr';
 
 export type AccountIdAndIndex = [AccountId?, AccountIndex?];
 
+/**
+ * @name idAndIndex
+ * @param {(Address | AccountId | AccountIndex | string | null)} address - An accounts address in various formats.
+ * @description  An array containing the [[AccountId]] and [[AccountIndex]] as optional values.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.accounts.idAndIndex('F7Hs', ([id, ix]) => {
+ *   console.log(`AccountId #${id} with corresponding AccountIndex ${ix}`);
+ * });
+ * ```
+ */
 export function idAndIndex (api: ApiInterface$Rx) {
   return (address?: Address | AccountId | AccountIndex | string | null): Observable<AccountIdAndIndex> => {
     try {

packages/api-derive/src/accounts/idToIndex.ts

@@ -10,6 +10,20 @@ import { AccountId, AccountIndex } from '@polkadot/types';
 import { indexes, AccountIndexes } from './indexes';
 import { drr } from '../util/drr';
 
+/**
+ * @name idToIndex
+ * @param {( AccountId | string )} accountId - An accounts Id in different formats.
+ * @returns Returns the corresponding AccountIndex.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * const ALICE = '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY';
+ * api.derive.accounts.idToIndex(ALICE, (accountIndex) => {
+ *   console.log(`The AccountIndex of ${ALICE} is ${accountIndex}`);
+ * });
+ * ```
+ */
 export function idToIndex (api: ApiInterface$Rx) {
   return (accountId: AccountId | string): Observable<AccountIndex | undefined> =>
     indexes(api)()

packages/api-derive/src/accounts/indexToId.ts

@@ -10,6 +10,19 @@ import { AccountId, AccountIndex, Vector } from '@polkadot/types';
 
 import { drr } from '../util/drr';
 
+/**
+ * @name indexToId
+ * @param {( AccountIndex | string )} accountIndex - An accounts index in different formats.
+ * @returns Returns the corresponding AccountId.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.accounts.indexToId('F7Hs', (accountId) => {
+ *   console.log(`The AccountId of F7Hs is ${accountId}`);
+ * });
+ * ```
+ */
 export function indexToId (api: ApiInterface$Rx) {
   return (_accountIndex: AccountIndex | string): Observable<AccountId> => {
     const querySection = api.query.indices || api.query.balances;

packages/api-derive/src/accounts/indexes.ts

@@ -15,9 +15,19 @@ export type AccountIndexes = { [index: string]: AccountIndex };
 const enumsetSize = ENUMSET_SIZE.toNumber();
 
 /**
- * Returns all the indexes on the system - this is an unwieldly query since it loops through
+ * @name indexes
+ * @returns Returns all the indexes on the system.
+ * @description This is an unwieldly query since it loops through
  * all of the enumsets and returns all of the values found. This could be up to 32k depending
  * on the number of active accounts in the system
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.accounts.indexes((indexes) => {
+ *   console.log('All existing AccountIndexes', indexes);
+ * });
+ * ```
  */
 export function indexes (api: ApiInterface$Rx) {
   return (): Observable<AccountIndexes> => {

packages/api-derive/src/balances/all.ts

@@ -14,6 +14,22 @@ import { drr } from '../util/drr';
 
 const EMPTY_ACCOUNT = new AccountId();
 
+/**
+ * @name all
+ * @param {( ccountIndex | AccountId | Address | string )} address - An accounts Id in different formats.
+ * @returns An object containing the combined results of the storage queries for
+ * all relevant fees as declared in the substrate chain spec.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * const ALICE = 'F7Hs';
+ *
+ * api.derive.balances.all(ALICE, ([accountId, lockedBalance]) => {
+ *   console.log(`The account ${accountId} has a locked balance ${lockedBalance} units.`);
+ * });
+ * ```
+ */
 export function all (api: ApiInterface$Rx) {
   return (address: AccountIndex | AccountId | Address | string): Observable<DerivedBalances> => {
     return idAndIndex(api)(address).pipe(

packages/api-derive/src/balances/fees.ts

@@ -10,6 +10,19 @@ import BN from 'bn.js';
 import { DerivedFees } from '../types';
 import { drr } from '../util/drr';
 
+/**
+ * @name fees
+ * @returns An object containing the combined results of the storage queries for
+ * all relevant fees as declared in the substrate chain spec.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * api.derive.balances.fees(([creationFee, transferFee]) => {
+ *   console.log(`The fee for creating a new account on this chain is ${transferFee} units. The fee required for making a transfer is ${transferFee} units.`);
+ * });
+ * ```
+ */
 export function fees (api: ApiInterface$Rx) {
   return (): Observable<DerivedFees> => {
     return (api.queryMulti([

packages/api-derive/src/chain/bestNumber.ts

@@ -10,7 +10,8 @@ import { BlockNumber, Header } from '@polkadot/types';
 import { drr } from '../util/drr';
 
 /**
- * @description Get the latest block number.
+ * @name bestNumber
+ * @returns The latest block number.
  * @example
  * <BR>
  *

packages/api-derive/src/chain/bestNumberFinalized.ts

@@ -10,8 +10,10 @@ import { BlockNumber, Header } from '@polkadot/types';
 import { drr } from '../util/drr';
 
 /**
+ * @name bestNumberFinalized
+ * @returns A BlockNumber
  * @description Get the latest finalized block number.
- * example
+ * @example
  * <BR>
  *
  * ```javascript

packages/api-derive/src/chain/bestNumberLag.ts

@@ -12,6 +12,8 @@ import { bestNumber } from './bestNumber';
 import { bestNumberFinalized } from './bestNumberFinalized';
 
 /**
+ * @name bestNumberLag
+ * @returns A number of blocks
  * @description Calculates the lag between finalized head and best head
  * @example
  * <BR>

packages/api-derive/src/chain/getHeader.ts

@@ -11,8 +11,10 @@ import { drr } from '../util/drr';
 import { HeaderAndValidators } from './subscribeNewHead';
 
 /**
- * @description Get the a specific block header and extend it with the author
- * @param hash: Uint8Array | string
+ * @name bestNumberFinalized
+ * @param {( Uint8Array | string )} hash - A block hash as U8 array or string.
+ * @returns An array containing the block header and the block author
+ * @description Get a specific block header and extend it with the author
  * @example
  * <BR>
  *

packages/api-derive/src/chain/subscribeNewHead.ts

@@ -12,7 +12,9 @@ import { drr } from '../util/drr';
 export type HeaderAndValidators = [Header, Array<AccountId>];
 
 /**
- * @description Subscribe to block headers and extend it with the author
+ * @name subscribeNewHead
+ * @returns An array containing the block header and the block author
+ * @description An observable of the current block header and it's author
  * @example
  * <BR>
  *