[docs] Update documentation (#1124)

docs/API.md

@@ -3,7 +3,15 @@
 
 - [IO](#io)
   - [io.protocol](#ioprotocol)
-  - [io(url[, options])](#iourl-options)
+  - [io([url][, options])](#iourl-options)
+    - [Initialization examples](#initialization-examples)
+      - [With multiplexing](#with-multiplexing)
+      - [With custom path](#with-custom-path)
+      - [With query parameters](#with-query-parameters)
+      - [With query option](#with-query-option)
+      - [With extraHeaders](#with-extraheaders)
+      - [With websocket transport only](#with-websocket-transport-only)
+      - [With a custom parser](#with-a-custom-parser)
   - [Class: io.Manager](#manager)
     - [new Manager(url[, options])](#new-managerurl-options)
     - [manager.reconnection([value])](#managerreconnectionvalue)
@@ -55,10 +63,11 @@ Exposed as the `io` namespace in the standalone build, or the result of calling
 
 The protocol revision number.
 
-#### io(url[, options])
+#### io([url][, options])
 
-  - `url` _(String)_
+  - `url` _(String)_ (defaults to `window.location`)
   - `options` _(Object)_
+    - `forceNew` _(Boolean)_ whether to reuse an existing connection
   - **Returns** `Socket`
 
 Creates a new `Manager` for the given URL, and attempts to reuse an existing `Manager` for subsequent calls, unless the `multiplex` option is passed with `false`. Passing this option is the equivalent of passing `'force new connection': true` or `forceNew: true`.
@@ -69,6 +78,163 @@ Query parameters can also be provided, either with the `query` option or directl
 
 See [new Manager(url[, options])](#new-managerurl-options) for available `options`.
 
+#### Initialization examples
+
+##### With multiplexing
+
+By default, a single connection is used when connecting to different namespaces (to minimize resources):
+
+```js
+const socket = io();
+const adminSocket = io('/admin');
+// a single connection will be established
+```
+
+That behaviour can be disabled with the `forceNew` option:
+
+```js
+const socket = io();
+const adminSocket = io('/admin', { forceNew: true });
+// will create two distinct connections
+```
+
+Note: reusing the same namespace will also create two connections
+
+```js
+const socket = io();
+const socket2 = io();
+// will also create two distinct connections
+```
+
+##### With custom `path`
+
+```js
+const socket = io('http://localhost', {
+  path: '/myownpath'
+});
+
+// server-side
+const io = require('socket.io')({
+  path: '/myownpath'
+});
+```
+
+The request URLs will look like: `localhost/myownpath/?EIO=3&transport=polling&sid=<id>`
+
+```js
+const socket = io('http://localhost/admin', {
+  path: '/mypath'
+});
+```
+
+Here, the socket connects to the `admin` namespace, with the custom path `mypath`.
+
+The request URLs will look like: `localhost/mypath/?EIO=3&transport=polling&sid=<id>` (the namespace is sent as part of the payload).
+
+##### With query parameters
+
+```js
+const socket = io('http://localhost?token=abc');
+
+// server-side
+const io = require('socket.io')();
+
+// middleware
+io.use((socket, next) => {
+  let token = socket.handshake.query.token;
+  if (isValid(token)) {
+    return next();
+  }
+  return next(new Error('authentication error'));
+});
+
+// then
+io.on('connection', (socket) => {
+  let token = socket.handshake.query.token;
+  // ...
+});
+```
+
+##### With query option
+
+```js
+const socket = io({
+  query: {
+    token: 'cde'
+  }
+});
+```
+
+The query content can also be updated on reconnection:
+
+```js
+socket.on('reconnect_attempt', () => {
+  socket.io.opts.query = {
+    token: 'fgh'
+  }
+});
+```
+
+##### With `extraHeaders`
+
+Note: will only work if `polling` transport is enabled (which is the default)
+
+```js
+const socket = io({
+  transportOptions: {
+    polling: {
+      extraHeaders: {
+        'x-clientid': 'abc'
+      }
+    }
+  }
+});
+
+// server-side
+const io = require('socket.io')();
+
+// middleware
+io.use((socket, next) => {
+  let clientId = socket.handshake.headers['x-clientid'];
+  if (isValid(clientId)) {
+    return next();
+  }
+  return next(new Error('authentication error'));
+});
+```
+
+##### With `websocket` transport only
+
+By default, a long-polling connection is established first, then upgraded to "better" transports (like WebSocket). If you like to live dangerously, this part can be skipped:
+
+```js
+const socket = io({
+  transports: ['websocket']
+});
+
+// on reconnection, reset the transports option, as the Websocket
+// connection may have failed (caused by proxy, firewall, browser, ...)
+socket.on('reconnect_attempt', () => {
+  socket.io.opts.transports = ['polling', 'websocket'];
+});
+```
+
+##### With a custom parser
+
+The default [parser](https://github.com/socketio/socket.io-parser) promotes compatibility (support for `Blob`, `File`, binary check) at the expense of performance. A custom parser can be provided to match the needs of your application. Please see the example [here](https://github.com/socketio/socket.io/tree/master/examples/custom-parsers).
+
+```js
+const parser = require('socket.io-msgpack-parser'); // or require('socket.io-json-parser')
+const socket = io({
+  parser: parser
+});
+
+// the server-side must have the same parser, to be able to communicate
+const io = require('socket.io')({
+  parser: parser
+});
+```
+
 ### Manager
 
 #### new Manager(url[, options])
@@ -90,6 +256,7 @@ See [new Manager(url[, options])](#new-managerurl-options) for available `option
     - `autoConnect` _(Boolean)_ by setting this false, you have to call `manager.open`
       whenever you decide it's appropriate
     - `query` _(Object)_: additional query parameters that are sent when connecting a namespace (then found in `socket.handshake.query` object on the server-side)
+    - `parser` _(Parser)_: the parser to use. Defaults to an instance of the `Parser` that ships with socket.io. See [socket.io-parser](https://github.com/socketio/socket.io-parser).
   - **Returns** `Manager`
 
 The `options` are also passed to `engine.io-client` upon initialization of the underlying `Socket`. See the available `options` [here](https://github.com/socketio/engine.io-client#methods).
@@ -218,7 +385,24 @@ socket.on('connect', function(){
 
   - **Returns** `Socket`
 
-Opens the socket.
+Manually opens the socket.
+
+```js
+const socket = io({
+  autoConnect: false
+});
+
+// ...
+socket.open();
+```
+
+It can also be used to manually reconnect:
+
+```js
+socket.on('disconnect', () => {
+  socket.open();
+});
+```
 
 #### socket.connect()