WIP

book.json

@@ -2,7 +2,8 @@
   "title": "Polkadot API Book",
   "gitbook": ">=2.4.0",
   "plugins": [
-    "include-codeblock"
+    "include-codeblock",
+    "mermaid-gb3"
   ],
   "root": "docs",
   "pluginsConfig": {}

package.json

@@ -25,6 +25,7 @@
     "@polkadot/ts": "^0.1.30"
   },
   "dependencies": {
-    "gitbook-plugin-include-codeblock": "^3.2.2"
+    "gitbook-plugin-include-codeblock": "^3.2.2",
+    "gitbook-plugin-mermaid-gb3": "^2.1.0"
   }
 }

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

@@ -17,16 +17,16 @@ const ERROR_SUBSCRIBE = 'HTTP Provider does not have subscriptions, use WebSocke
 
 /**
  * @name HttpProvider
- * @summary The HTTP Provider allows sending requests using HTTP.
+ * @summary The HTTP Provider allows sending requests using HTTP to HTTP RPC server TCP port
  * @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';
+ * import HttpProvider from '@polkadot/api-provider/http';
  * <BR>
- * const provider = new WsProvider('http://127.0.0.1:9933');
+ * const provider = new HttpProvider('http://127.0.0.1:9933');
  * const api = createApi(provider);
  * </CODE></PRE>
  *

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

@@ -39,7 +39,7 @@ interface WSProviderInterface extends ProviderInterface {
 
 /**
  * @name WsProvider
- * @summary The WebSocket Provider allows sending requests using WebSocket.
+ * @summary The WebSocket Provider allows sending requests using WebSocket to WebSocket RPC server TCP port.
  * @description Unlike the [[HttpProvider]], it does support subscriptions and allows
  * listening to events such as new blocks or balance changes.
  * @example

packages/api/src/index.ts

@@ -17,12 +17,21 @@ 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.
+ *
+ * ```mermaid
+ * graph LR;
+ *   A[Api] --> |protocol| B{Decision};
+ *   B --> |Http| D[HttpProvider];
+ *   B --> |WebSockets| E[WsProvider];
+ *   D --> |endpoint| F[https://127.0.0.1:9933]
+ *   E --> |endpoint| G[ws://127.0.0.1:9944]
+ * ```
  * @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 provider = new WsProvider('ws://127.0.0.1:9944');
  * const api = new Api(provider);
  * </CODE></PRE>
  */