updatd readme

README.md

@@ -131,6 +131,189 @@ var io = require('socket.io')(3000);
 io.use(a);
 ```
 
+# API
+
+## Router
+
+Get the `Router` class.
+
+```javascript
+var Router = require('socket.io-events');
+```
+
+The `use` and `on` methods are equivalent.  They also can be chained.
+
+```javascript
+var router = Router()
+  .use(function (sock, args, next) { })
+  .use(function (sock, args, next) { })
+  .use(function (sock, args, next) { });
+```
+
+### Router#()
+
+Make a `Router` instance
+
+```javascript
+var router = Router();
+```
+
+### Router#use(fn:Function, ...)
+
+Attach a `function` to the router.
+
+```javascript
+router.use(function (sock, args, next) {
+  //do something!
+  next();
+});
+```
+
+You can pass in multiple `function`s.
+
+```javascript
+var a = function (sock, args, next) { next() };
+var b = function (sock, args, next) { next() };
+var c = function (sock, args, next) { next() };
+
+router.use(a,b,c); 
+```
+
+You can pass in a function that accepts an `Error` object.
+
+```javascript
+router.use(function (err, sock, args, next) {
+  console.error(err);
+  
+  //calling next(err) will invoke the next error handler.
+  //to resume operation just call next()
+  next(err);
+});
+```
+
+### Router#use(event:String, fn:Function, ...)
+
+Bind the `function` to the `event`.
+
+```javascript
+router.use('chat', function (sock, args, next) {
+  assert.equal(args[0], 'chat');
+  args[1] = args[1].length > 128 ? args[1].slice(0, 125) + '...' : args[1];
+  next();
+});
+```
+
+You can also pass in multiple `function`s for handling the `event`.
+
+```javascript
+var chop = function (sock, args, next) { next() };
+var clean = function (sock, args, next) { next() };
+var pretty = function (sock, args, next) { next() };
+
+router.use('chat', chop, clean, pretty);
+```
+
+### Router#use(router:Router, ...)
+
+You can attach another `Router` instance to your `Router` instance.
+
+```javascript
+var another = Router();
+another.use(function (sock, args, next) { next(); });
+
+router.use(another);
+```
+
+Attach multiple routers in a single call.
+
+```javascript
+var foo = Router();
+foo.use(function (sock, args, next) { next(); });
+
+var bar = Router();
+bar.use(function (sock, args, next) { next(); });
+
+var baz = Router();
+baz.use(function (sock, args, next) { next(); });
+
+router.use(foo, bar, baz);
+```
+
+### Router#use(name:String, router:Router, ...)
+
+Just like attaching a `function` to the router given the `event`.  You can attach `Router`
+instance as well to the `event`.
+
+```javascript
+var foo = Router();
+foo.use(function (sock, args, next) { next(); });
+
+router.use('some event', foo);
+```
+
+Attach multiple routers in a single call to the `event` too.
+
+```javascript
+var foo = Router();
+foo.use(function (sock, args, next) { next(); });
+
+var bar = Router();
+bar.use(function (sock, args, next) { next(); });
+
+var baz = Router();
+baz.use(function (sock, args, next) { next(); });
+
+router.use('some event', foo, bar, baz);
+```
+
+### Router#use(fns:Array, ...)
+
+Attach an `Array` of `Fuction`'s or `Router` instances, or an `Array` or `Array`s .
+
+```javascript
+var middleware = [
+  function (sock, args, next) { next(); },
+  [
+    function (sock, args, next) { next(); },
+    Router().use(function (sock, args, next) { next(); }),
+    function (sock, args, next) { next(); },
+  ],
+  Router().use(function (sock, args, next) { next(); })
+];
+
+var errHandler = function (err, sock, args, next) { next(err); } 
+
+router.use(middleware, errHandler);
+```
+
+### Router#use(name:String, fns:Array, ...)
+
+Attach everything to an event.
+
+```javascript
+var middleware = [
+  function (sock, args, next) { next(); },
+  [
+    function (sock, args, next) { next(); },
+    Router().use(function (sock, args, next) { next(); }),
+    function (sock, args, next) { next(); },
+  ],
+  Router().use(function (sock, args, next) { next(); })
+];
+
+var errHandler = function (err, sock, args, next) { next(err); } 
+
+router.use('only this event', middleware, errHandler);
+```
+
+### Router#on(...)
+
+This is an alias to to the `use` method.  It does the same thing.
+
+```javascript
+router.on(function (sock, args, next) { next() });
+```
+
 # Installation and Environment Setup
 
 Install node.js (See download and install instructions here: http://nodejs.org/).