quantus/api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: Fixes #154 Modify TypeDocs that change the source to resolve rendering correctly (#203)

Browse Source 
* 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
This commit is contained in:
Luke Schoen
2018-10-05 08:42:32 +02:00
committed by Jaco Greeff
parent f77d75086f
commit fd596a1eb4
4 changed files with 58 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/api-provider/src/http/index.ts
+18 -8
View File
@@ -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);
packages/api-provider/src/ws/index.ts
+22 -11
View File
@@ -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}`;