Permalink
Browse files

[docs] Fix documentation for `local` flag (#2816)

  • Loading branch information...
1 parent 706ca2a commit b754cff2b415a8cbbf0f23c61824bcc69b078430 @darrachequesne darrachequesne committed on GitHub Jan 10, 2017
Showing with 36 additions and 27 deletions.
  1. +36 −27 docs/API.md
View
@@ -18,15 +18,17 @@
- [server.bind(engine)](#serverbindengine)
- [server.onconnection(socket)](#serveronconnectionsocket)
- [server.of(nsp)](#serverofnsp)
- - [server.emit(eventName[, ...args])](#serveremiteventname-args)
- [server.close([callback])](#serverclosecallback)
- [Class: Namespace](#namespace)
- [namespace.name](#namespacename)
- [namespace.connected](#namespaceconnected)
+ - [namespace.emit(eventName[, ...args])](#namespaceemiteventname-args)
- [namespace.clients(callback)](#namespaceclientscallback)
- [namespace.use(fn)](#namespaceusefn)
- [Event: 'connect'](#event-connect)
- [Event: 'connection'](#event-connect)
+ - [Flag: 'volatile'](#flag-volatile)
+ - [Flag: 'local'](#flag-local)
- [Class: Socket](#socket)
- [socket.id](#socketid)
- [socket.rooms](#socketrooms)
@@ -44,8 +46,7 @@
- [socket.compress(value)](#socketcompressvalue)
- [socket.disconnect(close)](#socketdisconnectclose)
- [Flag: 'broadcast'](#flag-broadcast)
- - [Flag: 'volatile'](#flag-volatile)
- - [Flag: 'local'](#flag-local)
+ - [Flag: 'volatile'](#flag-volatile-1)
- [Event: 'disconnect'](#event-disconnect)
- [Event: 'error'](#event-error)
- [Event: 'disconnecting'](#event-disconnecting)
@@ -202,19 +203,6 @@ Advanced use only. Creates a new `socket.io` client from the incoming engine.io
Initializes and retrieves the given `Namespace` by its pathname identifier `nsp`. If the namespace was already initialized it returns it immediately.
-#### server.emit(eventName[, ...args])
-
- - `eventName` _(String)_
- - `args`
-
-Emits an event to all connected clients. The following two are equivalent:
-
-```js
-var io = require('socket.io')();
-io.sockets.emit('an event sent to all connected clients');
-io.emit('an event sent to all connected clients');
-```
-
#### server.close([callback])
- `callback` _(Function)_
@@ -254,6 +242,22 @@ The namespace identifier property.
The hash of `Socket` objects that are connected to this namespace, indexed by `id`.
+#### namespace.emit(eventName[, ...args])
+
+ - `eventName` _(String)_
+ - `args`
+
+Emits an event to all connected clients. The following two are equivalent:
+
+```js
+var io = require('socket.io')();
+
+io.emit('an event sent to all connected clients'); // main namespace
+
+var chat = io.of('/chat');
+chat.emit('an event sent to all connected clients in chat namespace');
+```
+
#### namespace.clients(callback)
- `callback` _(Function)_
@@ -314,6 +318,22 @@ Fired upon a reconnection attempt error.
Synonym of [Event: 'connect'](#event-connect).
+#### Flag: 'volatile'
+
+Sets a modifier for a subsequent event emission that the event data may be lost if the clients are not ready to receive messages (because of network slowness or other issues, or because they’re connected through long polling and is in the middle of a request-response cycle).
+
+```js
+io.volatile.emit('an event', { some: 'data' }); // the clients may or may not receive it
+```
+
+#### Flag: 'local'
+
+Sets a modifier for a subsequent event emission that the event data will only be _broadcast_ to the current node (when the [Redis adapter](https://github.com/socketio/socket.io-redis) is used).
+
+```js
+io.local.emit('an event', { some: 'data' });
+```
+
### Socket
A `Socket` is the fundamental class for interacting with browser clients. A `Socket` belongs to a certain `Namespace` (by default `/`) and uses an underlying `Client` to communicate.
@@ -524,17 +544,6 @@ io.on('connection', function(socket){
});
```
-#### Flag: 'local'
-
-Sets a modifier for a subsequent event emission that the event data will only be _broadcast_ to the current node (when the [Redis adapter](https://github.com/socketio/socket.io-redis) is used).
-
-```js
-var io = require('socket.io')();
-io.on('connection', function(socket){
- socket.to('hello').local.emit('an event', { some: 'data' });
-});
-```
-
#### Event: 'disconnect'
- `reason` _(String)_ the reason of the disconnection (either client or server-side)

0 comments on commit b754cff

Please sign in to comment.