Merge pull request #304 from trustlines-protocol/feature/md-typedoc

Feature/md typedoc

Author: dohaki

.gitignore

@@ -8,6 +8,7 @@ doc.json
 *~
 package-lock.json
 addresses.json
+docs/api
 
 # code coverage
 .nyc_output

README.md

@@ -109,6 +109,12 @@ yarn test:e2e
 You have to have all components of the trustlines protocol running.
 A convenient way to achieve this is by using our [end2end](https://github.com/trustlines-protocol/end2end) setup.
 
+## Documentation
+
+You can find the documentation for the trustlines-clientlib [here](https://dev.trustlines.network/docs/clientlib/clientlib.html).
+The underlying markdown files of the documentation can be found in this repository under the `./docs` directory.
+To generate the [typedoc](https://typedoc.org/) API reference documentation for this library run `yarn doc`.
+
 ## Running injected web3 example
 
 To run the example make sure to have [MetaMask](https://metamask.io/) installed and connected to a JSON RPC.

docs/api-reference-index.md

@@ -0,0 +1,11 @@
+# API Reference
+
+## Table of Content
+
+- [`TLNetwork`](./api/classes/_tlnetwork_.tlnetwork.md)
+  - [`CurrencyNetwork`](./api/classes/_currencynetwork_.currencynetwork.md)
+  - [`User`](./api/classes/_user_.user.md)
+  - [`Trustline`](./api/classes/_trustline_.trustline.md)
+  - [`Payment`](./api/classes/_payment_.payment.md)
+  - [`Events`](./api/classes/_events_.events.md)
+- [`Utils`](<(./api/modules/_utils_.md)>>)

package.json

@@ -80,7 +80,7 @@
     "ts-node": "^7.0.0",
     "tslint": "^5.17.0",
     "tslint-config-prettier": "^1.18.0",
-    "typedoc": "^0.14.2",
+    "typedoc": "^0.16.9",
     "types-ethereumjs-util": "0.0.8",
     "typescript": "^2.9.2",
     "webpack": "^4.16.0",
@@ -94,6 +94,7 @@
     "rxjs": "^5.4.1",
     "simple-jsonrpc-js": "0.0.10",
     "trustlines-contracts-abi": "dev",
+    "typedoc-plugin-markdown": "^2.2.16",
     "ws": "^6.2.1"
   }
 }

src/CurrencyNetwork.ts

@@ -15,11 +15,20 @@ import {
 } from './typings'
 
 /**
- * The CurrencyNetwork class contains all functions relevant for retrieving
- * currency network related information.
+ * The [[CurrencyNetwork]] class contains all functions relevant for retrieving currency network related information.
+ * It is meant to be called via a [[TLNetwork]] instance like:
+ * ```typescript
+ * const tlNetwork = new TLNetwork(...)
+ *
+ * // Get all networks
+ * tlNetwork.currencyNetwork.getAll().then(
+ *  networks => console.log("All networks:", networks)
+ * )
+ * ```
  */
 export class CurrencyNetwork {
   /**
+   * @hidden
    * Returns general and interest rate decimals for given currency network.
    * @param networkAddress Currency network to get decimals for.
    * @param decimalsOptions Optional provided decimals if known.
@@ -31,6 +40,7 @@ export class CurrencyNetwork {
 
   private provider: TLProvider
 
+  /** @hidden */
   constructor(provider: TLProvider) {
     this.provider = provider
     this.getDecimals = this._getDecimalsCached()
@@ -118,6 +128,7 @@ export class CurrencyNetwork {
   }
 
   /**
+   * @hidden
    * Returns a mapping from network address to respective decimals.
    * @param networkAddresses List of currency networks.
    */
@@ -138,6 +149,7 @@ export class CurrencyNetwork {
   }
 
   /**
+   * @hidden
    * Returns true or false whether given address is a registered currency network.
    * @param contractAddress Address which should be checked.
    */

src/Event.ts

@@ -23,12 +23,26 @@ const TOKEN = 'Token'
 
 /**
  * The Event class contains all methods related to retrieving event logs.
+ * It is meant to be called via a [[TLNetwork]] instance like:
+ * ```typescript
+ * const tlNetwork = new TLNetwork(
+ *  //...
+ * )
+ *
+ * // Get transfer logs
+ * tlNetwork.event.get(
+ *  // ...
+ * ).then(
+ *  events => console.log("Events of loaded user:", events)
+ * )
+ * ```
  */
 export class Event {
   private currencyNetwork: CurrencyNetwork
   private provider: TLProvider
   private user: User
 
+  /** @hidden */
   constructor(params: {
     currencyNetwork: CurrencyNetwork
     provider: TLProvider
@@ -43,7 +57,7 @@ export class Event {
    * @hidden
    * Returns event logs of loaded user in a specified currency network.
    * @param networkAddress Address of a currency network.
-   * @param filter Event filter object. See `EventFilterOptions` for more information.
+   * @param filter Event filter object. See [[EventFilterOptions]] for more information.
    * @param filter.type Available event types are `Transfer`, `TrustlineUpdateRequest` and `TrustlineUpdate`.
    * @param filter.fromBlock Start of block range for event logs.
    */
@@ -73,7 +87,7 @@ export class Event {
 
   /**
    * Returns event logs of loaded user in all currency networks.
-   * @param filter Event filter object. See `EventFilterOptions` for more information.
+   * @param filter Event filter object. See [[EventFilterOptions]] for more information.
    * @param filter.type Available event types are:
    *                    CurrencyNetwork -> `Transfer`, `TrustlineUpdateRequest` and `TrustlineUpdate`
    *                    EthWrapper -> `Transfer`, `Deposit` and `Withdrawal`
@@ -121,6 +135,7 @@ export class Event {
   }
 
   /**
+   * @hidden
    * Fetches decimals for given event logs and formats them so that all numerical
    * values are `Amount` objects.
    * @param rawEvents trustlines network events
@@ -162,6 +177,7 @@ export class Event {
   }
 
   /**
+   * @hidden
    * Returns a mapping from address to decimals
    * @param addressesMap mapping from address to whether given address is a CurrencyNetwork
    *                     or Token contract.

src/Payment.ts

@@ -22,8 +22,20 @@ import {
 } from './typings'
 
 /**
- * The Payment class contains all payment related functions. This includes
- * trustline transfers and normal ETH transfers.
+ * The Payment class contains all payment related functions. This includes trustline transfers and TLC transfers.
+ * It is meant to be called via a [[TLNetwork]] instance like:
+ * ```typescript
+ * const tlNetwork = new TLNetwork(
+ *  //...
+ * )
+ *
+ * // Get transfer logs
+ * tlNetwork.payment.get(
+ *  // ...
+ * ).then(
+ *  payments => console.log("Payments of loaded user:", payments)
+ * )
+ * ```
  */
 export class Payment {
   private currencyNetwork: CurrencyNetwork
@@ -32,6 +44,7 @@ export class Payment {
   private transaction: Transaction
   private user: User
 
+  /** @hidden */
   constructor(params: {
     event: Event
     user: User
@@ -52,7 +65,7 @@ export class Payment {
    * @param receiverAddress Address of receiver of transfer.
    * @param value Amount to transfer in biggest unit,
    *              i.e. 1.5 if currency network has 2 decimals.
-   * @param options Optional payment options. See `PaymentOptions` for more information.
+   * @param options Optional payment options. See [[PaymentOptions]] for more information.
    * @param options.networkDecimals Decimals of currency network can be provided manually.
    * @param options.maximumHops Max. number of hops for transfer.
    * @param options.maximumFees Max. transfer fees user is willing to pay.
@@ -122,7 +135,7 @@ export class Payment {
    * Prepares a ethereum transaction object for a ETH transfer, where loaded user is the sender.
    * @param receiverAddress Address of receiver of transfer.
    * @param value Amount of ETH to transfer.
-   * @param options Payment options. See `PaymentOptions` for more information.
+   * @param options Payment options. See [[PaymentOptions]] for more information.
    * @param options.gasPrice Custom gas price.
    * @param options.gasLimit Custom gas limit.
    */
@@ -159,7 +172,7 @@ export class Payment {
    * @param receiverAddress Address of receiver of transfer.
    * @param value Amount to transfer in biggest unit,
    *              i.e. 1.23 if currency network has 2 decimals.
-   * @param options Payment options. See `PaymentOptions` for more information.
+   * @param options Payment options. See [[PaymentOptions]] for more information.
    * @param options.feePayer Either `sender` or `receiver`. Specifies who pays network fees.
    * @param options.networkDecimals Decimals of currency network can be provided manually.
    * @param options.maximumHops Max. number of hops for transfer.
@@ -211,7 +224,7 @@ export class Payment {
   /**
    * Returns transfer event logs of loaded user in a specified currency network.
    * @param networkAddress Address of currency network.
-   * @param filter Event filter object. See `EventFilterOptions` for more information.
+   * @param filter Event filter object. See [[EventFilterOptions]] for more information.
    */
   public get(
     networkAddress: string,

src/TLNetwork.ts

@@ -30,22 +30,17 @@ import { TLNetworkConfig } from './typings'
 import { IdentityWallet } from './wallets/IdentityWallet'
 
 /**
- * The TLNetwork class is the single entry-point into the trustline-network.js library.
- * It contains all of the library's functionality and all calls to the library should be made through a TLNetwork instance.
+ * The TLNetwork class is the single entry-point into the trustlines-clientlib.
+ * It contains all of the library's functionality and all calls to the library should be made through a `TLNetwork` instance.
  */
 export class TLNetwork {
   /**
    * User instance containing all user/keystore related methods.
    */
   public user: User
-  /**
-   * @hidden
-   * Transaction instance containing all transaction related methods.
-   */
-  public transaction: Transaction
   /**
    * Payment instance containing all methods for creating trustline transfers
-   * and ETH transfers.
+   * and TLC transfers.
    */
   public payment: Payment
   /**
@@ -57,23 +52,30 @@ export class TLNetwork {
    * related information.
    */
   public currencyNetwork: CurrencyNetwork
+  /**
+   * Event instance for retrieving and formatting event logs.
+   */
+  public event: Event
   /**
    * @hidden
+   * Transaction instance containing all transaction related methods.
    */
-  public contact: Contact
+  public transaction: Transaction
   /**
-   * Event instance for retrieving and formatting event logs.
+   * @hidden
    */
-  public event: Event
+  public contact: Contact
   /**
    * Exchange instance containing all methods for making and taking orders.
+   * @hidden
    */
   public exchange: Exchange
   /**
    * @hidden
    */
   public messaging: Messaging
   /**
+   * @hidden
    * EthWrapper instance for wrapping and unwrapping ETH.
    */
   public ethWrapper: EthWrapper
@@ -95,8 +97,8 @@ export class TLNetwork {
   public provider: TLProvider
 
   /**
-   * Initiates a new TLNetwork instance that provides the public interface to trustlines-network library.
-   * @param config Configuration object. See type `tlNetworkConfig` for more information.
+   * Initiates a new TLNetwork instance that provides the public interface to trustlines-clientlib.
+   * @param config Configuration object. See [[TLNetworkConfig]] for more information.
    */
   constructor(config: TLNetworkConfig = {}) {
     const {
@@ -181,13 +183,19 @@ export class TLNetwork {
     })
   }
 
+  /**
+   * @hidden
+   */
   public setProvider(provider: TLProvider): void {
     if (!(provider instanceof RelayProvider)) {
       throw new Error('Provider not supported.')
     }
     this.provider = provider
   }
 
+  /**
+   * @hidden
+   */
   public setSigner(web3Provider, wallet: TLWallet): void {
     const signer: TLSigner = web3Provider
       ? new Web3Signer(new ethers.providers.Web3Provider(web3Provider))
@@ -205,6 +213,9 @@ export class TLNetwork {
     this.signer = signer
   }
 
+  /**
+   * @hidden
+   */
   public setWallet(
     walletType: string,
     provider: TLProvider,