diff --git a/packages/api-provider/src/http/index.ts b/packages/api-provider/src/http/index.ts
index bd3d6c7072..08624755d3 100644
--- a/packages/api-provider/src/http/index.ts
+++ b/packages/api-provider/src/http/index.ts
@@ -17,7 +17,7 @@ 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 a 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]].
  *
@@ -25,11 +25,11 @@ const ERROR_SUBSCRIBE = 'HTTP Provider does not have subscriptions, use WebSocke
  * <BR>
  *
  * ```javascript
- * import createApi from '@polkadot/api';
- * import WsProvider from '@polkadot/api-provider/ws';
+ * import Api from '@polkadot/api';
+ * import HttpProvider from '@polkadot/api-provider/http';
  *
- * const provider = new WsProvider('http://127.0.0.1:9933');
- * const api = createApi(provider);
+ * const provider = new HttpProvider('http://127.0.0.1:9933');
+ * const api = new Api(provider);
  * ```
  *
  * @see [[WsProvider]]
diff --git a/packages/api-provider/src/ws/index.ts b/packages/api-provider/src/ws/index.ts
index b42548b316..82510a4bb5 100644
--- a/packages/api-provider/src/ws/index.ts
+++ b/packages/api-provider/src/ws/index.ts
@@ -39,18 +39,18 @@ 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 a 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
  * <BR>
  *
  * ```javascript
- * import createApi from '@polkadot/api';
+ * import Api from '@polkadot/api';
  * import WsProvider from '@polkadot/api-provider/ws';
  *
  * const provider = new WsProvider('ws://127.0.0.1:9944');
- * const api = createApi(provider);
+ * const api = new Api(provider);
  * ```
  *
  * @see [[HttpProvider]]
@@ -182,7 +182,7 @@ export default class WsProvider extends E3.EventEmitter implements WSProviderInt
    *
    * ```javascript
    * const provider = new WsProvider('ws://127.0.0.1:9944');
-   * const api = createApi(provider);
+   * const api = new Api(provider);
    *
    * api.state.storage([[storage.balances.freeBalance, <Address>]], (_, values) => {
    *   console.log(values)
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index 4655d6d4ae..7912a850a2 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -24,7 +24,7 @@ import isFunction from '@polkadot/util/is/function';
  * import Api from '@polkadot/api';
  * import WsProvider from '@polkadot/api-provider/ws';
  *
- * 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);
  * ```
  */
@@ -61,7 +61,7 @@ export default class Api implements ApiInterface {
    * <BR>
    *
    * ```javascript
-   * import Api from '@polkadot/Api';
+   * import Api from '@polkadot/api';
    *
    * Api.signature({ name: 'test_method', params: [ { name: 'dest', type: 'Address' } ], type: 'Address' }); // => test_method (dest: Address): Address
    * ```