Structuring

docs/SUMMARY.md

@@ -6,10 +6,6 @@
 - [rpc-provider](rpc-provider/README.md)
   - [HttpProvider](rpc-provider/classes/_http_index_.httpprovider.md)
   - [WsProvider](rpc-provider/classes/_ws_index_.wsprovider.md)
-- [rpc-core](rpc-core/README.md)
-  - [Rpc](rpc-core/classes/_index_.rpc.md)
-- [rpc-rx](rpc-rx/README.md)
-  - [RpcRx](rpc-rx/classes/_index_.rpcrx.md)
 
 ## Examples
 

packages/api/src/promise/index.ts

@@ -18,9 +18,14 @@ import { StorageFunction } from '@polkadot/types/StorageKey';
 /**
  * # @polkadot/api/promise
  *
+ * ## Overview
+ *
+ * @name ApiPromise
+ * @description
  * ApiPromise is a standard JavaScript wrapper around the RPC and interfaces on the Polkadot network. As a full Promise-based, all interface calls return Promises, including the static `.create(...)`. Subscription calls utilise standard JavaScript-convention `(error, value)` callbacks.
  *
  * The API is well suited to real-time applications where either the single-shot state is needed or use is to be made of the subscription-based features of Polkadot (and Substrate) clients.
+ * @see [[ApiRx]]
  *
  * ## Usage
  *

packages/api/src/rx/index.ts

@@ -23,9 +23,14 @@ const l = logger('api-rx');
 /**
  * # @polkadot/api/rx
  *
+ *  ## Overview
+ *
+ * @name ApiRx
+ * @description
  * ApiRx is a powerfull RxJS Observable wrapper around the RPC and interfaces on the Polkadot network. As a full Observable API, all interface calls return RxJS Observables, including the static `.create(...)`. In the same fashion and subscription-based methods return long-running Observables that update with the latest values.
  *
  * The API is well suited to real-time applications where the latest state is needed, unlocking the subscription-based features of Polkadot (and Substrate) clients. Some familiarity with RxJS is a requirement to use the API, however just understanding `.subscribe` and `.pipe` on Observables will unlock full-scale use thereof.
+ * @see [[ApiPromise]]
  *
  * ## Usage
  *

packages/rpc-core/src/index.ts

@@ -14,8 +14,6 @@ import assert from '@polkadot/util/assert';
 import ExtError from '@polkadot/util/ext/error';
 import isFunction from '@polkadot/util/is/function';
 
-import defaults from './defaults';
-
 /**
  * @name Rpc
  * @summary The API may use a HTTP or WebSockets provider.
@@ -51,7 +49,7 @@ export default class Rpc implements RpcInterface {
    * Default constructor for the Api Object
    * @param  {ProviderInterface} provider An API provider using HTTP or WebSocket
    */
