doc: add connection API documentation #300

nechaido · 2017-08-29T15:38:44Z

No description provided.

lundibundi · 2017-08-31T09:17:44Z

doc/api/connection.md

+
+Don't call this constructor manually unless you use custom tranport.
+Recommended approach is to call `connect()` function provided by these modules:
+* `net`


I think it's better to put md links here to the function descriptions even though there is no documentation for them right now to avoid missing them later on. See this and this.
Also, maybe you will add stubs for them?

lundibundi · 2017-08-31T09:31:59Z

doc/api/connection.md

+* callback(error, sessionId) — callback function to invoke after the handshake
+  is completed.
+  * error: `Error`.
+  * sessionId: `number`.


Ain't it a string? here

lundibundi · 2017-08-31T09:34:07Z

doc/api/connection.md

+#### connection.inspectInterface(interfaceName, callback)
+
+* interfaceName: `String` — name of an interface to inspect.
+* callback(error, proxy) — callback function to invoke after another side responds


...responds to the interface introspection?

lundibundi · 2017-08-31T09:35:00Z

doc/api/connection.md

+* callback(error, proxy) — callback function to invoke after another side responds
+  interface introspection.
+  * error: `Error`.
+  * proxy: `RemoteProxy` — remote proxy to the interface.


remote proxy for the interface?

lundibundi · 2017-08-31T09:36:25Z

doc/api/connection.md

+
+* interfaceName: `String` — name of an interface.
+* eventName: `String` — name of an event.
+* args: `Array` — event arguments as an array.


I think 'as an array' is redundant as we already have class written here.

lundibundi · 2017-08-31T09:37:19Z

doc/api/connection.md

+
+#### connection.stopHeartbeat()
+
+Stop sending heaarbeat messages.


s/heaarbeat/heartbeat/

lundibundi · 2017-08-31T09:40:47Z

doc/api/connection.md

+* event: `string` — name of an event.
+* handler(...args).
+
+Used to subscribe on this events:


Used to subscribe to the following events?

lundibundi · 2017-08-31T09:41:36Z

doc/api/connection.md

+* event: `string` — name of an event.
+* handler(...args).
+
+Used to subscribe on this events:


Maybe we should also add mandatory event arguments?

lundibundi · 2017-08-31T09:46:34Z

doc/api/connection.md

+* event: `string` — name of an event.
+* handler(...args).
+
+Used to subscribe on this events:


I think we should use the same style as in Connection here and in other Transport methods as this is just another class description. And in this place specifically, I think it's better to just state that Transport must emit the following events and avoid describing on method (Maybe just state that it has to be an EventEmitter).

lundibundi · 2017-08-31T09:49:03Z

doc/api/connection.md

+  * error: `Error`.
+  * connection: `Connection` — established connection.
+
+Optional, `new SimpleConnectPolicy().connect` will be used if not provided.


Put a link for new SimpleConnectPolicy().connect as in the first comment?

lundibundi

LGTM

belochub · 2017-09-26T10:54:40Z

doc/api/connection.md

+### new Connection(transport, server, client)
+
+* transport: `Transport`.
+* server: `Server` — JSTP server instance, used only for server—side parts


You shouldn't use em dash in word 'server-side', a hyphen must be used there.

belochub · 2017-09-26T10:55:26Z

doc/api/connection.md

