From fd596a1eb4ab89e4350cd2bef4d0a0b073f13e49 Mon Sep 17 00:00:00 2001
From: Luke Schoen <ltfschoen@users.noreply.github.com>
Date: Fri, 5 Oct 2018 07:42:32 +0100
Subject: [PATCH] fix: Fixes #154 Modify TypeDocs that change the source to
 resolve rendering correctly (#203)

* fix: Modify TypeDocs that change the source to resolve rendering correctly

* Add TypeDoc/TSDoc labels

* Use HTML <BR> element in TypeDoc to generate new lines even to achieve a newline between lines of code

* Use HTML <PRE><CODE> combination in TypeDoc for multiple line code generation

* Add missing TypeDocs for HTTP `constructor` and `send` for HTTP and WS

* Remove unnecessary assignment of `= true` default value in TypeDoc @param value and clean up text alignment

* Verified that it displays correctly in development environment by running `yarn; yarn polkadot-dev-build-docs; yarn gitbook serve`, and then navigating to localhost:4000

* fix: remove signature that was used with jsdocs flowtype
---
 packages/api-provider/src/http/index.ts | 26 +++++++++++++------
 packages/api-provider/src/ws/index.ts   | 33 ++++++++++++++++---------
 packages/api-rx/src/index.ts            |  8 ++++--
 packages/api/src/index.ts               | 17 +++++++++----
 4 files changed, 58 insertions(+), 26 deletions(-)

diff --git a/packages/api-provider/src/http/index.ts b/packages/api-provider/src/http/index.ts
index 3ed8b667d7..9b4235a49e 100644
--- a/packages/api-provider/src/http/index.ts
+++ b/packages/api-provider/src/http/index.ts
@@ -16,16 +16,19 @@ import coder from '../coder/json';
 const ERROR_SUBSCRIBE = 'HTTP Provider does not have subscriptions, use WebSockets instead';
 
 /**
- * The HTTP Provider allows sending requests using HTTP. it does not support subscriptions
- * so you won´t be able to listen to events such as new blocks or balance changes.
- * It is usually preferrable using the [[WsProvider]].
+ * @name HttpProvider
+ * @summary The HTTP Provider allows sending requests using HTTP.
+ * @description It does not support subscriptions so you won't be able to listen to events
+ * such as new blocks or balance changes. It is usually preferrable using the [[WsProvider]].
  *
  * @example
+ * <BR><PRE><CODE>
  * import createApi from '@polkadot/api';
  * import WsProvider from '@polkadot/api-provider/ws';
- *
+ * <BR>
  * const provider = new WsProvider('http://127.0.0.1:9933');
  * const api = createApi(provider);
+ * </CODE></PRE>
  *
  * @see [[WsProvider]]
  */
@@ -34,6 +37,9 @@ export default class HttpProvider implements ProviderInterface {
   private endpoint: string;
   private l: Logger;
 
+  /**
+   * @param {string} endpoint The endpoint url starting with http://
+   */
   constructor (endpoint: string) {
     assert(/^(https|http):\/\//.test(endpoint), `Endpoint should start with 'http://', received '${endpoint}'`);
 
@@ -43,7 +49,7 @@ export default class HttpProvider implements ProviderInterface {
   }
 
   /**
-   * Whether the node is connected or not.
+   * @summary Whether the node is connected or not.
    * @return {boolean} true if connected
    */
   isConnected (): boolean {
@@ -51,12 +57,16 @@ export default class HttpProvider implements ProviderInterface {
   }
 
   /**
-   * Events are not supported with the HttpProvider, see [[WsProvider]].
+   * @summary Events are not supported with the HttpProvider, see [[WsProvider]].
+   * @description HTTP Provider does not have 'on' emitters. WebSockets should be used instead.
    */
   on (type: ProviderInterface$Emitted, sub: ProviderInterface$EmitCb): void {
     this.l.error(`HTTP Provider does not have 'on' emitters, use WebSockets instead`);
   }
 
+  /**
+   * @summary Send HTTP POST Request with Body to configured HTTP Endpoint.
+   */
   async send (method: string, params: Array<any>): Promise<any> {
     const body = this.coder.encodeJson(method, params);
     const response = await fetch(this.endpoint, {
@@ -77,7 +87,7 @@ export default class HttpProvider implements ProviderInterface {
   }
 
   /**
-   * Subscriptions are not supported with the HttpProvider, see [[WsProvider]].
+   * @summary Subscriptions are not supported with the HttpProvider, see [[WsProvider]].
    */
   async subscribe (types: string, method: string, params: Array<any>, cb: ProviderInterface$Callback): Promise<number> {
     this.l.error(ERROR_SUBSCRIBE);
@@ -86,7 +96,7 @@ export default class HttpProvider implements ProviderInterface {
   }
 
   /**
-   * Subscriptions are not supported with the HttpProvider, see [[WsProvider]].
+   * @summary Subscriptions are not supported with the HttpProvider, see [[WsProvider]].
    */
   async unsubscribe (type: string, method: string, id: number): Promise<boolean> {
     this.l.error(ERROR_SUBSCRIBE);
diff --git a/packages/api-provider/src/ws/index.ts b/packages/api-provider/src/ws/index.ts
index 2ed352be6c..4a152a0569 100644
--- a/packages/api-provider/src/ws/index.ts
+++ b/packages/api-provider/src/ws/index.ts
@@ -38,14 +38,18 @@ interface WSProviderInterface extends ProviderInterface {
 }
 
 /**
- * The WebSocket Provider allows sending requests using WebSocket. Unlike the [[HttpProvider]],
- * it does support subscriptions and allows listening to events such as new blocks or balance changes.
- *
+ * @name WsProvider
+ * @summary The WebSocket Provider allows sending requests using WebSocket.
+ * @description Unlike the [[HttpProvider]], it does support subscriptions and allows
+ * listening to events such as new blocks or balance changes.
  * @example
+ * <BR><PRE><CODE>
  * import createApi from '@polkadot/api';
  * import WsProvider from '@polkadot/api-provider/ws';
+ * <BR>
  * const provider = new WsProvider('ws://127.0.0.1:9944');
  * const api = createApi(provider);
+ * </CODE></PRE>
  *
  * @see [[HttpProvider]]
  */
@@ -67,8 +71,8 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
   private websocket: WebSocket | null;
 
   /**
-   * @param {string}     endpoint The endpoint url. Usually `ws://ip:9944` or `wss://ip:9944`
-   * @param {boolean =        true}        autoConnect Whether to connect automatically or not.
+   * @param {string}  endpoint    The endpoint url. Usually `ws://ip:9944` or `wss://ip:9944`
+   * @param {boolean} autoConnect Whether to connect automatically or not.
    */
   constructor (endpoint: string, autoConnect: boolean = true) {
     super();
@@ -91,7 +95,8 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
   }
 
   /**
-   * The [[WsProvider]] connects automatically by default. if you decided otherwise, you may
+   * @summary Manually connect
+   * @description The [[WsProvider]] connects automatically by default, however if you decided otherwise, you may
    * connect manually using this method.
    */
   connect (): void {
@@ -108,7 +113,7 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
   }
 
   /**
-   * Whether the node is connected or not.
+   * @summary Whether the node is connected or not.
    * @return {boolean} true if connected
    */
   isConnected (): boolean {
@@ -116,7 +121,7 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
   }
 
   /**
-   * Listens on events after having subscribed using the [[subscribe]] function.
+   * @summary Listens on events after having subscribed using the [[subscribe]] function.
    * @param  {ProviderInterface$Emitted} type Event
    * @param  {ProviderInterface$EmitCb}  sub  Callback
    * @return {this}                           [description]
@@ -125,6 +130,9 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
     return super.on(type, sub);
   }
 
+  /**
+   * @summary Send JSON data using WebSockets to configured HTTP Endpoint or queue.
+   */
   async send (method: string, params: Array<any>, subscription?: SubscriptionHandler): Promise<any> {
     return new Promise((resolve, reject): void => {
       try {
@@ -159,7 +167,8 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
   }
 
   /**
-   * Allows subscribing to a specific event.
+   * @name subscribe
+   * @summary Allows subscribing to a specific event.
    * @param  {string}                     type     Subscription type
    * @param  {string}                     method   Subscription method
    * @param  {Array<any>}                 params   Parameters
@@ -167,14 +176,16 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
    * @return {Promise<number>}                     Promise resolving to the dd of the subscription you can use with [[unsubscribe]].
    *
    * @example
+   * <BR><PRE><CODE>
    * const provider = new WsProvider('ws://127.0.0.1:9944');
    * const api = createApi(provider);
-   *
+   * <BR>
    * api.state.storage([[storage.balances.freeBalance, <Address>]], (_, values) => {
    *   console.log(values)
    * }).then((subscriptionId) => {
    *   console.log('balance changes subscription id: ', subscriptionId)
    * })
+   * </CODE></PRE>
    */
   async subscribe (type: string, method: string, params: Array<any>, callback: ProviderInterface$Callback): Promise<number> {
     const id = await this.send(method, params, { callback, type });
@@ -183,7 +194,7 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
   }
 
   /**
-   * Allows unsubscribing to subscriptions made with [[subscribe]].
+   * @summary Allows unsubscribing to subscriptions made with [[subscribe]].
    */
   async unsubscribe (type: string, method: string, id: number): Promise<boolean> {
     const subscription = `${type}::${id}`;
diff --git a/packages/api-rx/src/index.ts b/packages/api-rx/src/index.ts
index 5b3a65a08d..590db2ec6a 100644
--- a/packages/api-rx/src/index.ts
+++ b/packages/api-rx/src/index.ts
@@ -21,14 +21,18 @@ type CachedMap = {
 };
 
 /**
- * An RxJs wrapper around the [[api]].
+ * @name RxApi
+ * @summary The RxJS API is a wrapper around the API.
+ * @description It allows wrapping API components with observables using RxJS.
  *
  * @example
+ * <BR><PRE><CODE>
  * import RxApi from '@polkadot/api';
  * import WsProvider from '@polkadot/api-provider/ws';
- *
+ * <BR>
  * const provider = new WsProvider('http://127.0.0.1:9944');
  * const rxapi = new RxApi(provider);
+ * </CODE></PRE>
  */
 export default class RxApi implements RxApiInterface {
   private _api: ApiInterface;
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index c2ca0e570f..f1e314ee62 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -14,12 +14,17 @@ import ExtError from '@polkadot/util/ext/error';
 import isFunction from '@polkadot/util/is/function';
 
 /**
+ * @name Api
+ * @summary The API may use a HTTP or WebSockets provider.
+ * @description It allows for querying a Polkadot Client Node.
  * @example
+ * <BR><PRE><CODE>
  * import Api from '@polkadot/api';
  * import WsProvider from '@polkadot/api-provider/ws';
- *
+ * <BR>
  * const provider = new WsProvider('http://127.0.0.1:9944');
  * const api = new Api(provider);
+ * </CODE></PRE>
  */
 export default class Api implements ApiInterface {
   private _provider: ProviderInterface;
@@ -46,14 +51,16 @@ export default class Api implements ApiInterface {
 
   /**
    * @name signature
-   * @signature jsonrpcSignature (method: InterfaceMethodDefinition): string
    * @summary Returns a string representation of the method with inputs and outputs.
    * @description
    * Formats the name, inputs and outputs into a human-readable string. This contains the input parameter names input types and output type.
-   * @example
-   *   import Api from '@polkadot/Api';
    *
-   *   Api.signature({ name: 'test_method', params: [ { name: 'dest', type: 'Address' } ], type: 'Address' }); // => test_method (dest: Address): Address
+   * @example
+   * <BR><PRE><CODE>
+   * import Api from '@polkadot/Api';
+   * <BR>
+   * Api.signature({ name: 'test_method', params: [ { name: 'dest', type: 'Address' } ], type: 'Address' }); // => test_method (dest: Address): Address
+   * </CODE></PRE>
    */
   static signature ({ method, params, type }: Method): string {
     const inputs = params.map(({ name, type }) =>