-  constructor (provider: ProviderInterface = new WsProvider(defaults.WS_URL)) {
+  constructor (provider: ProviderInterface = new WsProvider()) {
     assert(provider && isFunction(provider.send), 'Expected Provider to API create');
 
     this._provider = provider;

packages/rpc-provider/README.md

@@ -1,6 +1,12 @@
 # @polkadot/rpc-provider
 
-Generic transport providers to handle the transport of method calls to and from Polkadot clients from applications interacting with it. Generally, unless you are operating at a low-level and taking care of encoding and decoding of parameters/results, it won't be directly used. API interfaces building on top these providers can support various transports with the same underlying interfaces.
+Generic transport providers to handle the transport of method calls to and from Polkadot clients from applications interacting with it. It provides an interface to making RPC class and is generally, unless you are operating at a low-level and taking care of encoding and decoding of parameters/results, it won't be directly used, rather only passed to a higher-level interface.
+
+## Provider Selection
+
+There are two flavours of the providers provided, one allowing for using HTTP as a transport machanism, the other using WebSockets. It is generally recommended to use the [[WsProvider]] since in addition to standard calls, it allows for subscriptions where nes changes can be pushed from the node to the client.
+
+Both providers are usable (as is the API), in both browser-based and Node.js environments. Polyfills for unsupported functionality is automatically applied based on feature-detection.
 
 ## Usage
 
@@ -10,13 +16,26 @@ Installation -
 yarn add @polkadot/rpc-provider
 ```
 
-Initialisation -
+WebSocket Initialisation -
 
 ```js
 import WsProvider from '@polkadot/rpc-provider/ws';
 
-const provider = new WsProvider('http://127.0.0.1:9944');
+// this is the actual default endpoint
+const provider = new WsProvider('ws://127.0.0.1:9944');
 const version = await provider.send('client_version', []);
 
-console.log('clientVersion', version);
+console.log('client version', version);
+```
+
+HTTP Initialisation -
+
+```js
+import { HttpProvider } from '@polkadot/rpc-provider';
+
+// this is the actual default endpoint
+const provider = new HttpProvider('http://127.0.0.1:9933');
+const version = await provider.send('chain_getBlockHash', []);
+
+console.log('latest block Hash', hash);
 ```

packages/rpc-core/src/defaults.ts → packages/rpc-provider/src/defaults.ts

@@ -1,9 +1,11 @@
-// Copyright 2017-2018 @polkadot/rpc-core authors & contributors
+// Copyright 2017-2018 @polkadot/rpc-provider authors & contributors
 // This software may be modified and distributed under the terms
 // of the ISC license. See the LICENSE file for details.
 
+const HTTP_URL = 'http://127.0.0.1:9933';
 const WS_URL = 'ws://127.0.0.1:9944';
 
 export default {
+  HTTP_URL,
   WS_URL
 };

packages/rpc-provider/src/http/index.ts

@@ -12,10 +12,13 @@ import assert from '@polkadot/util/assert';
 import logger from '@polkadot/util/logger';
 
 import coder from '../coder/json';
+import defaults from '../defaults';
 
 const ERROR_SUBSCRIBE = 'HTTP Provider does not have subscriptions, use WebSockets instead';
 
 /**
+ * # @polkadot/rpc-provider/https
+ *
  * @name HttpProvider
  * @summary The HTTP Provider allows sending requests using HTTP to a HTTP RPC server TCP port.
  * @description It does not support subscriptions so you won't be able to listen to events
@@ -25,11 +28,11 @@ const ERROR_SUBSCRIBE = 'HTTP Provider does not have subscriptions, use WebSocke
  * <BR>
  *
  * ```javascript
- * import Rpc from '@polkadot/rpc-core';
+ * import Api from '@polkadot/api/promise';
  * import HttpProvider from '@polkadot/rpc-provider/http';
  *
  * const provider = new HttpProvider('http://127.0.0.1:9933');
- * const api = new Rpc(provider);
+ * const api = new Api(provider);
  * ```
  *
  * @see [[WsProvider]]
@@ -42,7 +45,7 @@ export default class HttpProvider implements ProviderInterface {
   /**
    * @param {string} endpoint The endpoint url starting with http://
    */
-  constructor (endpoint: string) {
+  constructor (endpoint: string = defaults.HTTP_URL) {
     assert(/^(https|http):\/\//.test(endpoint), `Endpoint should start with 'http://', received '${endpoint}'`);
 
     this.coder = coder();

packages/rpc-provider/src/ws/index.ts

@@ -15,6 +15,7 @@ import isUndefined from '@polkadot/util/is/undefined';
 import logger from '@polkadot/util/logger';
 
 import coder from '../coder/json';
+import defaults from '../defaults';
 
 type SubscriptionHandler = {
   callback: ProviderInterface$Callback,
@@ -38,6 +39,8 @@ interface WSProviderInterface extends ProviderInterface {
 }
 
 /**
+ * # @polkadot/rpc-provider/ws
+ *
  * @name WsProvider
  * @summary The WebSocket Provider allows sending requests using WebSocket to a WebSocket RPC server TCP port.
  * @description Unlike the [[HttpProvider]], it does support subscriptions and allows
@@ -46,11 +49,11 @@ interface WSProviderInterface extends ProviderInterface {
  * <BR>
  *
  * ```javascript
- * import Rpc from '@polkadot/rpc-core';
+ * import Api from '@polkadot/api/promise';
  * import WsProvider from '@polkadot/rpc-provider/ws';
  *
  * const provider = new WsProvider('ws://127.0.0.1:9944');
- * const api = new Rpc(provider);
+ * const api = new Api(provider);
  * ```
  *
  * @see [[HttpProvider]]
@@ -77,7 +80,7 @@ export default class WsProvider implements WSProviderInterface {
    * @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) {
+  constructor (endpoint: string = defaults.WS_URL, autoConnect: boolean = true) {
     assert(/^(wss|ws):\/\//.test(endpoint), `Endpoint should start with 'ws://', received '${endpoint}'`);
 
     this._eventemitter = new EventEmitter();