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}`;
packages/api-rx/src/index.ts
+6 -2
View File
@@ -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;
packages/api/src/index.ts
+12 -5
View File
@@ -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 }) =>