+* server: `Server` — JSTP server instance, used only for server—side parts
+  of connections (optional, but either server or client is required).
+* client: [`Client`](./client.md#object-client) — JSTP client instance,
+  used only for client—side parts of connections (optional,


Same for 'client-side'.

belochub · 2017-09-26T10:57:22Z

doc/api/connection.md

+
+#### getTransport()
+
+* Returns: `Object`.


Doesn't this method return Transport?

belochub · 2017-09-26T10:58:35Z

doc/api/simple-connect-policy.md

+
+## Class: SimpleConnectPolicy
+
+Simple generic connection provider. Used for user-side connection.


Maybe it'll be better to replace 'user-side' with 'client-side'?

belochub · 2017-09-26T11:00:11Z

doc/api/tls.md

+  `'name@version'` or `{ name, version }`, where version must be
+  a valid semver range.
+* client: [`Client`](./client.md#object-client) — JSTP client instance, used
+  only for client—side parts of connections (optional, but either server or


Again dash instead of the hyphen in word 'client-side'.

belochub · 2017-09-26T11:01:20Z

doc/api/net.md

+  `'name@version'` or `{ name, version }`, where version must be
+  a valid semver range.
+* client: [`Client`](./client.md#object-client) — JSTP client instance, used
+  only for client—side parts of connections (optional, but either server or


Dash instead of the hyphen.

belochub · 2017-09-26T11:03:41Z

doc/api/net.md

+  only for client—side parts of connections (optional, but either server or
+  client is required).
+* options: `Object` — will be destructured and passed directly to connFactory.
+* callback(error, connection): — Optional callback that will be called when


You have a dash right next to a colon here, looks like the argument type provided in other cases is missing.

belochub · 2017-09-26T11:24:40Z

doc/api/simple-connect-policy.md

+  * connection: [`Connection`](./connection.md#class-connection).
+
+Should send handshake message with appropriate credentials. You can get client
+object provided upon connection creation with connection.client.


Shouldn't 'connection.client' be written in a monospaced font?

belochub · 2017-09-26T11:27:59Z

doc/api/tls.md

+* client: [`Client`](./client.md#object-client) — JSTP client instance, used
+  only for client-side parts of connections (optional, but either server or
+  client is required).
+* options: `Object` — will be destructured and passed directly to connFactory.


'connFactory' should probably be written in a monospaced font as well.

belochub

LGTM

PR-URL: #300 Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Mykola Bilochub <nbelochub@gmail.com>

nechaido · 2017-09-26T12:01:41Z

Landed in a5b5808.

PR-URL: #300 Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Mykola Bilochub <nbelochub@gmail.com>

nechaido added connection doc labels Aug 29, 2017

lundibundi reviewed Aug 31, 2017

View reviewed changes

lundibundi approved these changes Sep 2, 2017

View reviewed changes

nechaido force-pushed the doc-connection branch from bed0aa4 to 21c2c64 Compare September 11, 2017 10:14

belochub reviewed Sep 26, 2017

View reviewed changes

doc/api/connection.md Outdated

#### getTransport()

* Returns: `Object`.

Copy link

Member

belochub Sep 26, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doesn't this method return Transport?

belochub reviewed Sep 26, 2017

View reviewed changes

nechaido force-pushed the doc-connection branch from 4db0e5f to 6c4e17e Compare September 26, 2017 11:17

nechaido changed the title ~~doc: start documenting connection~~ doc: add connection API documentation Sep 26, 2017

belochub reviewed Sep 26, 2017

View reviewed changes

doc: add connection API documentation

a124871

nechaido force-pushed the doc-connection branch from 6c4e17e to a124871 Compare September 26, 2017 11:30

belochub approved these changes Sep 26, 2017

View reviewed changes

nechaido added a commit that referenced this pull request Sep 26, 2017

doc: add connection API documentation

a5b5808

PR-URL: #300 Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Mykola Bilochub <nbelochub@gmail.com>

nechaido closed this Sep 26, 2017

nechaido deleted the doc-connection branch September 26, 2017 12:01

belochub pushed a commit that referenced this pull request Jan 22, 2018

doc: add connection API documentation

deadc03

PR-URL: #300 Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Mykola Bilochub <nbelochub@gmail.com>

belochub pushed a commit that referenced this pull request Jan 22, 2018

doc: add connection API documentation

d4f40e0

PR-URL: #300 Reviewed-By: Denys Otrishko <shishugi@gmail.com> Reviewed-By: Mykola Bilochub <nbelochub@gmail.com>

belochub mentioned this pull request Jan 22, 2018

v1.0.0 proposal #311

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add connection API documentation #300

doc: add connection API documentation #300

nechaido commented Aug 29, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi Aug 31, 2017

lundibundi left a comment

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub Sep 26, 2017

belochub left a comment

nechaido commented Sep 26, 2017


		#### connection.stopHeartbeat()

		Stop sending heaarbeat messages.


		## Class: SimpleConnectPolicy

		Simple generic connection provider. Used for user-side connection.

doc: add connection API documentation #300

doc: add connection API documentation #300

Conversation

nechaido commented Aug 29, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lundibundi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

belochub left a comment

Choose a reason for hiding this comment

nechaido commented Sep 26, 2017