docs: use mkdocs and add documentation

doc/api/application.md

@@ -0,0 +1,71 @@
+# Application
+
+## Class: jstp.Application
+
+Generic application class. You are free to substitute it with other class with
+the same interface that suits your needs.
+
+### Constructor: new Application(name, api\[, eventHandlers\[, version\]\[, ssp\]\])
+
+- `name` [`<string>`][string] Application name that may contain version after
+  '@' (e.g. app@1.0.0). Version in name is preferred over 'version' parameter.
+- `api` [`<Object>`][object]
+  - `[interfaceName]` [`<Object>`][object] Keys with the arbitrary names that
+    will be used as the remote interface names.
+    - `[methodName]` [`<Function>`][function] Keys with the arbitrary names
+      that will be used as the remote method names.
+      - `connection` [`<Connection>`][connection]
+      - `...args` `<any>`
+      - `callback` [`<Function>`][function]
+- `eventHandlers` [`<Object>`][object]
+  - `[interfaceName]` [`<Object>`][object] Keys with the arbitrary names that
+    will be used as the remote interface names.
+    - `[eventName]` [`<Function>`][function] Keys with the arbitrary names that
+      will be used as the remote event names.
+      - `connection` [`<Connection>`][connection]
+      - `...args` `<any>`
+- `version` [`<string>`][string] If a version is not provided either here or in
+  `name`, `1.0.0` is used.
+- `ssp` [`<SessionStorageProvider>`][ssp] If provided, it is used to store
+  sessions independently of other applications.
+
+### application.callMethod(connection, interfaceName, methodName, args, callback)
+
+- `connection` [`<Connection>`][connection]
+- `interfaceName` [`<string>`][string]
+- `methodName` [`<string>`][string]
+- `args` [`<Array>`][array]
+- `callback` [`<Function>`][function]
+
+This method is called when handling incoming `'call'` message.
+
+### application.getMethods(interfaceName)
+
+- `interfaceName` [`<string>`][string] Name of the interface to inspect.
+- Returns: [`<string[]>`][string] Array of method names of the interface.
+
+This method is called when handling incoming `'inspect'` message.
+
+### application.handleEvent(connection, interfaceName, eventName, args)
+
+- `connection` [`<Connection>`][connection]
+- `interfaceName` [`<string>`][string]
+- `eventName` [`<string>`][string]
+- `args` [`<Array>`][array]
+
+This method is called when handling incoming `'event'` message.
+
+## jstp.createAppsIndex(applications)
+
+- `applications` [`<Application[]>`](#class-jstpapplication)
+- Returns: [`<Map>`][map] Created index.
+
+Create an index of applications from an array.
+
+[connection]: ./connection.md#class-jstpconnection
+[ssp]: ./session-storage-provider.md#interface-jstpsessionstorageprovider
+[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
+[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
+[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+[map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
+[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function

doc/api/auth-policy.md

@@ -0,0 +1,20 @@
+# AuthPolicy
+
+## Interface: jstp.AuthPolicy
+
+### authPolicy.authenticate(connection, application, strategy, credentials, callback)
+
+- `connection` [`<Connection>`][connection]
+- `application` [`<Application>`][application]
+- `strategy` [`<string>`][string]
+- `credentials` [`<Array>`][array]
+- `callback` [`<Function>`][function]
+  - `error` [`<Error>`][error]
+  - `username` [`<string>`][string]
+
+[connection]: ./connection.md#class-jstpconnection
+[application]: ./application.md#class-jstpapplication
+[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
+[array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
+[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
+[error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error

doc/api/client.md

@@ -1,36 +1,97 @@
 # Client
 
-- [Object: Client](#object-client)
-  - [Methods](#methods)
-    - [connectPolicy(application, connection, callback)](#connectpolicyapplication-connection-callback)
-  - [Properties](#properties)
-    - [application](#application)
-    - [heartbeatInterval](#heartbeatinterval)
+## Interface: jstp.Client
 
-## Object: Client
+Client object is used to specify client-side connection behavior.
 
-### Methods
+### client.connectPolicy(application, connection\[, session\], callback)
 
-#### connectPolicy(application, connection, callback)
+- `application` [`<string>`][string] | [`<Object>`][object]
+- `connection` [`<Connection>`][connection]
+- `session` [`<Session>`][session]
+- `callback` [`<Function>`][function]
+  - `error` [`<Error>`][error] | [`<null>`][null]
+  - `connection` [`<Connection>`][connection]
+  - `session` [`<Session>`][session]
 
-- application: `Application` — JSTP Application to be exposed over connection.
-- connection: [`Connection`](./connection.md#class-connection) —
-  JSTP Connection.
-- callback(error, connection)
-  - error: `Error`.
-  - connection: [`Connection`](./connection.md#class-connection) —
-    established connection.
+The `application` may be `'name'`, `'name@version'` or `{ name, version }`,
+where version must be a valid semver range.
 
-Optional,
-[`new SimpleConnectPolicy().connect`](./simple-connect-policy.md#connectapp-connection-callback)
-will be used if not provided.
+The `session` is passed to this function when the client is reconnecting to the
+existing session.
+In that case, implementations of this interface are not required to pass
+`session` argument to the `callback`.
 
-### Properties
+If this field is not set, [`new SimpleConnectPolicy().connect()`][scpconnect]
+is used.
 
-#### application
+It is also possible to set this field to an object with the `connect()` method
+having the same signature.
 
-- Type: `Application`.
+### client.application
 
-#### heartbeatInterval
+- [`<Application>`][application]
 
-- Type: `number`.
+Client-side application instance to be exposed over connection.
+
+If this field is not set, an [`Application`][application] `jstp@1.0.0` with an
+empty `api` is used.
+
+### client.heartbeatInterval
+
+- [`<number>`][number]
+
+Setting this field enables heartbeat.
+
+### client.session
+
+- [`<Session>`][session]
+
+Setting this field results in using the `'session'` authentication strategy
+when connecting, which can be used to reconnect to the existing session.
+
+### client.logger
+
+- [`<EventEmitter>`][eventemitter]
+
+Optional EventEmitter object to use for logging. If this field is not set,
+logging events are emitted on the connection object itself. Available logging
+events are listed in the [`Connection`][connection] class.
+
+### client.reconnector(connection, reconnectFn)
+
+- `connection` [`<Connection>`][connection]
+- `reconnectFn` [`<Function>`][function]
+  - `transport` [`<string>`][string] Optional argument, can be passed to switch
+    transport on reconnection.
+  - `...options` `<any>` Optional options to be passed to `transport.connect()`
+    function.
+  - `callback` [`<Function>`][function] Optional callback to be called after
+    finishing the reconnection attempt.
+
+When set, this function will be called after the connection is closed and can be
+used to reconnect to the same or different server by calling `reconnectFn` and
+providing options in the same way they are provided when connecting to the
+server.
+
+It is also possible to use another transport by providing its name as the first
+argument to `reconnectFn`. In case no `transport` and/or `options` were provided
+to `reconnectFn`, values from the previous successful connection attempt are to
+be used.
+
+To completely stop reconnecting do not call `reconnectFn` inside this function.
+
+In case this field is not set, default reconnector that provides exponential
+backoff functionality is used.
+
+[application]: ./application.md#class-jstpapplication
+[connection]: ./connection.md#class-jstpconnection
+[session]: ./session.md
+[scpconnect]: ./simple-connect-policy.md#simpleconnectpolicyconnectapp-connection-session-callback
+[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type
+[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type
+[object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
+[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
+[eventemitter]: http://nodejs.org/api/events.html#events_class_eventemitter
+[error]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
+[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type